Yandex.Dictionary API. Developer`s guide

Yandex.Dictionary API
Developer's guide
26.02.2015
Yandex.Dictionary API. Developer's guide. Version 1.0
Document build date: 26.02.2015.
This volume is a part of Yandex technical documentation.
Yandex helpdesk site: http://help.yandex.ru
© 2008—2015 Yandex LLC. All rights reserved.
Copyright Disclaimer
Yandex (and its applicable licensor) has exclusive rights for all results of intellectual activity and equated to them means of individualization, used for development, support,
and usage of the service Yandex.Dictionary API. It may include, but not limited to, computer programs (software), databases, images, texts, other works and inventions, utility
models, trademarks, service marks, and commercial denominations. The copyright is protected under provision of Part 4 of the Russian Civil Code and international laws.
You may use Yandex.Dictionary API or its components only within credentials granted by the Terms of Use of Yandex.Dictionary API or within an appropriate Agreement.
Any infringements of exclusive rights of the copyright owner are punishable under civil, administrative or criminal Russian laws.
Contact information
Yandex LLC
http://www.yandex.com
Phone: +7 495 739 7000
Email: pr@yandex-team.ru
Headquarters: 16 L'va Tolstogo St., Moscow, Russia 119021
Contents
About this guide ................................................................................................................................................................................... 4
API description .................................................................................................................................................................................... 4
Formatting results ................................................................................................................................................................................ 4
API methods ....................................................................................................................................................................................... 5
getLangs method .......................................................................................................................................................................... 5
lookup method ............................................................................................................................................................................. 6
Index .................................................................................................................................................................................................. 10
Yandex.Dictionary API
Developer's guide
Developer's guide
About this guide
The developer's guide describes the Yandex.Dictionary API and explains how to enable and use the service.
The guide is intended for web developers who want their web site pages to have a feature that searches for words
in the Yandex online dictionary.
API description
Attention!
All API methods are accessed using a key. Please fill out this simple form to get your free API key.
To access the Yandex.Dictionary API over HTTP, there are XML and JSON (JSONP) interfaces available.
All the interfaces provide identical functionality and use the same set of input parameters.
The XML interface returns a response in the form of an XML document, while the JSON interface returns
JavaScript objects instead of XML elements, but with the same names and semantics; the JSONP interface
returns the same JavaScript objects, but by calling a callback function with the specified name.
Formatting results
When formatting translation results, you must follow the rules set in the License for using the Yandex.Dictionary
service.
Each page that uses data from the Yandex.Dictionary service must display the text "Powered
by Yandex.Dictionary" with an active hyperlink to the page http://api.yandex.com/dictionary/.
The font size for the link must be no smaller than the font size for the main text, and the color must match the font
color of the main text on the page.
Yandex.Dictionary API
Developer's guide
4
API methods 5
API methods
getLangs method
Returns a list of translation directions supported by the service.
Description
string[] getLangs(string key);
Input parameters
List of input parameters:
Parameter
Type
Description
string
API key. Get a free API key on this page.
Mandatory
key
Sample request:
XML interface:
https://dictionary.yandex.net/api/v1/dicservice/getLangs?key=APIkey
JSON interface:
https://dictionary.yandex.net/api/v1/dicservice.json/getLangs?key=APIkey
JSONP interface (for the "myCallback" function):
https://dictionary.yandex.net/api/v1/dicservice.json/getLangs?
key=APIkey&callback=myCallback
Returns
In the XML interface it returns an XML document with the root element ArrayOfString. For example:
<?xml version="1.0" encoding="utf-8"?>
<ArrayOfString>
<string>ru-ru</string>
<string>ru-en</string>
<string>ru-pl</string>
<string>ru-uk</string>
<string>ru-de</string>
<string>ru-fr</string>
...
<string>it-ru</string>
<string>it-en</string>
<string>tr-ru</string>
<string>tr-en</string>
</ArrayOfString>
Error codes
Code
Value
Description
ERR_KEY_INVALID
401
Invalid API key.
ERR_KEY_BLOCKED
402
This API key has been blocked.
Yandex.Dictionary API
Developer's guide
API methods 6
In the JSON interface, instead of XML elements, JavaScript objects are returned with the same names
and semantics:
["ru-ru","ru-en","ru-pl","ru-uk","ru-de","ru-fr","ru-es","ru-it","ru-tr","enru","en-en","en-de","en-fr","en-es","en-it","en-tr","pl-ru","uk-ru","de-ru","deen","fr-ru","fr-en","es-ru","es-en","it-ru","it-en","tr-ru","tr-en"]
In the JSONP interface, the same JavaScript objects are returned to a callback function (for example,
"myCallback"):
myCallback(["ru-ru","ru-en","ru-pl","ru-uk","ru-de","ru-fr","ru-es","ru-it","rutr","en-ru","en-en","en-de","en-fr","en-es","en-it","en-tr","pl-ru","uk-ru","deru","de-en","fr-ru","fr-en","es-ru","es-en","it-ru","it-en","tr-ru","tr-en"])
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=enru&text=time
JSON interface:
https://dictionary.yandex.net/api/v1/dicservice.json/lookup?key=APIkey&lang=enru&text=time
JSONP interface (for the "myCallback" function):
https://dictionary.yandex.net/api/v1/dicservice.json/lookup?key=API&lang=enru&text=time&callback=myCallback
List of input parameters.
Parameter
Type
Description
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.
Mandatory
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.
string
The language of the user's interface for displaying names of parts of speech in the dictionary
entry.
Optional
ui
Yandex.Dictionary API
Developer's guide
API methods 7
Parameter
Type
Description
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.
Yandex.Dictionary API
Developer's guide
API methods 8
Element
Description
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 403
_EXCEEDED
Exceeded the daily limit on the number of requests.
ERR_TEXT_TOO_LONG
The text size exceeds the maximum.
413
ERR_LANG_NOT_SUPPOR 501
TED
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",
Yandex.Dictionary API
Developer's guide
API methods 9
"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": "тайм-слот" }
]
}
]
}
]
}
]
})
Yandex.Dictionary API
Developer's guide
Index
getLangs 5
JSON 4–6, 8
JSONP 5, 6, 9
lookup 6
XML 5–7
Yandex.Dictionary API
Developer's guide
Yandex.Dictionary API
Developer's guide
26.02.2015