Ultralingua API Reference

Develop cross-platform applications using ULAPI via HTTP.

General

Version

This document describes ULAPI-over-HTTP version 2.0.

All API endpoints begin with https://api.ultralingua.com/api/2.0

GET AN API KE

Get an API key by contacting us at dev@ultralingua.com. Once you have a key, make your queries like so:

    https://api.ultralingua.com/api/2.0/ENDPOINT-PATH?key=YOUR-API-KEY

Encoding

Queries sent to ULAPI must be encoded using UTF-8. Responses are also encoded using UTF-8.

HTTP request method

Use HTTP’s GET request method to access ULAPI.

Request format: languages

For endpoints requiring you to specify a language, you do so by using ISO two-letter or three-letter language codes (ISO 639-1 and 639-2/T) or the English name for the language. For example, to specify Portuguese, you can use pt, por, or portuguese.

RESPONSE FORMAT: status codes

ULAPI uses standard HTTP status codes to provide status information for each query.

  • 200 OK indicates a successful query.

  • 401 Not Authorized indicates that the query did not include a valid API key, and that the number of free queries during the past 24 hours from your IP address has been exhausted.

  • 403 Forbidden indicates that the query requests a service for which your API key does not grant you access. For example, if your API key is for the Spanish-English dataset and you try to look up a Spanish-to-French translation, you will receive a 403 status result. Our trial API keys give you access to all our available datasets.

  • 404 Not Found indicates that the endpoint being queried does not exist.

Response format: JSON

ULAPI response content is represented in JSON, with endpoint-specific formats described below.

Several of the endpoint responses include one or more JSON Objects (i.e. associative arrays) with special sets of keys. We will refer to these special objects as PartOfSpeech, Word, and Term. The keys found in these three type of JSON Objects are described here.

PartOfSpeech: These JSON Objects represent a part of speech, and have the following keys (marked required or optional as appropriate).

  • partofspeechcategory: string [required]. This gives the basic part of speech: verb, noun, adjective, etc. See /help/partsofspeech.

  • partofspeechsubcategory: string [optional]. Miscellaneous attributes of various parts of speech, like “reflexive” for reflexive verbs, “definite” for definite articles, etc.

  • number: string [optional]. “singular” or “plural”

  • gender: string [optional]. For nouns—“masculine”, “feminine”, or “neuter”

  • tense: string [optional]. For verb forms. See /help/tenses.

  • person: string [optional]. For verb forms. See /help/persons.

  • formality: string [optional]. For pronouns—“informal” or “formal” (for words like “tu” and “vous”).

Word: Each Word JSON Object represents a single word, and may include the following keys:

  • surfaceform: string [required]. The word being represented.

  • partofspeech: Object [required]. The word’s part of speech is represented by a JSON Object as described below.

  • root: string [optional]. The word’s root word.

  • text: string [optional]. Sometimes, a result (say, of a dictionary lookup) is a multi-word expression; in such cases, surfaceform will be the word being searched for, but text will be the full text of the expression.

  • clarification: list of string [optional]. A list of one or more clarifications to help identify which sense of the word is being translated.

  • grammarusage: list of string [optional]. A list of usage notes.

  • pronunciation: list of string [optional]. A list of one or more pronunciations as International Phonetic Alphabet strings.

  • etymology: list of string [optional]: A list of one or more etymology notes.

  • example: list of string [optional]. A list of example phrases using the word.

  • synonym: list of string [optional]. A list of synonyms of the word.

  • antonym: list of string [optional]. A list of antonyms of the word.

  • homonym: list of string [optional]. A list of homonyms of the word.

