Skip to content

Self-documentation resources output

contexts, taxonomies and the child resources of taxonomies return information on the contexts available for document analysis and the taxonomies available for document classification. See the format of the resource endpoints on page.

contexts

The contexts resource returns a JSON object like this:

{
    "contexts": [
        {
            "description": "Standard context",
            "languages": [
                {
                    "analyses": [
                        "disambiguation",
                        "relevants",
                        "entities",
                        "sentiment",
                        "relations"
                    ],
                    "code": "en",
                    "name": "English"
                },
                {
                    "analyses": [
                        "disambiguation",
                        "relevants",
                        "entities",
                        "relations"
                    ],
                    "code": "es",
                    "name": "Spanish"
                },
                {
                    "analyses": [
                        "disambiguation",
                        "relevants",
                        "entities",
                        "relations"
                    ],
                    "code": "fr",
                    "name": "French"
                },
                {
                    "analyses": [
                        "disambiguation",
                        "relevants",
                        "entities",
                        "relations"
                    ],
                    "code": "de",
                    "name": "German"
                },
                {
                    "analyses": [
                        "disambiguation",
                        "relevants",
                        "entities",
                        "relations"
                    ],
                    "code": "it",
                    "name": "Italian"
                }
            ],
            "name": "standard"
        }
    ]
}

The contexts array contains one object for each context.
The name property is the exact name that must be used in the endpoint of analysis resources.

The languages array documents the context's capabilities in terms of the analyses available for each of the supported languages.
code id the ISO 639-1 language code, analyses is an array listing available analyses for the language. The value of the analyses are the exact names that must be used in the endpoint of partial analysis resources.

taxonomies

The taxonomies resource returns a JSON object like this:

{
    "taxonomies": [
        {
            "description": "The iptc document classification resource classifies texts based on the IPTC Media Topics taxonomy",
            "languages": [
                {
                    "code": "en",
                    "name": "English"
                },
                {
                    "code": "es",
                    "name": "Spanish"
                },
                {
                    "code": "fr",
                    "name": "French"
                },
                {
                    "code": "de",
                    "name": "German"
                },
                {
                    "code": "it",
                    "name": "Italian"
                }
            ],
            "name": "iptc"
        },
        {
            "contract": "https://github.com/therealexpertai/nlapi-openapi-specification/blob/master/geotax.yaml",
            "description": "The geotax document classification resource recognizes geographic places cited in the text and returns corresponding countries' names. In addition, when requested with a specific query-string parameter, it returns extra-data containing equivalent GeoJSON objects. See the specific OpenAPI document (https://github.com/therealexpertai/nlapi-openapi-specification/blob/master/geotax.yaml) for information about the way to obtain and interpret GeoJSON data.",
            "languages": [
                {
                    "code": "en",
                    "name": "English"
                },
                {
                    "code": "es",
                    "name": "Spanish"
                },
                {
                    "code": "fr",
                    "name": "French"
                },
                {
                    "code": "de",
                    "name": "German"
                },
                {
                    "code": "it",
                    "name": "Italian"
                }
            ],
            "name": "geotax"
        }
    ]
}

The taxonomies array contains one object for each taxonomy.
The name property is the exact name that must be used in the endpoint of classification resources and also in the endpoint of taxonomy child resources.

The languages array lists the languages for which the taxonomy is available.
code id the ISO 639-1 language code.

taxonomies child resources

taxonomies/{taxonomy}/{language} resources return the categories' ​tree ​for a given taxonomy in a given language. Their output is a JSON object like this:

