lookup method

Searches for a word or phrase in the dictionary and returns an automatically generated dictionary entry.

Description

DicResult lookup(string key, string text, string lang, string ui, int flags);

Input parameters

Input parameters can be passed either using an HTTP GET request (see the example), or using an HTTP POST request where the parameters are passed in the body of the HTTP request.

Sample request:

XML interface:

https://dictionary.yandex.net/api/v1/dicservice/lookup?key=APIkey&lang=en-ru&text=time

JSON interface:

https://dictionary.yandex.net/api/v1/dicservice.json/lookup?key=APIkey&lang=en-ru&text=time

JSONP interface (for the "myCallback" function):

https://dictionary.yandex.net/api/v1/dicservice.json/lookup?key=API&lang=en-ru&text=time&callback=myCallback

List of input parameters.

ParameterTypeDescription
Mandatory
keystringAPI key. Get a free API key on this page.
langstring

Translation direction (for example, "en-ru"). Set as a pair of language codes separated by a hyphen. For example, "en-ru" specifies to translate from English to Russian.

Tip. The service does not just work with translation dictionaries. For example, you can set the direction "ru-ru" or "en-en" to get all the possible meanings of the word you are searching for in Russian or English.
textstring

The word or phrase to find in the dictionary.

Optional
uistring

The language of the user's interface for displaying names of parts of speech in the dictionary entry.

flagsint

Search options (bitmask of flags).

Possible values:

  • FAMILY = 0x0001 - Apply the family search filter.
  • MORPHO = 0x0004 - Enable searching by word form.
  • POS_FILTER = 0x0008 - Enable a filter that requires matching parts of speech for the search word and translation.

Returns

In the XML interface, it returns the DicResult structure, which contains a dictionary entry that is generated automatically based on search results. For example:

<DicResult>
  <head/>
  <def pos="noun" ts="taɪm">
    <text>time</text>
    <tr pos="существительное">
      <text>время</text>
      <syn>
        <text>раз</text>
      </syn>
      <syn>
        <text>тайм</text>
      </syn>
      <mean>
        <text>timing</text>
      </mean>
      <mean>
        <text>fold</text>
      </mean>
      <mean>
         <text>half</text>
      </mean>
      <ex>
         <text>prehistoric time</text>
         <tr>
            <text>доисторическое время</text>
         </tr>
      </ex>
      <ex>
         <text>hundredth time</text>
         <tr>
            <text>сотый раз</text>
         </tr>
      </ex>
      <ex>
         <text>time-slot</text>
         <tr>
            <text>тайм-слот</text>
         </tr>
      </ex>
    </tr>
  </def>
</DicResult>
Elements of the XML schema for the DicResult response
ElementDescription
headResult header (not used).
defArray of dictionary entries. A transcription of the search word may be provided in the ts attribute.
trArray of translations.
synArray of synonyms.
meanArray of meanings.
exArray of examples.
Attributes used in the elements def, tr, syn, mean, and ex
AttributeDescription
textText of the entry, translation, or synonym (mandatory).
posPart of speech (may be omitted).

Error codes
CodeValueDescription
ERR_OK200

Operation completed successfully.

ERR_KEY_INVALID401

Invalid API key.

ERR_KEY_BLOCKED402

This API key has been blocked.

ERR_DAILY_REQ_LIMIT_EXCEEDED403

Exceeded the daily limit on the number of requests.

ERR_TEXT_TOO_LONG413

The text size exceeds the maximum.

ERR_LANG_NOT_SUPPORTED501

The specified translation direction is not supported.

In the JSON interface, instead of XML elements, JavaScript objects are returned with the same names and semantics:

{ "head": {},
  "def": [
     { "text": "time", "pos": "noun",
       "tr": [
          { "text": "время", "pos": "существительное",
            "syn": [
               { "text": "раз" },
               { "text": "тайм" }
            ],
            "mean": [
               { "text": "timing" },
               { "text": "fold" },
               { "text": "half"}
            ],
            "ex" : [
               { "text": "prehistoric time",
                 "tr": [
                    { "text": "доисторическое время" }
                 ]
               },
               { "text": "hundredth time",
                 "tr": [
                    { "text": "сотый раз" }
                 ]
               },
               { "text": "time-slot",
                 "tr": [
                    { "text": "тайм-слот" }
                 ]
               }
            ]
          }
       ]
    }
  ]
}

In the JSONP interface, the same JavaScript objects are returned to a callback function (for example, "myCallback"):

myCallback({
  "head": {},
  "def": [
     { "text": "time", "pos": "noun",
       "tr": [
          { "text": "время", "pos": "существительное",
            "syn": [
               { "text": "раз" },
               { "text": "тайм" }
            ],
            "mean": [
               { "text": "timing" },
               { "text": "fold" },
               { "text": "half"}
            ],
            "ex" : [
               { "text": "prehistoric time",
                 "tr": [
                    { "text": "доисторическое время" }
                 ]
               },
               { "text": "hundredth time",
                 "tr": [
                    { "text": "сотый раз" }
                 ]
               },
               { "text": "time-slot",
                 "tr": [
                    { "text": "тайм-слот" }
                 ]
               }
            ]
          }
       ]
    }
  ]
})