Yandex.Dictionary API Developer's guide

Transcription

1

2 .. Version 1.0 Document build date: This volume is a part of Yandex technical documentation. Yandex helpdesk site: 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. 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 or its components only within credentials granted by the Terms of Use of 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 Phone: pr@yandex-team.ru Headquarters: 16 L'va Tolstogo St., Moscow, Russia

3 Contents About this guide... 4 API description... 4 Formatting results... 4 API methods... 5 getlangs method... 5 lookup method... 6 Index... 10

4 4 About this guide The developer's guide describes the 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 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 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.

5 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 Mandatory key string API key. Get a free API key on this page. Sample request: XML interface: JSON interface: JSONP interface (for the "mycallback" function): 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.

6 API methods 6 In the JSON interface, instead of XML elements, JavaScript objects are returned with the same names and semantics: In the JSONP interface, the same JavaScript objects are returned to a callback function (for example, "mycallback"): 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: JSON interface: JSONP interface (for the "mycallback" function): ["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" 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") 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.

7 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 head def Description Result header (not used). Array of dictionary entries. A transcription of the search word may be provided in the ts attribute.

8 API methods 8 Element tr syn mean ex Description Array of translations. Array of synonyms. Array of meanings. Array of examples. Attributes used in the elements def, tr, syn, mean, and ex Attribute text pos Description Text of the entry, translation, or synonym (mandatory). 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_SUPPOR TED 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", { "text": "время", "pos": "существительное", "syn": [ { "text": "раз", { "text": "тайм", "mean": [ { "text": "timing", { "text": "fold", { "text": "half", "ex" : [ { "text": "prehistoric time", { "text": "доисторическое время", { "text": "hundredth time", { "text": "сотый раз", { "text": "time-slot",

9 API methods 9 { "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", { "text": "время", "pos": "существительное", "syn": [ { "text": "раз", { "text": "тайм", "mean": [ { "text": "timing", { "text": "fold", { "text": "half", "ex" : [ { "text": "prehistoric time", { "text": "доисторическое время", { "text": "hundredth time", { "text": "сотый раз", { "text": "time-slot", { "text": "тайм-слот" )

10 Index getlangs 5 JSON 4 6, 8 JSONP 5, 6, 9 lookup 6 XML 5 7

11