ULAPI REST Documentation

The REST interface documented here is a great way to develop cross-platform applications using ULAPI, and is the basis for our own online dictionary tools. We also use ULAPI's REST interface to do rapid prototyping, even when our eventual plan is to use ULAPI C++.

General

Version

The current version of our ULAPI REST is version 1. Depending on which version of the API you would like to use, you can structure your requests in two ways. If you would like to specify a particular version, you must include the version number before a resource path: https://api.ultralingua.com/v1/.... However, you can always use the latest version by specifying api as the version number: https://api.ultralingua.com/api/.... While we intend to maintain to maintain a few older versions of our REST API to make transitions easier, we recommend always using the latest version for best results.

Security

We require you to use SSL for each request.

Encoding

All data sent to and from the Ultralingua API must be a UTF-8 encoded string.

Format

Requests should follow the structures outlined in the documentation below. All responses, including error messages, will be returned as a JSON formatted list or object. Refer to the documentation for each resource to determine what the return type will be.

Errors

Errors are denoted by standard HTTP status codes and the responses will contain a JSON object with more information about the error. To make these responses more useful, each response will contain an additional error code that can help you pinpoint why a particular request failed. In general, the body of an error response will look like the following:

{
  "message": "An error message."
  "code": 123
}
Status Error Description
400 null The server didn't find an endpoint that matched your request. You may have misspelled the resource name.
401 null The server could not verify that you are authorized to access a particular resource.
10 Either you did not send a token or your token is invalid.
11 The resource requires an authentication token, but the request did not contain one.
12 The resource required an access token, but the request did not contain one.

Numbers↑Top

/numbersVersion 1

Description
Returns a string representing the translation of a string of digits into words in a specified language.
Structure
/numbers/<language>/<number>
language
The language to which you wish to translate. (Ex: fra)
number
The number you wish to translate. (Ex: 1234)
Method
GET
Parameters
There are no optional parameters for this resource.
Returns
A list of translations, though usually there is just one available.
Sample response
[
  "mille deux cent trente-quatre"
]
Try It

Singulars↑Top

/singularsVersion 1

Description
Returns a list of strings showing the singular form(s) of the specified noun or adjective.
Structure
/singulars/<language>/<word>
language
The language of <word>. (Ex: fra)
word
The word you wish to singularize. (Ex: chats)
Method
GET
Parameters
gender
optionalThe gender by which the results will be filtered.
Returns
A list of singulars.
Sample response
[  
  'chat'
]
Try It

Plurals↑Top

/pluralsVersion 1

Description
Returns a list of strings showing the plural form(s) of the specified noun or adjective. If the word is already plural, the list of all possible plurals for the singular form(s) of word will be returned.
Structure
/plurals/<language>/<word>
language
The language of <word>. (Ex: spa)
word
The word you wish to pluralize. (Ex: casa)
Method
GET
Parameters
gender
optionalThe gender by which the results will be filtered.
Returns
A list of plurals.
Sample response
[  
  'casas'
]
Try It

Stemming↑Top

/stemsVersion 1

Description
Returns all of the stems, or root words, of the specified word and their associated linguistic attributes.
Structure
/stems/<language>/<word>
language
The language of <word>. (Ex: eng)
word
The word you wish to dissect. (Ex: caught)
Method
GET
Parameters
partofspeech
optionalThe part of speech to which you want to stem the word. By default, this method will return stems in all applicable parts of speech.
Returns
Returns a list of mappings containing both the surface and root forms of each stem as well as additional linguistic attributes.
Sample response
[
  {
    "surfaceform": "caught", 
    "root": "catch", 
    "partofspeech": {
      "tense": "pastparticiple", 
      "partofspeechcategory": "verb", 
      "partofspeechdisplay": "verb"
    }
  }
]
Try It

Word lookup / translation↑Top

/definitionsVersion 1

