Requests are made using GET or POST data submissions to the API entry point. Typically, a POST method is recommended in order to overcome the parameter maximum length limit associated to the GET method.
url are mutually exclusive; in other words, at least one of them must not be empty (a content parameter is required), and in cases where more than one of them has a value assigned, only one will be processed. The precedence order is
Besides these parameters, there are a number of additional parameters that are specific for the different topic types that can be extracted.
Type of disambiguation applied. It is accumulative, that is, the semantic disambiguation mode will also include morphosyntactic disambiguation.
|n: no disambiguation
m: morphosyntactic disambiguation
s: semantic disambiguation
Semantic disambiguation grouping. This parameter will only apply when semantic disambiguation is activated (
g: global intersection
t: intersection by type
l: intersection by type - smallest location
Disambiguation context. Context prioritization for entity semantic disambiguation. See context disambiguation for a more in depth explanation.
||This value allows to set a specific time reference to detect the actual value of all the relative time expressions detected in the text.||YYYY-MM-DD hh:mm:ss GMT±HH:MM||Optional. Default: current time at the moment the request is made.|
Subtopics refer to the cases where a structure detected as a topic has another topic within; under normal circumstances, the resulting topic will be the one that contains the second one, but it may imply missing semantic information associated to it. In each element, the element will not be called subtopics but sub[element name], and each element included will contain the same structure as the parent element.
The most common case will take place for entities, where there will appear elements with semantic information that are detected as other types of entities because of the grammatical structure in which they appear.
Tower of London would be detected as an
entity, and within its analysis, London would appear as a
Two points to take into account:
Below we have examples on how exactly each mode of the disambiguation grouping parameter behaves. This parameter will only be enabled when
dm=s, which means that all modes will include morphological and basic semantic disambiguation.
sdg=n): no grouping done, the analyses obtained after the morphological and basic semantic disambiguation are the ones shown.
When no semantic disambiguation is applied, Toledo has the following senses: Last Name, City in Spain, City in Colombia, City in USA, Adm2 in Spain, and Spanish Sports Team. The disambiguation applied will result in two senses: City in Spain and Adm2 in Spain.
In this case the disambiguation applied to Toledo will result in just one sense: Spanish Sports Team.
sdg=g): ambiguous entities are grouped at entity type level (that is, the global interesection of the analyses) and marked as uncertain, resulting in just one sense per entity.
In this case, the basic disambiguation results in two senses: Last Name and City. As this result is ambiguous (as it is the sentence, which can refer to either the city or the author), the result will be a single sense with no
type (the result of intersecting "Person>LastName" and "Location>GeoPoliticalEntity>City"), and uncertain as the
sdg=t): ambiguous entities are grouped at entity subtype level and marked as uncertain.
Again, the basic disambiguation of Toledo leaves two senses: City in Spain and Adm2 in Spain. As both share the entity type up to GeoPoliticalEntity, the result for this grouping mode will be a unique analysis with the
type Location>GeoPoliticalEntity and uncertain as the
In this case the result will be the same as for
sdg=n, as it is not ambiguous: Spanish Sports Team.
sdg=l): similar to
sdg=texcept for locations; ambiguous locations are disambiguated in favor of the smaller location (lower in the hierarchy)(default).
As seen in the previous examples, the basic disambiguation results in two senses, both of them locations: City in Spain and Adm2 in Spain. In case of having several ambiguous locations, this mode keeps the smaller location, so in this case, the resulting sense will be City of Spain.
Again, the result for this example will be the same as in
sdg=t as the result is not ambiguous nor a location.
The main goal of this parameter is to provide different possibilities in the disambiguation process in order to be adaptable to different scenarios.
With the disambiguation context parameter you can prioritize an entity or different themes when disambiguating a text, in order to prioritize some analyses. There are two different types of values for this parameter:
idof an entity returned by this same API.
When analyzed with
id of the entity America in our ontology) two variants of the entity Toledo are detected, a city in Antioquia, Colombia, and another city in Ohio, USA.
When analyzed with
cont=Football (name of the entry ODTHEME_FOOTBALL in our ontology), the entity Madrid is detected as a sport team (Real Madrid C. F.).
You can use the
cont parameter with either identifiers or themes from our ontology; if you use more than one, they must always be separated by the