Описание API - Диктую По Буквам

Диктую По Буквам имеет простой 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".

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.