{
    "success": true,
    "data": [
        {
            "namespace": "cat-geo_en_1.0",
            "taxonomy": [
                {
                    "id": "GEO_TAX",
                    "label": "Geo Taxonomy",
                    "categories": [
                        {
                            "id": "001.",
                            "label": "Afghanistan"
                        },
                        {
                            "id": "002.",
                            "label": "Albania"
                        },
                        {
                            "id": "003.",
                            "label": "Algeria"
                        },
                        {
                            "id": "004.",
                            "label": "Andorra"
                        },
                        {
                            "id": "005.",
                            "label": "Angola"
                        },
                        {
                            "id": "006.",
                            "label": "Antigua and Barbuda"
                        },
                        {
                            "id": "007.",
                            "label": "Argentina"
                        },
                        {
                            "id": "008.",
                            "label": "Armenia"
                        },
                        {
                            "id": "009.",
                            "label": "Australia"
                        },
                        {
                            "id": "010.",
                            "label": "Austria"
                        },
                        {
                            "id": "011.",
                            "label": "Azerbaijan"
                        },
                        {
                            "id": "012.",
                            "label": "Bahamas"
                        },
                        {
                            "id": "013.",
                            "label": "Bahrain"
                        },
                        {
                            "id": "014.",
                            "label": "Bangladesh"
                        },
                        {
                            "id": "015.",
                            "label": "Barbados"
                        },
                        {
                            "id": "016.",
                            "label": "Belarus"
                        },
                        {
                            "id": "017.",
                            "label": "Belgium"
                        },
                        {
                            "id": "018.",
                            "label": "Belize"
                        },
                        {
                            "id": "019.",
                            "label": "Benin"
                        },
                        {
                            "id": "020.",
                            "label": "Bhutan"
                        },
                        {
                            "id": "021.",
                            "label": "Bolivia"
                        },
                        {
                            "id": "022.",
                            "label": "Bosnia-Herzegovina"
                        },
                        {
                            "id": "023.",
                            "label": "Botswana"
                        },
                        {
                            "id": "024.",
                            "label": "Brazil"
                        },
                        {
                            "id": "025.",
                            "label": "Brunei"
                        },
                        {
                            "id": "026.",
                            "label": "Bulgaria"
                        },
                        {
                            "id": "027.",
                            "label": "Burkina Faso"
                        },
                        {
                            "id": "028.",
                            "label": "Burundi"
                        },
                        {
                            "id": "029.",
                            "label": "Cambodia"
                        },
                        {
                            "id": "030.",
                            "label": "Cameroon"
                        },
                        {
                            "id": "031.",
                            "label": "Canada"
                        },
                        {
                            "id": "032.",
                            "label": "Cape Verde"
                        },
                        {
                            "id": "033.",
                            "label": "Central African Republic"
                        },
                        {
                            "id": "034.",
                            "label": "Chad"
                        },
                        {
                            "id": "035.",
                            "label": "Chile"
                        },
                        {
                            "id": "036.",
                            "label": "China"
                        },
                        {
                            "id": "037.",
                            "label": "Colombia"
                        },
                        {
                            "id": "038.",
                            "label": "Comoros"
                        },
                        {
                            "id": "039.",
                            "label": "Costa Rica"
                        },
                        {
                            "id": "040.",
                            "label": "Côte d'Ivoire"
                        },
                        {
                            "id": "041.",
                            "label": "Croatia"
                        },
                        {
                            "id": "042.",
                            "label": "Cuba"
                        },
                        {
                            "id": "043.",
                            "label": "Cyprus"
                        },
                        {
                            "id": "044.",
                            "label": "Czech Republic"
                        },
                        {
                            "id": "045.",
                            "label": "Democratic Republic of Congo"
                        },
                        {
                            "id": "046.",
                            "label": "Denmark"
                        },
                        {
                            "id": "047.",
                            "label": "Djibouti"
                        },
                        {
                            "id": "048.",
                            "label": "Dominica"
                        },
                        {
                            "id": "049.",
                            "label": "Dominican Republic"
                        },
                        {
                            "id": "050.",
                            "label": "East Timor"
                        },
                        {
                            "id": "051.",
                            "label": "Ecuador"
                        },
                        {
                            "id": "052.",
                            "label": "Egypt"
                        },
                        {
                            "id": "053.",
                            "label": "El Salvador"
                        },
                        {
                            "id": "054.",
                            "label": "Equatorial Guinea"
                        },
                        {
                            "id": "055.",
                            "label": "Eritrea"
                        },
                        {
                            "id": "056.",
                            "label": "Estonia"
                        },
                        {
                            "id": "057.",
                            "label": "Ethiopia"
                        },
                        {
                            "id": "058.",
                            "label": "Fiji"
                        },
                        {
                            "id": "059.",
                            "label": "Finland"
                        },
                        {
                            "id": "060.",
                            "label": "France"
                        },
                        {
                            "id": "061.",
                            "label": "Gabon"
                        },
                        {
                            "id": "062.",
                            "label": "Gambia"
                        },
                        {
                            "id": "063.",
                            "label": "Georgia"
                        },
                        {
                            "id": "064.",
                            "label": "Germany"
                        },
                        {
                            "id": "065.",
                            "label": "Ghana"
                        },
                        {
                            "id": "066.",
                            "label": "Greece"
                        },
                        {
                            "id": "067.",
                            "label": "Grenada"
                        },
                        {
                            "id": "068.",
                            "label": "Guatemala"
                        },
                        {
                            "id": "069.",
                            "label": "Guinea"
                        },
                        {
                            "id": "070.",
                            "label": "Guinea-Bissau"
                        },
                        {
                            "id": "071.",
                            "label": "Guyana"
                        },
                        {
                            "id": "072.",
                            "label": "Haiti"
                        },
                        {
                            "id": "073.",
                            "label": "Honduras"
                        },
                        {
                            "id": "074.",
                            "label": "Hungary"
                        },
                        {
                            "id": "075.",
                            "label": "Iceland"
                        },
                        {
                            "id": "076.",
                            "label": "India"
                        },
                        {
                            "id": "077.",
                            "label": "Indonesia"
                        },
                        {
                            "id": "078.",
                            "label": "Iran"
                        },
                        {
                            "id": "079.",
                            "label": "Iraq"
                        },
                        {
                            "id": "080.",
                            "label": "Ireland"
                        },
                        {
                            "id": "081.",
                            "label": "Israel"
                        },
                        {
                            "id": "082.",
                            "label": "Italy"
                        },
                        {
                            "id": "083.",
                            "label": "Jamaica"
                        },
                        {
                            "id": "084.",
                            "label": "Japan"
                        },
                        {
                            "id": "085.",
                            "label": "Jordan"
                        },
                        {
                            "id": "086.",
                            "label": "Kazakhstan"
                        },
                        {
                            "id": "087.",
                            "label": "Kenya"
                        },
                        {
                            "id": "088.",
                            "label": "Kiribati"
                        },
                        {
                            "id": "089.",
                            "label": "Kosovo"
                        },
                        {
                            "id": "090.",
                            "label": "Kuwait"
                        },
                        {
                            "id": "091.",
                            "label": "Kyrgyzstan"
                        },
                        {
                            "id": "092.",
                            "label": "Laos"
                        },
                        {
                            "id": "093.",
                            "label": "Latvia"
                        },
                        {
                            "id": "094.",
                            "label": "Lebanon"
                        },
                        {
                            "id": "095.",
                            "label": "Lesotho"
                        },
                        {
                            "id": "096.",
                            "label": "Liberia"
                        },
                        {
                            "id": "097.",
                            "label": "Libya"
                        },
                        {
                            "id": "098.",
                            "label": "Liechtenstein"
                        },
                        {
                            "id": "099.",
                            "label": "Lithuania"
                        },
                        {
                            "id": "100.",
                            "label": "Luxemburg"
                        },
                        {
                            "id": "101.",
                            "label": "Macedonia"
                        },
                        {
                            "id": "102.",
                            "label": "Madagascar"
                        },
                        {
                            "id": "103.",
                            "label": "Malawi"
                        },
                        {
                            "id": "104.",
                            "label": "Malaysia"
                        },
                        {
                            "id": "105.",
                            "label": "Maldives"
                        },
                        {
                            "id": "106.",
                            "label": "Mali"
                        },
                        {
                            "id": "107.",
                            "label": "Malta"
                        },
                        {
                            "id": "108.",
                            "label": "Marshall Islands"
                        },
                        {
                            "id": "109.",
                            "label": "Mauritania"
                        },
                        {
                            "id": "110.",
                            "label": "Mauritius"
                        },
                        {
                            "id": "111.",
                            "label": "Mexico"
                        },
                        {
                            "id": "112.",
                            "label": "Micronesia"
                        },
                        {
                            "id": "113.",
                            "label": "Moldova"
                        },
                        {
                            "id": "114.",
                            "label": "Monaco"
                        },
                        {
                            "id": "115.",
                            "label": "Mongolia"
                        },
                        {
                            "id": "116.",
                            "label": "Montenegro"
                        },
                        {
                            "id": "117.",
                            "label": "Morocco"
                        },
                        {
                            "id": "118.",
                            "label": "Mozambique"
                        },
                        {
                            "id": "119.",
                            "label": "Myanmar"
                        },
                        {
                            "id": "120.",
                            "label": "Namibia"
                        },
                        {
                            "id": "121.",
                            "label": "Nauru"
                        },
                        {
                            "id": "122.",
                            "label": "Nepal"
                        },
                        {
                            "id": "123.",
                            "label": "Netherlands"
                        },
                        {
                            "id": "124.",
                            "label": "New Zealand"
                        },
                        {
                            "id": "125.",
                            "label": "Nicaragua"
                        },
                        {
                            "id": "126.",
                            "label": "Niger"
                        },
                        {
                            "id": "127.",
                            "label": "Nigeria"
                        },
                        {
                            "id": "128.",
                            "label": "North Korea"
                        },
                        {
                            "id": "129.",
                            "label": "Norway"
                        },
                        {
                            "id": "130.",
                            "label": "Oman"
                        },
                        {
                            "id": "131.",
                            "label": "Pakistan"
                        },
                        {
                            "id": "132.",
                            "label": "Palau"
                        },
                        {
                            "id": "133.",
                            "label": "Panama"
                        },
                        {
                            "id": "134.",
                            "label": "Papua New Guinea"
                        },
                        {
                            "id": "135.",
                            "label": "Paraguay"
                        },
                        {
                            "id": "136.",
                            "label": "Peru"
                        },
                        {
                            "id": "137.",
                            "label": "Philippines"
                        },
                        {
                            "id": "138.",
                            "label": "Poland"
                        },
                        {
                            "id": "139.",
                            "label": "Portugal"
                        },
                        {
                            "id": "140.",
                            "label": "Qatar"
                        },
                        {
                            "id": "141.",
                            "label": "Republic of Congo"
                        },
                        {
                            "id": "142.",
                            "label": "Romania"
                        },
                        {
                            "id": "143.",
                            "label": "Russia"
                        },
                        {
                            "id": "144.",
                            "label": "Rwanda"
                        },
                        {
                            "id": "145.",
                            "label": "Saint Kitts and Nevis"
                        },
                        {
                            "id": "146.",
                            "label": "Saint Lucia"
                        },
                        {
                            "id": "147.",
                            "label": "Saint Vincent and the Grenadines"
                        },
                        {
                            "id": "148.",
                            "label": "Samoa"
                        },
                        {
                            "id": "149.",
                            "label": "San Marino"
                        },
                        {
                            "id": "150.",
                            "label": "São Tomé and Príncipe"
                        },
                        {
                            "id": "151.",
                            "label": "Saudi Arabia"
                        },
                        {
                            "id": "152.",
                            "label": "Senegal"
                        },
                        {
                            "id": "153.",
                            "label": "Serbia"
                        },
                        {
                            "id": "154.",
                            "label": "Seychelles"
                        },
                        {
                            "id": "155.",
                            "label": "Sierra Leone"
                        },
                        {
                            "id": "156.",
                            "label": "Singapore"
                        },
                        {
                            "id": "157.",
                            "label": "Slovakia"
                        },
                        {
                            "id": "158.",
                            "label": "Slovenia"
                        },
                        {
                            "id": "159.",
                            "label": "Solomon Islands"
                        },
                        {
                            "id": "160.",
                            "label": "Somalia"
                        },
                        {
                            "id": "161.",
                            "label": "South Africa"
                        },
                        {
                            "id": "162.",
                            "label": "South Korea"
                        },
                        {
                            "id": "163.",
                            "label": "Spain"
                        },
                        {
                            "id": "164.",
                            "label": "Sri Lanka"
                        },
                        {
                            "id": "165.",
                            "label": "Sudan"
                        },
                        {
                            "id": "166.",
                            "label": "Suriname"
                        },
                        {
                            "id": "167.",
                            "label": "Swaziland"
                        },
                        {
                            "id": "168.",
                            "label": "Sweden"
                        },
                        {
                            "id": "169.",
                            "label": "Switzerland"
                        },
                        {
                            "id": "170.",
                            "label": "Syria"
                        },
                        {
                            "id": "171.",
                            "label": "Tajikistan"
                        },
                        {
                            "id": "172.",
                            "label": "Tanzania"
                        },
                        {
                            "id": "173.",
                            "label": "Thailand"
                        },
                        {
                            "id": "174.",
                            "label": "Togo"
                        },
                        {
                            "id": "175.",
                            "label": "Tonga"
                        },
                        {
                            "id": "176.",
                            "label": "Trinidad and Tobago"
                        },
                        {
                            "id": "177.",
                            "label": "Tunisia"
                        },
                        {
                            "id": "178.",
                            "label": "Turkey"
                        },
                        {
                            "id": "179.",
                            "label": "Turkmenistan"
                        },
                        {
                            "id": "180.",
                            "label": "Tuvalu"
                        },
                        {
                            "id": "181.",
                            "label": "Uganda"
                        },
                        {
                            "id": "182.",
                            "label": "Ukraine"
                        },
                        {
                            "id": "183.",
                            "label": "United Arab Emirates"
                        },
                        {
                            "id": "184.",
                            "label": "United Kingdom",
                            "categories": [
                                {
                                    "id": "18401.",
                                    "label": "England"
                                },
                                {
                                    "id": "18402.",
                                    "label": "Northern Ireland"
                                },
                                {
                                    "id": "18403.",
                                    "label": "Scotland"
                                },
                                {
                                    "id": "18404.",
                                    "label": "Wales"
                                }
                            ]
                        },
                        {
                            "id": "185.",
                            "label": "United States of America",
                            "categories": [
                                {
                                    "id": "18501.",
                                    "label": "Alabama"
                                },
                                {
                                    "id": "18502.",
                                    "label": "Alaska"
                                },
                                {
                                    "id": "18503.",
                                    "label": "Arizona"
                                },
                                {
                                    "id": "18504.",
                                    "label": "Arkansas"
                                },
                                {
                                    "id": "18505.",
                                    "label": "California"
                                },
                                {
                                    "id": "18506.",
                                    "label": "Colorado"
                                },
                                {
                                    "id": "18507.",
                                    "label": "Connecticut"
                                },
                                {
                                    "id": "18508.",
                                    "label": "Delaware"
                                },
                                {
                                    "id": "18509.",
                                    "label": "District of Columbia"
                                },
                                {
                                    "id": "18510.",
                                    "label": "Florida"
                                },
                                {
                                    "id": "18511.",
                                    "label": "Georgia"
                                },
                                {
                                    "id": "18512.",
                                    "label": "Hawaii"
                                },
                                {
                                    "id": "18513.",
                                    "label": "Idaho"
                                },
                                {
                                    "id": "18514.",
                                    "label": "Illinois"
                                },
                                {
                                    "id": "18515.",
                                    "label": "Indiana"
                                },
                                {
                                    "id": "18516.",
                                    "label": "Iowa"
                                },
                                {
                                    "id": "18517.",
                                    "label": "Kansas"
                                },
                                {
                                    "id": "18518.",
                                    "label": "Kentucky"
                                },
                                {
                                    "id": "18519.",
                                    "label": "Louisiana"
                                },
                                {
                                    "id": "18520.",
                                    "label": "Maine"
                                },
                                {
                                    "id": "18521.",
                                    "label": "Maryland"
                                },
                                {
                                    "id": "18522.",
                                    "label": "Massachusetts"
                                },
                                {
                                    "id": "18523.",
                                    "label": "Michigan"
                                },
                                {
                                    "id": "18524.",
                                    "label": "Minnesota"
                                },
                                {
                                    "id": "18525.",
                                    "label": "Mississippi"
                                },
                                {
                                    "id": "18526.",
                                    "label": "Missouri"
                                },
                                {
                                    "id": "18527.",
                                    "label": "Montana"
                                },
                                {
                                    "id": "18528.",
                                    "label": "Nebraska"
                                },
                                {
                                    "id": "18529.",
                                    "label": "Nevada"
                                },
                                {
                                    "id": "18530.",
                                    "label": "New Hampshire"
                                },
                                {
                                    "id": "18531.",
                                    "label": "New Jersey"
                                },
                                {
                                    "id": "18532.",
                                    "label": "New Mexico"
                                },
                                {
                                    "id": "18533.",
                                    "label": "New York State"
                                },
                                {
                                    "id": "18534.",
                                    "label": "North Carolina"
                                },
                                {
                                    "id": "18535.",
                                    "label": "North Dakota"
                                },
                                {
                                    "id": "18536.",
                                    "label": "Ohio"
                                },
                                {
                                    "id": "18537.",
                                    "label": "Oklahoma"
                                },
                                {
                                    "id": "18538.",
                                    "label": "Oregon"
                                },
                                {
                                    "id": "18539.",
                                    "label": "Pennsylvania"
                                },
                                {
                                    "id": "18540.",
                                    "label": "Rhode Island"
                                },
                                {
                                    "id": "18541.",
                                    "label": "South Carolina"
                                },
                                {
                                    "id": "18542.",
                                    "label": "South Dakota"
                                },
                                {
                                    "id": "18543.",
                                    "label": "Tennessee"
                                },
                                {
                                    "id": "18544.",
                                    "label": "Texas"
                                },
                                {
                                    "id": "18545.",
                                    "label": "Utah"
                                },
                                {
                                    "id": "18546.",
                                    "label": "Vermont"
                                },
                                {
                                    "id": "18547.",
                                    "label": "Virginia"
                                },
                                {
                                    "id": "18548.",
                                    "label": "Washington State"
                                },
                                {
                                    "id": "18549.",
                                    "label": "West Virginia"
                                },
                                {
                                    "id": "18550.",
                                    "label": "Wisconsin"
                                },
                                {
                                    "id": "18551.",
                                    "label": "Wyoming"
                                }
                            ]
                        },
                        {
                            "id": "186.",
                            "label": "Uruguay"
                        },
                        {
                            "id": "187.",
                            "label": "Uzbekistan"
                        },
                        {
                            "id": "188.",
                            "label": "Vanuatu"
                        },
                        {
                            "id": "189.",
                            "label": "Vatican City"
                        },
                        {
                            "id": "190.",
                            "label": "Venezuela"
                        },
                        {
                            "id": "191.",
                            "label": "Vietnam"
                        },
                        {
                            "id": "192.",
                            "label": "Yemen"
                        },
                        {
                            "id": "193.",
                            "label": "Zambia"
                        },
                        {
                            "id": "194.",
                            "label": "Zimbabwe"
                        }
                    ]
                }
            ]
        }
    ]
}

The Boolean property success indicates that processing was successful while the data array contains the results.

data contains one object for each categories' tree because, in theory, a taxonomy can have more than one.
namespace is the name of the software module containing the taxonomy, while taxonomy is an array of possibly nested categories.

Each category is an object with these properties:

  • id: category identifier
  • label: category label
  • categories: sub-categories

There can be several categories with the same value for id in the categories' tree, but there cannot be two or more categories with the same id having the same parent category.