---
keywords:
  - lookup
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/tech-only/doc/dg/en/llms.txt


# lookup method

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

## Description

```javascript
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](https://yandex.com/dev/dictionary/keys/get/?service=dict).
||
||
`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.

{% note 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.

{% endnote %}
||
||
`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. This flag should also be set for receiving translations.
- `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](*head)/>
  <[def](*def) pos="noun" ts="taɪm">
    <[text](*text)>time</text>
    <[tr](*tr) pos="существительное">
      <[text](*text)>время</text>
      <[syn](*syn)>
        <[text](*text)>раз</text>
      </syn>
      <[syn](*syn)>
        <[text](*text)>тайм</text>
      </syn>
      <[mean](*mean)>
        <[text](*text)>timing</text>
      </mean>
      <[mean](*mean)>
        <[text](*text)>fold</text>
      </mean>
      <[mean](*mean)>
         <[text](*text)>half</text>
      </mean>
      <[ex](*ex)>
         <[text](*text)>prehistoric time</text>
         <[tr](*tr)>
            <[text](*text)>доисторическое время</text>
         </tr>
      </ex>
      <[ex](*ex)>
         <[text](*text)>hundredth time</text>
         <[tr](*tr)>
            <[text](*text)>сотый раз</text>
         </tr>
      </ex>
      <[ex](*ex)>
         <[text](*text)>time-slot</text>
         <[tr](*tr)>
            <[text](*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:

```javascript
{ "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"):

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

[*head]: {% include notitle [head](../_includes/hints.md#head) %}

[*def]: {% include notitle [def](../_includes/hints.md#def) %}

[*text]: {% include notitle [text](../_includes/hints.md#text) %}

[*tr]: {% include notitle [tr](../_includes/hints.md#tr) %}

[*syn]: {% include notitle [syn](../_includes/hints.md#syn) %}

[*mean]: {% include notitle [mean](../_includes/hints.md#mean) %}

[*ex]: {% include notitle [ex](../_includes/hints.md#ex) %}