Description
Returns all of the definitions (in the case of monlingual dictionaries) or translations (in the case of bilingual dictionaries) of a given word and their associated linguistic attributes.
Structure
/definitions/<source_language>/<target_language>/<word>
source_language
The language of <word>. (Ex: eng)
target_language
The language in which you want the definitions/translations. (Ex: spa)
word
The word you wish to define/translate. (Ex: jump)
Method
GET
Parameters
partofspeech
optionalThe part of speech to use to narrow down the definitions/translations. By default, this method will return definitions/translations in all applicable parts of speech. (Ex: noun)
simple
optionalSet this to ‘true’ if you want the method to return the definitions as a list of strings rather than a list of complex objects that include the definition along with parts of speech and other linguistic information.
Returns
Returns a list of mappings containing the surface form of each definition/translation as well as additional linguistic attributes such as part of speech.
Sample response
[
  {
    "surfaceform": "salto",
    "text": "salto",
    "root": "salto",
    "partofspeech": {
      "gender": "masculine",
      "number": "singular",
      "partofspeechcategory": "noun",
      "partofspeechdisplay": "noun"
    }
  },
  {
    "surfaceform": "brinco",
    "text": "brinco",
    "root": "brinco",
    "partofspeech": {
      "gender": "masculine",
      "number": "singular",
      "partofspeechcategory": "noun",
      "partofspeechdisplay": "noun"
    }
  },
  {
    "surfaceform": "saltar",
    "text": "saltar",
    "root": "saltar",
    "partofspeech": {
      "tense": "infinitive",
      "partofspeechcategory": "verb",
      "partofspeechdisplay": "verb"
    }
  },
  {
    "surfaceform": "brincar",
    "text": "brincar",
    "root": "brincar",
    "partofspeech": {
      "tense": "infinitive",
      "partofspeechcategory": "verb",
      "partofspeechdisplay": "verb"
    }
  },
  {
    "surfaceform": "cabriolear",
    "text": "cabriolear",
    "root": "cabriolear",
    "partofspeech": {
      "tense": "infinitive",
      "partofspeechcategory": "verb",
      "partofspeechdisplay": "verb"
    }
  },
  {
    "surfaceform": "lanzarse",
    "text": "lanzarse",
    "root": "lanzarse",
    "partofspeech": {
      "tense": "infinitive",
      "partofspeechcategory": "verb",
      "partofspeechdisplay": "verb"
    }
  }
]
Try It

Verb conjugation↑Top

/conjugationsVersion 1

Description
Returns all of the conjugations of a given word, optionally narrowed by tense and/or person.
Structure
/conjugations/<language>/<verb>
language
The language of <verb>. (Ex: spa)
word
The verb you wish to conjugate. (Ex: lavar)
Method
GET
Parameters
tense
optionalThe tense you want to conjugate in (Ex: present). By default, this method will return conjugations in all applicable tenses.
person
optionalThe person you want to conjugate in (Ex: firstsingular ("I")). If this parameter is set, then the tense parameter should also be set. By default, this method will return conjugations in all applicable persons.
Returns
Returns a list of mappings containing both the surface and root forms of each conjugation as well as additional linguistic attributes such as part of speech.
Sample response
[
  {
    "surfaceform": "lavar",
    "root": "lavar",
    "partofspeech": {
      "tense": "infinitive",
      "partofspeechcategory": "verb",
      "partofspeechdisplay": "verb"
    }
  },
  {
    "surfaceform": "lavado",
    "root": "lavar",
    "partofspeech": {
      "tense": "pastparticiple",
      "partofspeechcategory": "verb",
      "partofspeechdisplay": "verb"
    }
  },
  {
    "surfaceform": "lavado",
    "root": "lavar",
    "partofspeech": {
      "tense": "pastparticiplemasculinesingular",
      "partofspeechcategory": "verb",
      "partofspeechdisplay": "verb"
    }
  },
  {
    "surfaceform": "lavados",
    "root": "lavar",
    "partofspeech": {
      "tense": "pastparticiplemasculineplural",
      "partofspeechcategory": "verb",
      "partofspeechdisplay": "verb"
    }
  },
  {
    "surfaceform": "lavada",
    "root": "lavar",
    "partofspeech": {
      "tense": "pastparticiplefemininesingular",
      "partofspeechcategory": "verb",
      "partofspeechdisplay": "verb"
    }
  },
  {
    "surfaceform": "lavadas",
    "root": "lavar",
    "partofspeech": {
      "tense": "pastparticiplefeminineplural",
      "partofspeechcategory": "verb",
      "partofspeechdisplay": "verb"
    }
  },
  {
    "surfaceform": "lavando",
    "root": "lavar",
    "partofspeech": {
      "tense": "gerund",
      "partofspeechcategory": "verb",
      "partofspeechdisplay": "verb"
    }
  },
  {
    "surfaceform": "lavo",
    "root": "lavar",
    "partofspeech": {
      "person": "first",
      "tense": "present",
      "number": "singular",
      "partofspeechcategory": "verb",
      "partofspeechdisplay": "verb"
    }
  },
  {
    "surfaceform": "lavas",
    "root": "lavar",
    "partofspeech": {
      "person": "second",
      "tense": "present",
      "number": "singular",
      "partofspeechcategory": "verb",
      "partofspeechdisplay": "verb"
    }
  },
  .
  .
  .
]
Try It

/tensesVersion 1