Term: Each Term JSON Object represents a single word or phrase. Like a Word, a Term includes information about the word or phrase, but a Term also includes its definitions or translations. A Term includes the following keys:

  • text: string [required]. The word or phrase.

  • partofspeech: PartOfSpeech [required]. The term’s part of speech.

  • language: string [required]. The term’s language.

  • translationlanguage: string [required]. The language of the term’s definitions/translations.

  • definitions: list of Word [required]. The definitions/translations of the term.

  • example: Object mapping languages to strings [optional]. Example usages, like {“en”: “it’s all the rage”, “fr”: “c'est très à la mode”}.

  • pronunciation: string [optional]. A list of one or more pronunciations as International Phonetic Alphabet strings.

  • grammarusage: list of string [optional]. A list of usage notes.

  • usage: string [optional]. A note on the semantic (as opposed to grammatical) usage of the term.

  • clarification: Object mapping languages to strings [optional]. This attribute helps clarify the specific sense of the term. This attribute will look something like {“en”: “split wood”, “fr”: “fendre du bois”} (that example describes the sense of the word “split” that we’re talking about, to distinguish between the verbs used when splitting wood or atoms or hairs).

  • tone: Object mapping languages to strings [optional]. This attribute represents the tone of the term (e.g. Slang, Vulgar, etc.). This attribute will look something like {“en”: “Slang”, “fr”: “Argot”}.

  • dialect: Object mapping languages to strings [optional]. This attribute represents the dialect of the term (e.g. UK, US, Brazilian, etc.). This attribute will look something like {“en”: “Quebecois”, “fr”: “Québécisme”}.

  • ontology: Object mapping languages to strings [optional]. This attribute represents the field of study or endeavor relevant to the term (e.g. Sports, Finance, etc.). This attribute will look something like {“en”: “Beekeeping”, “fr”: “Apiculture”}.

  • alternatespelling: string [optional]. A comma-delimited list of possible alternate spellings of the term.

  • synonyms: string [optional]. A comma-delimited list of synonyms for the term.

  • antonyms: string [optional]. A comma-delimited list of antonyms for the term.

  • homonyms: string [optional]. A comma-delimited list of homonyms for the term.

  • etymology: string [optional]. A brief description of the etymology of the term.

Endpoints

/definitions — look up a word in a bilingual or monolingual dictionary

/terms — look up a word in a bilingual or monolingual dictionary and include multi-word phrases in the results

/conjugations — conjugate a verb

/lemmas — compute the lemma (or root word) of a word

/numbers — translate a number into words

/plurals — get the plural form(s) of a noun

/singulars — get the singular form(s) of a plural noun

/help/dictionaries — list the available dictionaries

/help/languages — list the available languages (for monolingual features such as /lemmas and /conjugations)

/help/partsofspeech — list all the part-of-speech categories that can appear in parts of speech

/help/persons — list all the person identifiers (e.g. first, second, firstsingular, etc.) that can appear in parts of speech

/help/tenses — list all the tenses that can appear in parts of speech

Endpoint

/definitions

Description

Finds all the definitions (in the case of monolingual dictionaries) or translations (in the case of bilingual dictionaries) of a word.

Structure

/definitions/<source_language>/<target_language>/<word>

source_language: The language of <word>.

target_language: The language in which you want the definitions/translations.

word: The word you wish to define/translate.

Returns

A list of definitions/translations for the requested word. Each definition/translation consists of a Word object as described in the Response Format: JSON section above.

Example

Query
/definitions/en/es/jump
Response
[ { "surfaceform": "salto", "text": "salto", "root": "salto", "partofspeech": { "gender": "masculine", "number": "singular", "partofspeechcategory": "noun" } }, { "surfaceform": "brinco", "text": "brinco", "root": "brinco", "partofspeech": { "gender": "masculine", "number": "singular", "partofspeechcategory": "noun" } }, { "surfaceform": "saltar", "text": "saltar", "root": "saltar", "partofspeech": { "tense": "infinitive", "partofspeechcategory": "verb" } }, { "surfaceform": "brincar", "text": "brincar", "root": "brincar", "partofspeech": { "tense": "infinitive", "partofspeechcategory": "verb" } }, { "surfaceform": "cabriolear", "text": "cabriolear", "root": "cabriolear", "partofspeech": { "tense": "infinitive", "partofspeechcategory": "verb" } }, { "surfaceform": "lanzarse", "text": "lanzarse", "root": "lanzarse", "partofspeech": { "pospsubcategory": "reflexive", "tense": "infinitive", "partofspeechcategory": "verb" } } ]

Endpoint

/terms

Description

Finds all the terms containing the specified word. This will include exact matches (e.g. if you look up chair, depending on the dataset you might get both the noun and verb forms of chair) as well as phrases involving the word (e.g. chair lift or rocking chair). Unlike /definitions, /term looks only for exact matches; it does not lemmatize your search word before searching, so /term/en/[other-language]/chairs or /term/en/[other-language]/chaired will not find chair.

Structure

/terms/<source_language>/<target_language>/<word>

source_language: The language of <word>.

target_language: The language in which you want the definitions/translations.

word: The word you are searching for.

Returns

A list of terms containing the requested word. Each term consists of a Term object as described in the Response Format: JSON section above.

Example

Query
/terms/en/fr/fly
Response
[ { "text": "fly", "language": "en", "translationlanguage": "fr" "partofspeech": { "number": "singular", "partofspeechcategory": "noun" }, "pronunciation": "fla\u026a", "definitions": [ { "text": "mouche", "partofspeech": { "partofspeechcategory": "noun", "gender": "feminine", "number": "singular" } }, { "text": "braguette", "partofspeech": { "partofspeechcategory": "noun", "gender": "feminine", "number": "singular" }, "clarification": { "en": "on trousers" }, "dialect": { "en": "US" }, "ontology": { "en": "Clothing", "fr": "V\u00eatement" } } ], }, { "text": "fly", "language": "en", "translationlanguage": "fr" "partofspeech": { "partofspeechcategory": "verb", "tense": "infinitive" }, "pronunciation": "fla\u026a", "grammarusage": "p.,p.p.: flew, flown", "definitions": [ { "text": "voler" "partofspeech": { "partofspeechcategory": "verb", "tense": "infinitive" }, "clarification": { "fr": "avion, oiseau" } }, { "text": "fuser", "clarification": { "en": "sparks that fly", "fr": "\u00e9tincelles qui fusent" }, "partofspeech": { "partofspeechcategory": "verb", "tense": "infinitive" } } ] }, { "text": "fly swatter", "language": "en", "translationlanguage": "fr" "partofspeech": { "partofspeechcategory": "noun", "number": "singular" }, "definitions": [ "text": "chasse-mouches", { "partofspeech": { "partofspeechcategory": "noun", "gender": "masculine", "number": "singular" } ] }, ...and so on (tsetse fly, fly into pieces, eat on the fly, etc.)... ]

Endpoint

/conjugations

Description

Computes all the conjugations of a specified verb.

Structure

/conjugations/<language>/<verb>

language: The language of <verb>.

verb: The verb you wish to conjugate. This can be any form of the verb. For example, you could conjugate the infinitive "parler" in French, but other forms of the verb like "parlez" or "parlions" or "a parlé" will work just as well.

Returns

A JSON Object with the following structure:

{
    "infinitive": [the verb's infinitive form],
    "conjugations": [a list of all the verb's conjugations]
}

Each conjugation consists of a Word object as described in the Response format: JSON section above.

Example

Query
/conjugations/fr/parlez
Response
[ { "infinitive": "parler", "conjugations": [ { "surfaceform": "parler", "partofspeech": { "tense": "infinitive", "partofspeechcategory": "verb" } }, { "surfaceform": "parlant", "partofspeech": { "tense": "presentparticiple", "partofspeechcategory": "verb" } }, { "surfaceform": "parlé", "partofspeech": { "tense": "pastparticiplemasculinesingular", "partofspeechcategory": "verb" } }, { "surfaceform": "parlés", "partofspeech": { "tense": "pastparticiplemasculineplural", "partofspeechcategory": "verb" } }, { "surfaceform": "parlée", "partofspeech": { "tense": "pastparticiplefemininesingular", "partofspeechcategory": "verb" } }, { "surfaceform": "parlées", "partofspeech": { "tense": "pastparticiplefeminineplural", "partofspeechcategory": "verb" } }, { "surfaceform": "parle", "partofspeech": { "person": "first", "tense": "present", "number": "singular", "partofspeechcategory": "verb" } }, { "surfaceform": "parles", "partofspeech": { "person": "second", "tense": "present", "number": "singular", "partofspeechcategory": "verb" } }, { "surfaceform": "parle", "partofspeech": { "person": "third", "tense": "present", "number": "singular", "partofspeechcategory": "verb" } }, { "surfaceform": "parlons", "partofspeech": { "person": "first", "tense": "present", "number": "plural", "partofspeechcategory": "verb" } }, { "surfaceform": "parlez", "partofspeech": { "person": "second", "tense": "present", "number": "plural", "partofspeechcategory": "verb" } }, { "surfaceform": "parlent", "partofspeech": { "person": "third", "tense": "present", "number": "plural", "partofspeechcategory": "verb" } }, { "surfaceform": "parlerai", "partofspeech": { "person": "first", "tense": "future", "number": "singular", "partofspeechcategory": "verb" } }, { "surfaceform": "parleras", "partofspeech": { "person": "second", "tense": "future", "number": "singular", "partofspeechcategory": "verb" } }, { "surfaceform": "parlera", "partofspeech": { "person": "third", "tense": "future", "number": "singular", "partofspeechcategory": "verb" } }, ...and so on and so on...there are a *lot* of conjugations for French verbs... ]

Endpoint

/lemmas
/stems
/roots

Description

Computes all of the lemmas, or root words, of a specified word. (Though the word stem has a slightly different meaning, ULAPI uses "lemmas" and "stems" interchangeably for historical reasons. We'll call this endpoint "/lemmas", but you can use "/roots" or "/stems" if you prefer.)

Structure

/lemmas/<language>/<word>

language: The language of <word>.

word: The word whose lemmas you seek.

Returns

The list of the requested word's lemmas/root words. Each lemma consists of a Word object as described in the Response Format: JSON section above.

Example

Query
/lemmas/en/thought
Response
[ { "surfaceform": "thought", "text": "thought", "root": "thought", "partofspeech": { "number": "singular", "partofspeechcategory": "noun" }, "etymology": [ "Old Eng. thoght, thouht, AS. thôht, gethôht, from thencean to think; akin to Dutch gedachte thought, Mid. High Germ. dâht, gedâht, Icel. thôttr, thôtti. Related to Think." ], "pronunciation": [ "θɔːt" ], "grammarusage": [ "thoughts" ] }, { "surfaceform": "thought", "text": "think", "root": "think", "partofspeech": { "tense": "pastparticiple", "partofspeechcategory": "verb" }, "pronunciation": [ "θɪŋk" ], "grammarusage": [ "thought ◊ thinking ◊ thinks" ] } ]

Endpoint

/number

Description

Translates a number (i.e. a string of digits) into words in a specified language.

Structure

/number/<language>/<number>

language: The language into which you wish to translate <number>.

number: The number you wish to translate.

Returns

A string containing the translation of the number into words.

Example

Query
/number/pt/54321
Response
"cinqüenta e quatro mil, trezentos e vinte e um"

Endpoint

/plurals

Description

Computes the plural form(s) of the specified noun or adjective.

Structure

/plurals/<language>/<word>

language: The language of the word.

word: The word whose plural forms you seek.

Returns

A list of strings, each of which is a plural form of the specified word.

Example

Query
/plurals/en/octopus
Response
["octopi", "octopuses"]

Endpoint

/singulars

Description

Computes the singular form(s) of the specified noun or adjective.

Structure

/singulars/<language>/<word>

language: The language of the word.

word: The word whose singular forms you seek.

Returns

A list of strings, each of which is a singular form of the specified word.

Example

Query
/singulars/fr/chansons
Response
["chanson"]

Endpoint

/help/languages

Description

Shows the list of languages available for monolingual endpoints such as /lemmas and /conjugations.

Structure

/help/languages

Returns

A list of JSON Objects of the following form, one for each available language.

{
    "english-name": "Spanish",
    "iso2": "es",
    "iso3": "spa"
}

Example

Query
/help/languages
Response
[ { "english-name": "English", "iso2": "en", "iso3": "eng" }, { "english-name": "Spanish", "iso2": "es", "iso3": "spa" }, { "english-name": "French", "iso2": "fr", "iso3": "fra" }, ...and so on... ]

Endpoint

/help/dictionaries

Description

Shows the list of dictionary datasets available for dictionary lookup via the /definitions endpoint.

Structure

/help/dictionaries

Returns

A list of JSON Objects of the following form, one for each available dictionary.

{
    "language1": [ISO language code],
    "language2": [ISO language code],
    "thesaurus": [true or false]
}

For monolingual dictionaries, the values for language1 and language2 will be the same.

For bilingual dictionaries, there is no meaning to the ordering of language1 and language2; all bilingual dictionaries can be searched in both directions.

The thesaurus key is only present if the dataset is a thesaurus, in which case its value is true.

Example

Query
/help/dictionaries
Response
[ { "language1": "de", "language2": "it" }, { "language1": "en", "language2": "en" }, { "language1": "fr", "language2": "fr", "thesaurus": true }, ...and so on. The three dictionary descriptors above show a bilingual dictionary (German-Italian), a monolingual dictionary (English), and a thesaurus (French). ]

Endpoint

/help/partsofspeech

Description

Shows the list of part-of-speech categories that may appear in ULAPI responses. Examples include "verb", "noun", "adjective", etc.

Structure

/help/partsofspeech

Returns

A list of strings, each of which is a part-of-speech category.

Example

Query
/help/partsofspeech
Response
["noun", "verb", "pronoun", ...and so on...]

Endpoint

/help/tenses

Description

Shows the list of tenses that may appear in ULAPI responses related to verbs.

Structure

/help/tenses

Returns

A list of JSON objects of the following form, one for each available tense.

{
  "id": [tense identifier],
  "names": {
     "en": [English name of the tense],
     "fr": [French name of the tense],
     ...and so on...
  }
}

Example

Query
/help/tenses
Response
[ { "id": "infinitive", "names": { "en": "infinitive", "fr": "infinitif", "de": "infinitiv", "es": "infinitivo", "it": "infinito", "nl": "Onbepaalde wijs", "pt": "infinitivo", "ru": "\u0438\u043d\u0444\u0438\u043d\u0438\u0442\u0438\u0432" } }, { "id": "present", "names": { "en": "present", "fr": "pr\u00e9sent", "de": "pr\u00e4sens", "es": "presente de indicativo", "it": "presente", "nl": "O.T.T", "pt": "presente do indicativo", "ru": "\u043d\u0430\u0441\u0442\u043e\u044f\u0301\u0449\u0435\u0435" } }, ...and so on... ]

Endpoint

/help/persons

Description

Shows the list of part-of-speech categories that may appear in ULAPI responses. Examples include "verb", "noun", "adjective", etc.

Structure

/help/persons

Returns

A list of strings, each of which identifies a person. Note that there are some differences in how our dictionary datasets have been tagged, so sometimes a verb Word's partofspeech attribute might look like this:

"partofspeech": { "partofspeechcategory": "verb", "tense": "present", "person": "secondsingularformal" }

while in other datasets it might look like this:

"partofspeech": { "partofspeechcategory": "verb", "tense": "present", "person": "second", "number": "singular", "formality": "formal" }

Example

Query
/help/persons
Response
[ "first", "second", "third", "firstsingular", "secondsingular", "secondsingularformal", "thirdsingular", "firstplural", "secondplural", "secondpluralformal", "thirdplural" ]