Spell Out provides a simple REST API. There are three function available that enable you to:

All API functions support the JSONP method: if an optional request parameter callback=functionName is specified, the JSON response will be wrapped into a functionName() call.

Getting available alphabets

To acquire the list of available alphabets, send a GET request to the following address:

http://api.spellout.org/en/alphabets?format=json[&callback=functionName]

The server will return a JSON array containing brief information about the alphabets.

[
    {
        "id":"int-icao",
        "language":"International",
        "name":"ICAO phonetic alphabet"
    },
    {
        "id":"de-default",
        "language":"German",
        "name":"The official German spelling alphabet"
    },
    {
        "id":"ru-default",
        "language":"Russian",
        "name":"The official Russian phonetic alphabet"
    }
]

Array items have the following properties:

id
An internal ID of the alphabet. This ID is used for specifying the alphabet in other API functions.
language
The language for which the alphabet is used. For language-independent alphabets it is set to "International".
name
Alphabet name in a human-readable form.

Getting information about alphabet

To get information about an alphabet, send a GET request with the following parameters:

http://api.spellout.org/en/alphabetInfo?alphabet=int-icao&format=json[&callback=functionName]

The request parameters have the following meaning:
alphabet
The ID of the alphabet. Available alphabet IDs can be acquired as described above.
format
Specifies the desired response format. If set to json, the output will be a JSON string (recommended); otherwise the result will be in HTML.
callback
If this optional parameter is specified, the result will be wrapped into a function call with the name specified by the callback value (for more details, see JSONP).

Here is an example of server response (formatted for better legibility):

{
    "alphabet":{
        "id":"int-icao",
        "language":"International",
        "name":"ICAO phonetic alphabet",
        "description":"The ICAO phonetic alphabet is...",
        "source":{
                "name":"ICAO",
                "url":"http://www.icao.int/icao/en/trivia/alphabet.htm"
        }
    }
}

The alphabet object has the following properties:

id
Alphabet's ID.
language
The language for which the alphabet is used. For language-independent alphabets it is set to "International".
name
Alphabet name in a human-readable form.
description
The description of the alphabet, its history, application scenarios, other related information.
source
The source of information about the alphabet:
  • name — name of the source (contributor's name, book title, website name, etc).
  • url — link to the source page (if one exists).

Converting text

To spell out a text, send a GET or POST request with the following parameters:

http://api.spellout.org/en/convert?text=some%20text&alphabet=int-icao&format=json[&callback=functionName]

The request parameters have the following meaning:
text
A URL-encoded text to be converted. Text length should be within 200 characters, any extra will be ignored.
alphabet
The ID of the alphabet to be used for conversion. The list of available alphabets and their IDs can be acquired as described above.
format
Specifies the response format. If set to json, the output will be a JSON string (recommended); otherwise the result will be in HTML.
callback
If this optional parameter is specified, the spelling result will be wrapped into a function call with the name specified by the callback value (for more details, see JSONP).

Here is an example of server response (formatted for better legibility):

{
    "alphabet":{
        "id":"int-icao",
        "language":"International",
        "name":"ICAO phonetic alphabet",
        "description":"The ICAO phonetic alphabet is...",
        "source":{
                "name":"ICAO",
                "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
        }
    ]
}

The alphabet object contains information about the alphabet used for conversion. For more details, see "Getting information about alphabet".

The items of the spelling array have the following properties:

original
The original symbol or symbols (such as "ae" or "sch") as a url-encoded string.
spelling
The spelling associated with the original (in url-encoded form). The format of string is defined by the format property.
format (optional)
The format of the spelling item. It takes one of the following values:
  • "text" — The spelling property contains HTML or plain text.
  • "img" — The spelling property contains a URL of an image or a data:URI-encoded image itself.
If the format property is not specified, the default spelling format is "text".
isGeneric
Indicates whether the applied conversion rule is a generic one (true) or has been taken from the spelling alphabet (false). In some cases, the spelling alphabet does not contain a suitable conversion rule; this is often the case for punctuation symbols. In these cases, one of the generic rules for the alphabet's language is applied.
translation (optional)
A url-encoded string with either an alternative spelling, or spelling translation. If spelling relates to an image, this property specifies its 'alt' attribute.
midWord (optional)
A url-encoded string with the word which links the original and the spelling in the alphabet's language. For example, "a for Alpha" (English), "b come Bologna" (Italian), etc.
isPunct (optional)
If defined, isPunct indicates whether the spelling item is a punctuation mark (true) or a letter/number (false). If isPunct is not defined, it defaults to false.