Yandex.

Translate API
Developer's guide
2.07.2013

Yandex.Translate API. Developer's guide. Version 1.5 Document build date: 2.07.2013. This volume is a part of Yandex technical documentation. Yandex helpdesk site: http://help.yandex.ru 20082013 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.Translate 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.Translate API or its components only within credentials granted by the Terms of Use of Yandex.Translate 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 detect method ............................................................................................................................................................................... 6 translate method ........................................................................................................................................................................... 8 Index .................................................................................................................................................................................................. 11

Yandex.Translate API

Developer's guide

Developer's guide

About this guide

The developer's guide describes the Yandex.Translate API and explains how to enable and use the service. The guide is intended for web developers who want to add the text translation feature to pages on their web sites.

API description
Attention! Starting from version 1.5, all API methods must be accessed using a key. Please fill out this simple form to get your free API key.

To access the Yandex.Translate 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. The API can be accessed using the following URLs: XML interface:
https://translate.yandex.net/api/v1.5/tr

JSON and JSOP interfaces:

https://translate.yandex.net/api/v1.5/tr.json

Note: To enable the JSONP interface, pass an additional callback parameter with the name of the callback function.

Formatting results
When formatting translation results, you must follow the rules set in the License for using the Yandex.Translate service. Each page that uses data from the Yandex.Translate service must display the text "Translated by the Yandex.Translate service" with an active hyperlink to the page http://translate.yandex.com/. 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.Translate API

Developer's guide

API methods 5

API methods
getLangs method
Returns a list of translation directions supported by the service.

Description
Langs getLangs(string key, string ui);

Input parameters
List of input parameters: Parameter
Mandatory key Optional ui string If set, the service's response will contain a list of language codes and corresponding names of languages: en in English ru in Russian tr in Turkish uk in Ukrainian string API key. Get a free API key on this page.

Type

Description

Sample request: XML interface:

https://translate.yandex.net/api/v1.5/tr/getLangs?key=APIkey&ui=uk

JSON interface:
https://translate.yandex.net/api/v1.5/tr.json/getLangs?key=APIkey&ui=uk

JSONP interface (for the "myCallback" function):

https://translate.yandex.net/api/v1.5/tr.json/getLang? key=APIkey&ui=uk&callback=myCallback

Returns
In the XML interface it returns an XML document with the root element Langs. For example:
<?xml version="1.0" encoding="utf-8"?> <Langs> <dirs> <string>ru-en</string> <string>ru-pl</string> <string>ru-uk</string> <string>ru-de</string> <string>ru-fr</string> ... <string>sr-uk</string>

Yandex.Translate API

Developer's guide

API methods 6

</dirs> <langs> <Item key="ru" value=""/> <Item key="en" value=""/> <Item key="pl" value=""/> ... <Item key="tr" value=""/> <Item key="ro" value=""/> <Item key="sr" value=""/></langs> </Langs>

Error codes Code

ERR_KEY_INVALID ERR_KEY_BLOCKED

Value
401 402

Description
Invalid API key. This API key has been blocked.

In the JSON interface, instead of XML elements, JavaScript objects are returned with the same names and semantics:
{"dirs": ["ru-en","ru-pl","ru-uk","ru-de","ru-fr","ru-es","ru-it","ru-bg","ru-cs","rutr","ru-ro","ru-sr","en-ru","en-uk","en-de","en-fr","en-es","en-it","en-cs","entr","pl-ru","pl-uk","uk-ru","uk-en","uk-pl","uk-de","uk-fr","uk-es","uk-it","ukbg","uk-cs","uk-tr","uk-ro","uk-sr","de-ru","de-en","de-uk","fr-ru","fr-en","fruk","es-ru","es-en","es-uk","it-ru","it-en","it-uk","bg-ru","bg-uk","cs-ru","csen","cs-uk","tr-ru","tr-en","tr-uk","ro-ru","ro-uk","sr-ru","sr-uk"], "langs": {"ru":"","en":"","pl":"","uk":"","de":" ","fr":"","es":"","it":"","bg":"","cs ":"","tr":"","ro":"","sr":""} }

In the JSONP interface, the same JavaScript objects are returned to a callback function (for example, "myCallback"):
myCallback( {"dirs":["ru-en","ru-pl","ru-uk","ru-de","ru-fr","ru-es","ru-it","ru-bg","rucs","ru-tr","ru-ro","ru-sr","en-ru","en-uk","en-de","en-fr","en-es","en-it","encs","en-tr","pl-ru","pl-uk","uk-ru","uk-en","uk-pl","uk-de","uk-fr","uk-es","ukit","uk-bg","uk-cs","uk-tr","uk-ro","uk-sr","de-ru","de-en","de-uk","fr-ru","fren","fr-uk","es-ru","es-en","es-uk","it-ru","it-en","it-uk","bg-ru","bg-uk","csru","cs-en","cs-uk","tr-ru","tr-en","tr-uk","ro-ru","ro-uk","sr-ru","sr-uk"], "langs": {"ru":"","en":"","pl":"","uk":"","de":" ","fr":"","es":"","it":"","bg":"","cs ":"","tr":"","ro":"","sr":""} })

detect method
Detects the language of the specified text.

Description
DetectedLang detect(string key, string text[], string format);

Yandex.Translate API

Developer's guide

API methods 7

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. Parameter
Mandatory key text string API key. Get a free API key on this page. string[ The text to detect the language for. ] Restrictions: Although the text parameter is an array (you can pass multiple text parameters), only one language tag is returned for the entire text. To detect the language of each text item, call the detect method for each of them. Optional format string Text format. Possible values: plain Text without markup (default value). html Text in HTML format.

