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.

Parameter Type Description
Mandatory
key string API key. Get a free API key on this page.
lang string

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.
text string

The word or phrase to find in the dictionary.

Optional
ui string

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

flags int

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
Element Description
head Result header (not used).
def Array of dictionary entries. A transcription of the search word may be provided in the ts attribute.
tr Array of translations.
syn Array of synonyms.
mean Array of meanings.
ex Array of examples.
Attributes used in the elements def, tr, syn, mean, and ex
Attribute Description
text Text of the entry, translation, or synonym (mandatory).
pos Part of speech (may be omitted).

Error codes
Code Value Description
ERR_OK 200

Operation completed successfully.

ERR_KEY_INVALID 401

Invalid API key.

ERR_KEY_BLOCKED 402

This API key has been blocked.

ERR_DAILY_REQ_LIMIT_EXCEEDED 403

Exceeded the daily limit on the number of requests.

ERR_TEXT_TOO_LONG 413

The text size exceeds the maximum.

ERR_LANG_NOT_SUPPORTED 501

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": "тайм-слот" }
                 ]
               }
            ]
          }
       ]
    }
  ]
})