Translating a text

JSON and JSONP interfaces

The response is returned in JSON format. If the callback parameter is set, the JSON object is wrapped in a function. The function name is specified in this parameter (JSONP).

Request syntax

https://translate.yandex.net/api/v1.5/tr.json/translate
 ? [key=<API key>]
 & [text=<text to translate>]
 & [lang=<translation direction>]
 & [format=<text format>]
 & [options=<translation options>]
 & [callback=<callback function name>]
Query parameters
key

API key.

text

The text to be translated.

You can use several text parameters in the request.

Attention.

For the source text, use the URL encoding.

Limitations:

  • For POST requests, the maximum size of the text you pass is 10,000 characters.
  • In GET requests, limits aren't set on the text you pass. Instead, they're set on the entire query string that may include other parameters besides the text.

    The maximum line size is from 2 to 10 KB (depending on the browser version).

lang

Translation direction.

Can be set using one of the following methods:

  • With a pair of language codes (“from”-“to”) separated with a hyphen. For example, en-ru indicates a translation from English to Russian.
  • With a target language code (for example ru). In this case, the service tries to detect the source language automatically.
format

Text format.

Possible values:

  • plain: Text without markup (default value).
  • html: Text in HTML format.
options

Currently, the only available option is to include the automatically defined source language in the response. This corresponds to the parameter value 1.

If the source language is set explicitly, meaning the lang parameter contains a pair of codes, the fist code sets the source language. This means that the options parameter doesn't let you switch to automatic language detection. However, it lets you know whether the source language was specified correctly in the lang parameter.

callbackName of the callback function. Used to get a JSONP response.
Note. All special characters must be escaped.

XML interface

The response is returned in XML format.

Request syntax

https://translate.yandex.net/api/v1.5/tr/translate
 ? [key=<API key>]
 & [text=<text to translate>]
 & [lang=<translation direction>]
 & [format=<text format>]
 & [options=<translation options>]
Query parameters
key

API key.

text

The text to be translated.

You can use several text parameters in the request.

Attention.

For the source text, use the URL encoding.

Limitations:

  • For POST requests, the maximum size of the text you pass is 10,000 characters.
  • In GET requests, limits aren't set on the text you pass. Instead, they're set on the entire query string that may include other parameters besides the text.

    The maximum line size is from 2 to 10 KB (depending on the browser version).

lang

Translation direction.

Can be set using one of the following methods:

  • With a pair of language codes (“from”-“to”) separated with a hyphen. For example, en-ru indicates a translation from English to Russian.
  • With a target language code (for example ru). In this case, the service tries to detect the source language automatically.
format

Text format.

Possible values:

  • plain: Text without markup (default value).
  • html: Text in HTML format.
options

Currently, the only available option is to include the automatically defined source language in the response. This corresponds to the parameter value 1.

If the source language is set explicitly, meaning the lang parameter contains a pair of codes, the fist code sets the source language. This means that the options parameter doesn't let you switch to automatic language detection. However, it lets you know whether the source language was specified correctly in the lang parameter.

Note. All special characters must be escaped.

Response codes

Description of response codes.

Value Description
200

The operation was completed successfully

401

Invalid API key

402

The API key is blocked

404

The daily limit on the amount of translated text is exceeded

413

The maximum allowed text size is exceeded

422

The text can't be translated

501

The specified translation direction isn't supported