Spell Out provides a simple REST API. There are three function available that enable you to:
- Get the list of available alphabets
- Get information about an alphabet
- Convert a text using specific alphabet
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.
format
property is not specified, the default spelling format is "text". - "text" — The
- 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). IfisPunct
is not defined, it defaults to false.