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.