Self-documentation resources output
Overview
contexts, taxonomies, detectors and the child resources of taxonomies are API self-documentation resources they return information on the contexts available for document analysis, the taxonomies available for document classification and the detectors available for information detection. See the format of the resources' endpoints in the reference 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 resources classify 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-w-geojson.yaml",
"description": "The geotax document classification resources recognize geographic places cited in the text and return corresponding countries' names. In addition, when requested with a specific query-string parameter, they return extra-data containing equivalent GeoJSON objects. Refer to the specific OpenAPI document (https://github.com/therealexpertai/nlapi-openapi-specification/blob/master/geotax-w-geojson.yaml) for this special use of the API resources.",
"languages": [
{
"code": "en",
"name": "English"
},
{
"code": "es",
"name": "Spanish"
},
{
"code": "fr",
"name": "French"
},
{
"code": "de",
"name": "German"
},
{
"code": "it",
"name": "Italian"
}
],
"name": "geotax"
},
{
"description": "The emotional-traits document classification resources classify documents in terms of feelings like joy, surprise, irritation, etc. expressed in the text. In addition, when requested with a specific query-string parameter, they return extra-data containing the main groups to which the emotional traits belong. Especially with longer texts, main groups are an useful abstract of the detailed classification. Refer to the specific OpenAPI document (https://github.com/therealexpertai/nlapi-openapi-specification/blob/master/emotional-traits-w-main-groups.yaml) for this special use of the API resources.",
"languages": [
{
"code": "en",
"name": "English"
}
],
"name": "emotional-traits"
},
{
"description": "The behavioral-traits document classification resources classify document in terms of personality traits like curiosity, honesty, negativity, etc. the text deals with.",
"languages": [
{
"code": "en",
"name": "English"
}
],
"name": "behavioral-traits"
}
]
}
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 contract property, which is optional, contains the URL of the OpenAPI document describing a special use of the taxonomy. For example, in the case of the geotax taxonomy, the OpenAPI document defines the way to use the classification resource to obtain a GeoJSON output.
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 category 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 identifierlabel: category labelcategories: 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.
detectors
The detectors resource returns a JSON object like this:
{
"detectors": [
{
"contract": "https://github.com/therealexpertai/nlapi-openapi-specification/blob/master/pii.yaml",
"description": "Personally Identifiable Information (PII) detector",
"languages": [
{
"code": "en",
"name": "English"
},
{
"code": "it",
"name": "Italian"
}
],
"name": "pii"
},
{
"contract": "https://github.com/therealexpertai/nlapi-openapi-specification/blob/master/writeprint.yaml",
"description": "Writeprint detector",
"languages": [
{
"code": "en",
"name": "English"
},
{
"code": "it",
"name": "Italian"
},
{
"code": "es",
"name": "Spanish"
},
{
"code": "fr",
"name": "French"
},
{
"code": "de",
"name": "German"
}
],
"name": "writeprint"
}
]
}
The detectors array contains one object for each detector.
The name property is the exact name that must be used in the endpoint of information detection resources.
The languages array lists the languages for which the taxonomy is available.
code id the ISO 639-1 language code.
Each detector has a specific output which is formally described in an OpenAPI document. The contract property contains the URL of that document.