Type

Description

Sample request: XML interface:

https://translate.yandex.net/api/v1.5/tr/detect?key=APIkey&text=Hello+world

JSON interface:
https://translate.yandex.net/api/v1.5/tr.json/detect?key=APIkey&text=Hello+world

JSONP interface (for the "myCallback" function):

https://translate.yandex.net/api/v1.5/tr.json/detect?key=APIkey&text=Hello +world&callback=myCallback

Returns
In the XML interface it returns the DetectedLang structure, which contains the return code (200 if successful) and the text language code (or an empty string, if the language could not be detected). For example:
<?xml version="1.0" encoding="utf-8"?> <DetectedLang code="200" lang="en"/>

Error codes Code

ERR_OK ERR_KEY_INVALID ERR_KEY_BLOCKED

Value
200 401 402

Description
Operation completed successfully. Invalid API key. This API key has been blocked. You have reached the daily limit for requests (including calls of the translate method). You have reached the daily limit for the volume of translated text (including calls of the translate method).

ERR_DAILY_REQ_LIMIT 403 _EXCEEDED ERR_DAILY_CHAR_LIMI 404 T_EXCEEDED

Yandex.Translate API

Developer's guide

API methods 8

In the JSON interface, instead of XML elements, JavaScript objects are returned with the same names and semantics:
{ "code": 200, "lang": "en" }

In the JSONP interface, the same JavaScript objects are returned to a callback function (for example, "myCallback"):
myCallback([ { "code": 200, "lang": "en" } ])

translate method
Translates the text.

Description
Translation translate(string key, string lang, string text[], string format, string options);

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://translate.yandex.net/api/v1.5/tr/translate?key=APIkey&lang=en-ru&text=To +be,+or+not+to+be%3F&text=That+is+the+question.

JSON interface:
https://translate.yandex.net/api/v1.5/tr.json/translate?key=APIkey&lang=enru&text=To+be,+or+not+to+be%3F&text=That+is+the+question.

JSONP interface (for the "myCallback" function):

https://translate.yandex.net/api/v1.5/tr.json/translate?key=APIkey&lang=enru&text=To+be,+or+not+to+be%3F&text=That+is+the+question.&callback=myCallback

List of input parameters. Parameter

Mandatory key lang string string API key. Get a free API key on this page. Translation direction (for example, "en-ru" or "ru"). Format: 1. 2. A pair of language codes separated by a dash. For example, "en-ru" specifies to translate from English to Russian. Single language code. For example, "ru" specifies to translate to Russian. In this case, the language of the original text is detected automatically.

Type

Description

Yandex.Translate API

Developer's guide

API methods 9

Parameter
text

Type

Description

string[ The text to be translated. ] Restrictions: For POST requests, the maximum size of the text being passed is 10000 characters. In GET requests, the restriction applies not to the text itself, but to the size of the entire request string, which can contain other parameters besides the text. The maximum size of the request string is 10 KB.

Optional format string Text format. Possible values: options string plain Text without markup (default value). html Text in HTML format.

Translation options. Possible values: 1 Automatically detect language. For example, if the lang parameter has reversed the translation direction for a pair, the service automatically detects the text language and returns it in the detected tag:
http://translate.yandex.net/api/v1.5/tr/translate? key=APIkey&lang=en-ru&text=&options=1 <Translation code="200" lang="en-ru"> <detected lang="ru"/> <text></text> </Translation>

Returns
In the XML interface, it returns the Translation structure, which contains the translated text. For example:
<?xml version="1.0" encoding="utf-8"?> <Translation code="200" lang="en-ru"> <text> ?</text> <text> .</text> </Translation>

Elements of the response XML schema: Translation The root element, which contains text elements (one per fragment). The code attribute contains the return code (see the table) and the lang attribute, which is the language code of the text fragment detected by the service. text An array of strings with translated text (for the XML interface, a sequence of <text> elements). The number of items in the array corresponds to the number of text parameters in the request.

Error codes Code

ERR_OK ERR_KEY_INVALID ERR_KEY_BLOCKED

Value
200 401 402

Description
Operation completed successfully. Invalid API key. This API key has been blocked. You have reached the daily limit for requests (including calls of the detect method).

ERR_DAILY_REQ_LIMIT 403 _EXCEEDED

Yandex.Translate API

Developer's guide

API methods 10

Code

Value

Description
You have reached the daily limit for the volume of translated text (including calls of the detect method). The text size exceeds the maximum. The text could not be translated. The specified translation direction is not supported.

ERR_DAILY_CHAR_LIMI 404 T_EXCEEDED ERR_TEXT_TOO_LONG 413

ERR_UNPROCESSABLE_T 422 EXT ERR_LANG_NOT_SUPPOR 501 TED

In the JSON interface, instead of XML elements, JavaScript objects are returned with the same names and semantics:
{ "code": 200, "lang": "en-ru", "text": [ " ?", " ." ] }

In the JSONP interface, the same JavaScript objects are returned to a callback function (for example, "myCallback"):
myCallback({ "code": 200, "lang": "en-ru", "text": [ " ?", " ." ] })

Yandex.Translate API

Developer's guide

Index
detect 6 getLangs 5 JSON 48, 10 JSONP 58, 10 translate 8 XML 5, 79

Yandex.Translate API

Developer's guide

Yandex.Translate API
Developer's guide 2.07.2013