Description
Returns all of the tenses that can be used for the specified verb in a given language.
Structure
/tenses/<language>/<verb>
language
The language of <verb>. (Ex: spa)
verb
The verb for which you want the tenses (Ex: saltar)
Method
GET
Parameters
There are no optional parameters for this resource.
Returns
Returns a list of tenses in which the verb can be conjugated for the given language. These tense names can be used in <tense> parameters in other methods.
Sample response
[
  "pastparticiple",
  "pastparticiplemasculinesingular",
  "pastparticiplemasculineplural",
  "pastparticiplefemininesingular",
  "pastparticiplefeminineplural",
  "gerund",
  "present",
  "future",
  "futureperfect",
  "past",
  "presentperfect",
  "imperfect",
  "conditional",
  "pastconditional",
  "imperative",
  "pastanterior",
  "presentsubjunctive",
  "imperfectsubjunctive",
  "futuresubjunctive",
  "pastperfectsubjunctive",
  "futureperfectsubjunctive",
  "pastperfect",
  "presentperfectsubjunctive"
]
Try It

/personsVersion 1

Description
Returns all of the persons that can be used for the specified verb in a given tense for a given language.
Structure
/persons/<language>/<verb>/<tense>
language
The language of <verb>. (Ex: spa)
verb
The verb for which you want the persons (Ex: saltar)
tense
The tense for which you want the persons (Ex: present)
Method
GET
Parameters
There are no optional parameters for this resource.
Returns
Returns a list of persons in which the verb can be conjugated for a specific tense and language. These person names can be used in <person> parameters in other methods.
Sample response
[
  "firstsingular",
  "secondsingular",
  "thirdsingular",
  "firstplural",
  "secondplural",
  "thirdplural"
]
Try It

/pronounsVersion 1

Description
Returns all of the pronouns for a given person in a specific language. Sometimes there is only one pronoun for a person (the first singular "I" in English), but other times there are multiple pronouns for one person (the third plural "ils" and "elles" in French).
Structure
/pronouns/<language>/<person>
language
The language in which to lookup the pronouns. (Ex: spa)
person
The person for which you want the pronoun (Ex: thirdplural)
Method
GET
Parameters
There are no optional parameters for this resource.
Returns
Returns a list of pronouns for the given language corresponding to the given person.
Sample response
[
  "ellos",
  "ellas",
  "Vds"
]
Try It

Part of speech tagging↑Top

/tagsVersion 1

Description
Tags the words in a given sentence or phrase with a list of their possible part of speech in order from most to least likely.
Structure
/stems/<language>/<word>
language
The language of <sentence>. (Ex: eng)
sentence
The sentence or phrase you wish to tag. (Ex: I eat two cakes.)
Method
GET
Parameters
max_tags
optionalSetting this parameter restricts the total number of parts of speech that a word can be tagged with. Using value 1 for this parameter will limit the tags to only the most likely part of speech for each word. By default, this method will return all possible parts of speech that each word can have.
Returns
Returns a list of tags for each word in the <sentence> where each tag is a possible part of speech for that word, ordered from most to least likely.
Sample response
[
  [
    {
      "surfaceform": "I",
      "root": "I",
      "partofspeech": {
        "person": "first",
        "number": "singular",
        "partofspeechcategory": "pronoun",
        "partofspeechdisplay": "pronoun"
      }
    },
    {
      "surfaceform": "I",
      "root": "I",
      "partofspeech": {
        "number": "singular",
        "partofspeechcategory": "noun",
        "partofspeechdisplay": "noun"
      }
    }
  ],
  [
    {
      "surfaceform": "eat",
      "root": "eat",
      "partofspeech": {
        "tense": "infinitive",
        "partofspeechcategory": "verb",
        "partofspeechdisplay": "verb"
      }
    },
    {
      "surfaceform": "eat",
      "root": "eat",
      "partofspeech": {
        "person": "first",
        "tense": "present",
        "number": "singular",
        "partofspeechcategory": "verb",
        "partofspeechdisplay": "verb"
      }
    }
  ],
  [
    {
      "surfaceform": "two",
      "root": "two",
      "partofspeech": {
        "partofspeechcategory": "adjective",
        "partofspeechdisplay": "adjective"
      }
    },
    {
      "surfaceform": "two",
      "root": "two",
      "partofspeech": {
        "number": "singular",
        "partofspeechcategory": "noun",
        "partofspeechdisplay": "noun"
      }
    }
  ],
  [
    {
      "surfaceform": "cakes",
      "root": "cake",
      "partofspeech": {
        "number": "plural",
        "partofspeechcategory": "noun",
        "partofspeechdisplay": "noun"
      }
    },
    {
      "surfaceform": "cakes",
      "root": "cake",
      "partofspeech": {
        "person": "third",
        "tense": "present",
        "number": "singular",
        "partofspeechcategory": "verb",
        "partofspeechdisplay": "verb"
      }
    }
  ]
]
Try It