Yandex.Dictionary API Developer's guide

Yandex.Dictionary API Developer's guide 12.01.2017 Yandex.Dictionary API. Developer's guide. Version 1.0 Document build date: 12.01.2017. This volum...
Author: Beverly Long
0 downloads 1 Views 236KB Size
Yandex.Dictionary API Developer's guide 12.01.2017

Yandex.Dictionary API. Developer's guide. Version 1.0 Document build date: 12.01.2017. This volume is a part of Yandex technical documentation. Yandex helpdesk site: http://help.yandex.ru © 2008—2017 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: [email protected] 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 https://tech.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: ru-ru ru-en ru-pl ru-uk ru-de ru-fr ... it-ru it-en tr-ru tr-en

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: time время раз тайм timing fold half prehistoric time доисторическое время hundredth time сотый раз time-slot тайм-слот

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 12.01.2017