Request

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.

Besides these parameters, there are a number of additional parameters that are specific for the different topic types that can be extracted.

Subtopics

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.

For example: "The tickets for the Tower of London are very expensive."

Tower of London would be detected as an entity, and within its analysis, London would appear as a subentity.

Two points to take into account:

• there will be only one level of subtopics and in the cases where it applies, the elements included there will not go through the same disambiguation process as top level topics.
• Currently, only subentity_list is enabled.

Disambiguation grouping

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.

• No grouping (sdg=n): no grouping done, the analyses obtained after the morphological and basic semantic disambiguation are the ones shown.
  Example 1: Toledo is very beautiful.

  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.

  Example 2: The Toledo always wins his matches in the Santiago Bernabéu stadium.

  In this case the disambiguation applied to Toledo will result in just one sense: Spanish Sports Team.

• Global intersection (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.
  Example 1: Her favorite is London

  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 confidence value.

• Intersection by type (sdg=t): ambiguous entities are grouped at entity subtype level and marked as uncertain.
  Example 1: Toledo is very beautiful.

  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 sementity type Location>GeoPoliticalEntity and uncertain as the confidence.

  Example 2: The Toledo always wins his matches in the Santiago Bernabéu stadium.

  In this case the result will be the same as for sdg=n, as it is not ambiguous: Spanish Sports Team.

• Intersection by type - smallest location (sdg=l): similar to sdg=t except for locations; ambiguous locations are disambiguated in favor of the smaller location (lower in the hierarchy)(default).
  Example 1: Toledo is very beautiful.

  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.

  Example 2: The Toledo always wins his matches in the Santiago Bernabéu stadium.

  Again, the result for this example will be the same as in sdg=n and 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.

Context disambiguation

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:

• Entity IDs: id of an entity returned by this same API.
  Example: He always wanted to live in Toledo.

  When analyzed with cont=33fc13e6dd (the 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.

• Ontology themes: name of a theme from our ontology.
  Example: Madrid is the best!

  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 | character.