Yandex.Translate API. Developer`s guide

Transcription

Yandex.Translate API
Developer's guide
11.06.2015
Yandex.Translate API. Developer's guide. Version 1.5
Document build date: 11.06.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.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: [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
detect method ............................................................................................................................................................................... 7
translate method ........................................................................................................................................................................... 8
Supported languages .......................................................................................................................................................................... 11
Index .................................................................................................................................................................................................. 13
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 HTTPS, 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.Translate
service.
Each page that uses data from the Yandex.Translate service must display the text "Powered
by Yandex.Translate" 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.
Developer's guide
4
API methods 5
API methods
getLangs method
Returns a list of translation directions supported by the service.
Description
Langs getLangs(string key, string ui);
The service translates between any of the languages in the list of supported languages. To get this list, set the
ui parameter when calling the method.
Input parameters
List of input parameters:
Parameter
Type
Description
string
API key. Get a free API key on this page.
string
If set, the service's response will contain a list of supported language codes and the
corresponding language names (langs):
Mandatory
key
Optional
ui
•
en — in English
•
ru — in Russian
•
tr — in Turkish
•
uk — in Ukrainian
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/getLangs?
key=APIkey&ui=uk&callback=myCallback
Returns
In the XML interface it returns an XML document with the root element Langs. For example:
Developer's guide
API methods 6
<?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>
</dirs>
<langs>
<Item key="ru" value="Russian"/>
<Item key="en" value="English"/>
<Item key="pl" value="Polish"/>
...
<Item key="tr" value="Turkish"/>
<Item key="ro" value="Romanian"/>
<Item key="sr" value="Serbian"/>
</langs>
</Langs>
Error codes
Code
Value
Description
ERR_KEY_INVALID
401
Invalid API key.
ERR_KEY_BLOCKED
402
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":"сербська"}
})
Developer's guide
API methods 7
detect method
Detects the language of the specified text.
Description
DetectedLang detect(string key, string text[], string format);
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
Type
Description
key
string
text
string[ The text to detect the language for.
]
Restrictions:
Mandatory
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.
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
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:
<DetectedLang code="200" lang="en"/>
Error codes
Code
Value
Description
ERR_OK
200
Operation completed successfully.
Developer's guide
API methods 8
Code
Value
Description
ERR_KEY_INVALID
401
Invalid API key.
ERR_KEY_BLOCKED
402
ERR_DAILY_REQ_LIMIT 403
_EXCEEDED
You have reached the daily limit for requests (including calls of the
translate method).
ERR_DAILY_CHAR_LIMI 404
T_EXCEEDED
You have reached the daily limit for the volume of translated text
(including calls of the translate method).
and semantics:
{
"code": 200,
"lang": "en"
}
"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.
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
Developer's guide
API methods 9
List of input parameters.
Parameter
Type
Description
key
string
lang
string
Translation direction (for example, "en-ru" or "ru"). Format:
Mandatory
text
1.
A pair of language codes separated by a dash. For example, "en-ru" specifies to translate
from English to Russian.
2.
Single language code. For example, "ru" specifies to translate to Russian. In this case,
the language of the original text is detected automatically.
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:
https://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:
<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.
Developer's guide
API methods 10
Error codes
Code
Value
Description
ERR_OK
200
Operation completed successfully.
ERR_KEY_INVALID
401
Invalid API key.
ERR_KEY_BLOCKED
402
ERR_DAILY_REQ_LIMIT 403
_EXCEEDED
You have reached the daily limit for requests (including calls of the
detect method).
ERR_DAILY_CHAR_LIMI 404
T_EXCEEDED
You have reached the daily limit for the volume of translated text
(including calls of the detect method).
ERR_TEXT_TOO_LONG
The text size exceeds the maximum.
413
ERR_UNPROCESSABLE_T 422
EXT
The text could not be translated.
ERR_LANG_NOT_SUPPOR 501
TED
The specified translation direction is not supported.
and semantics:
{
"code": 200,
"lang": "en-ru",
"text": [
"Быть или не быть?",
"Вот в чем вопрос."
]
}
"myCallback"):
myCallback({
"code": 200,
"lang": "en-ru",
"text": [
"Быть или не быть?",
"Вот в чем вопрос."
]
})
Developer's guide
Developer's guide
Supported languages
Язык
Код
Albanian
sq
Arabian
ar
Armenian
hy
Azeri
az
Belarusian
be
Bosnian
bs
Bulgarian
bg
Catalan
ca
Croatian
hr
Czech
cs
Chinese
zh
Danish
da
Dutch
nl
English
en
Estonian
et
Finnish
fi
French
fr
Georgian
ka
German
de
Greek
el
Hebrew
he
Hungarian
hu
Icelandic
is
Indonesian
id
Italian
it
Japanese
ja
Korean
ko
Latvian
lv
Lithuanian
lt
Macedonian
mk
Malay
ms
Maltese
mt
Norwegian
no
Polish
pl
Portuguese
pt
Romanian
ro
Russian
ru
Spanish
es
Serbian
sr
Slovak
sk
Slovenian
sl
Swedish
sv
Developer's guide
11
Developer's guide
Язык
Код
Thai
th
Turkish
tr
Ukrainian
uk
Vietnamese
vi
Developer's guide
12
Index
detect 6
getLangs 5
JSON 4–8, 10
JSONP 5–8, 10
translate 8
XML 5, 7–9
Developer's guide
Developer's guide
11.06.2015

Yandex.Translate API. Developer`s guide

Transcription

Similar documents

Gabe Westmaas Rackspace @westmaas

Sze Wong | CEO | Zerion Software, Inc.

Practical 5: OpenWeatherMap Objective Development of Web Applications Vincent Simonet, 2014-2015

Cyprexx Enhanced

The 13th National Chil

presentation slides

2015 IEEE PES ASIA - PACIFIC POWER AND ENERGY

Yandex.Dictionary API. Developer`s guide

APIs as a Foundation for Systems of Engagement

YPP CHRISTMAS EVENT