Диктую По Буквам имеет простой REST API который позволяет:
- Получить список всех алфавитов
- Получить подробную информацию об алфавите
- Преобразовать текст с помощью определённого алфавита
Все функции API поддерживают метод JSONP: если запрос содержит параметр callback=functionName
, JSON-ответ сервера будет завёрнут в вызов функции functionName
.
Получение списка алфавитов
Чтобы получить список доступных алфавитов, отправьте GET-запрос следующего формата:
http://api.pobukvam.org/ru/alphabets?format=json[&callback=functionName]
Сервер вернёт JSON-массив с краткой информацией о доступных алфавитах.[ { "id":"int-icao", "language":"Международные", "name":"Международный фонетический алфавит ИКАО" }, { "id":"de-default", "language":"Немецкий", "name":"Немецкий фонетический алфавит" }, { "id":"ru-avia", "language":"Русский", "name":"Русский авиационный радиоалфавит" } ]
Элементы массива имеют следующие поля:
- id
- Идентификатор алфавита, используемый для указания нужного алфавита в других функциях API.
- language
- Язык, для которого используется данный алфавит. Для алфавитов, не привязанных к какому-либо конкретному языку, это поле содержит значение "Международные".
- name
- Название алфавита на русском языке.
Получение подробной информации об алфавите
Чтобы получить информацию о конкретном алфавите, нужно отправить GET-запрос со следующими параметрами:
http://api.pobukvam.org/ru/alphabetInfo?alphabet=int-icao&format=json[&callback=functionName]
Параметры запроса имеют следующее назначение:- alphabet
- Идентификатор алфавита. Список доступных алфавитов (и их ID) можно получить вышеописанным способом.
- format
- Желаемый формат ответа. Если
format=json
, результат запроса будет JSON-строкой, в других случаях ответ будет в HTML-формате.
Ниже приведён пример ответа сервера (отформатированный для наглядности):
{ "alphabet":{ "id":"int-icao", "language":"Международные", "name":"Международный фонетический алфавит ИКАО", "description":"Фонетический алфавит международной авиационной организации, также известный как международный радиотелефонный алфавит...", "source":{ "name":"ICAO", "url":"http://www.icao.int/icao/en/trivia/alphabet.htm" } } }
Объект alphabet
имеет следующие поля:
- id
- Идентификатор алфавита.
- language
- Язык, для которого используется данный алфавит. Для алфавитов, не привязанных к какому-либо конкретному языку, это поле содержит значение "Международные".
- name
- Название алфавита на русском языке.
- description
- Описание алфавита, его история, варианты использования, другая полезная информация.
- source
- Источник информации об алфавите:
- name — название источника (имя человека, название книги или сайта).
- url — гиперссылка на источник (если существует).
Преобразование текста
Чтобы преобразовать по буквам текст, нужно отправить GET или POST запрос со следующими параметрами:
http://api.pobukvam.org/ru/convert?text=some%20text&alphabet=int-icao&format=json[&callback=functionName]
Параметры запроса имеют следующий смысл:- text
- Текст для конверсии (URL-encoded). Максимальная длина текста — 200 символов, остальные будут проигнорированы.
- alphabet
- Идентификатор алфавита, который будет использован для преобразования. Список доступных алфавитов (и их ID) можно получить вышеописанным способом.
- format
- Желаемый формат ответа. Если
format=json
, результат запроса будет JSON-строкой, в других случаях ответ будет в HTML-формате.
Ниже приведён пример ответа сервера (отформатированный для наглядности):
{ "alphabet":{ "id":"int-icao", "language":"Международные", "name":"Международный фонетический алфавит", "description":"Фонетический алфавит международной авиационной организации, также известный как международный радиотелефонный алфавит...", "source":{ "name":"ИКАО", "url":"http://www.icao.int/icao/en/trivia/alphabet.htm" } }, "spelling":[ { "original":"h", "spelling":"Hotel", "format":"text", "isGeneric":false, "midWord":"for" }, { "original":"i", "spelling":"India", "format":"text", "isGeneric":false, "midWord":"for" }, { "original":"!", "spelling":"exclamation mark", "format":"text", "isGeneric":true, "isPunct":true } ] }
Объект alphabet
содержит информацию об алфавите, использованном при конверсии текста. Описание полей находится в разделе "Получение подробной информации об алфавите".
Элементы массива spelling
имеют следующие поля:
- original
- Один или несколько символов исходного текста (например, "h", "ae" или "sch"), в виде url-encoded строки.
- spelling
- Кодовое слово ассоциированное с исходным символом (url-encoded строка). Формат содержимого определяется полем
format
. - format (необязательный)
- Формат поля
spelling
. Может принимать одно из следующих значений:- "text" — Поле
spelling
содержит HTML или простой текст. - "img" — Поле
spelling
содержит ссылку на изображение или само изображение (закодированное в data:URI).
format
не задано, по умолчанию принимается формат "text". - "text" — Поле
- isGeneric
- Указывает, взято ли правило конверсии из самого алфавита (
false
). Если использованный алфавит не содержит правила для данного исходного символа (например, для знаков пунктуации), правило берётся из набора общих правил для данного языка (true
). - translation (необязательный)
- Вспомогательное кодовое слово (в url-encoded виде). Это может быть или перевод слова указанного в spelling, или альтернативное кодовое слово ("а" — "Антон", "Александр"). Если
spelling
задаёт изображение (format="img"
),translation
задаёт текстовое описание этой картинки, которое можно поместить в атрибут "alt" тега <img>. - midWord (необязательный)
- Слово-связка (на языке алфавита), используемое между исходной буквой и кодовым словом (url-encoded строка). Например, "a for Alpha" (по-английски), "b come Bologna" (по-итальянски), и т.п.
- isPunct (необязательный)
- Указывает, является ли исходный символ символом пунктуации (true) или буквой/цифрой (false). Если поле
isPunct
не задано, по умолчанию принимается значение false.