If you are working with an on-premises installation, you will need to substitute by your own server address.




keyAuthorization key for using MeaningCloud services. Create an account for free to create your key.Required
ofOutput format.json xmlOptional. Default:json
langLanguage of the text to analyze.See supported languages.Required. Use auto to perform language detection.
ilangLanguage in which the returned values will appear, if known. Check the response section to see which fields are affected.See supported languages.Optional. If not specified, the language set in lang will be used.
txtText to analyzeUTF-8 encoded text (plain text, HTML or XML).Use only one
urlURL of the document to analyze. Non-authenticated HTTP(s) and FTP supported. See supported formats.
docInput file with the content to analyze. See supported formats.
txtfThe text format parameter specifies if the text included in the txt parameter uses markup language that needs to be interpreted (known HTML tags and HTML code will be interpreted, and unknown tags will be ignored).plain
Optional, default:plain
ttThe list of topic types to extract will be specified through a string with the letters assigned to each one of the topic types that are to be extracted.e: named entities
c: concepts
t: time expressions
m: money expressions
n: quantity expressions [beta]
o: other expressions
q: quotations
r: relations
a: all
uwDeal with unknown words. This feature adds a stage to the topic extraction in which the engine, much like a spellchecker, tries to find a suitable analysis to the unknown words resulted from the initial analysis assignment. It is specially useful to decrease the impact typos have in text analyses.y: enabled
n: disabled
Optional. Default: n
rtDeal with relaxed typography. This parameter indicates how reliable the text (as far as spelling, typography, etc. are concerned) to analyze is, and influences how strict the engine will be when it comes to take these factors into account in the topic extraction.y: enabled
u: enabled only for user dictionary
n: disabled
Optional. Default: n
udThe user dictionary allows to include user-defined entities and concepts in the topics extraction. It provides a mechanism to adapt the process to focus on specific domains or on terms relevant to a user's interests, either to increase the precision in any of the domains already taken into account in our ontology, to include a new one, or just to add a new semantic meaning to known terms. Several dictionaries can be combined separating them with |.Name of your user dictionariesOptional.
stShow subtopics. This parameter will indicate if subtopics are to be shown. See subtopics for a more in depth explanation.y: enabled
n: disabled
Optional. Default: n


The fields txt, doc and 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 txt, url and doc.

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

Entities parameters

dmType 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
sdgSemantic disambiguation grouping. This parameter will only apply when semantic disambiguation is activated (dm=s). See disambiguation grouping for a more in depth explanation.n: none
g: global intersection
t: intersection by type
l: intersection by type - smallest location
contDisambiguation context. Context prioritization for entity semantic disambiguation. See context disambiguation for a more in depth explanation.

Time Expressions parameters

timerefThis value allows to set a specific time reference to detect the actual value of all the relative time expressions detected in the textYYYY-MM-DD hh:mm:ss GMT±HH:MMCurrent time at the moment the request is made.

Disambiguation grouping

Below we have examples on how exactly each mode of the disambiguation grouping parameter behaves. This parameter will only be enabled whendm=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 toToledo 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 notype (the result of intersecting "Person>LastName" and "Location>GeoPoliticalEntity>City"), anduncertain as theconfidence 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 ofToledo leaves two senses: City in Spain and Adm2 in Spain. As both share the entity type up toGeoPoliticalEntity, the result for this grouping mode will be a unique analysis with thesementity typeLocation>GeoPoliticalEntity anduncertain as theconfidence.

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

        In this case the result will be the same as forsdg=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 insdg=n andsdg=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 withcont=33fc13e6dd (theid 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 withcont=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 thecont parameter with either identifiers or themes from our ontology; if you use more than one, they must always be separated by the| character.


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 butsub[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, onlysubentity_list is enabled.