Text prediction REST API, v2.4


word/random

Returns random words drawn from the vocabulary.

Parameter Required/optional Description Valid values Default
num
Optional Number of results Positive integer 5
vocab
Optional Name of vocabulary to draw words from 1k, 5k, 10k, 20k, 40k, 100k, 500k 100k
sort
Optional Sorting of result words alpha = sort alphabetically A-Z
rev-alpha = sort reverse alphabetically Z-A
(none)
safe
Optional Safe mode, filters obscene words. true or false false
prefix
Optional Prefix of random words Sequence of one or more characters (none)
suffix
Optional Suffix of random words Sequence of one or more characters (none)
substring
Optional Substring that must occur in random words Sequence of one or more characters (none)
lang
Optional Language code Language to use (see list) en

Example:


word/predict

Predict the most likely words based on what is to the left, right, and/or the prefix of the current word.

Parameter Required/optional Description Valid values Default
left
Optional Left text context One or more words separated by spaces (none)
right
Optional Right text context One or more words separated by spaces (none)
prefix
Optional Prefix of current word Sequence of one or more characters (none)
num
Optional Number of results Positive integer 5
vocab
Optional Filter to words in this vocabulary 1k, 5k, 10k, 20k, 40k, 100k, 500k 100k
sort
Optional Sorting of result words alpha = alphabetically A-Z
rev-alpha = reverse alphabetically Z-A
logprob = log probability, largest first
rev-logprob = log probability, smallest first
logprob
safe
Optional Safe mode, filters obscene words. true or false false
lang
Optional Language code Language to use (see list) en

Example:


word/predict/future

Predict the most likely words based on all possible future characters and what is to the left, right, and/or the prefix of the current word. This is useful for interfaces that want to cache future predictions in order to hide API latency.

Parameter Required/optional Description Valid values Default
left
Optional Left text context One or more words separated by spaces (none)
right
Optional Right text context One or more words separated by spaces (none)
prefix
Optional Prefix of current word Sequence of one or more characters (none)
num
Optional Number of results Positive integer 5
vocab
Optional Filter to words in this vocabulary 1k, 5k, 10k, 20k, 40k, 100k, 500k 100k
sort
Optional Sorting of result words alpha = alphabetically A-Z
rev-alpha = reverse alphabetically Z-A
logprob = log probability of next character, largest first
rev-logprob = log probability of next character, smallest first
logprob-next = word set max log probability, largest first
rev-logprob-next = word set max log probability, smallest first
logprob
safe
Optional Safe mode, filters obscene words. true or false false
lang
Optional Language code Language to use (see list) en

Example:


word/predict/next/future

Predict the most likely words based on the words predictions based on a given left context, prefix, and right context. This is useful for interfaces that want to cache future predictions in order to hide API latency.

Parameter Required/optional Description Valid values Default
left
Optional Left text context One or more words separated by spaces (none)
right
Optional Right text context One or more words separated by spaces (none)
prefix
Optional Prefix of current word Sequence of one or more characters (none)
num
Optional Number of results Positive integer 5
vocab
Optional Filter to words in this vocabulary 1k, 5k, 10k, 20k, 40k, 100k, 500k 100k
sort
Optional Sorting of result words alpha = alphabetically A-Z
rev-alpha = reverse alphabetically Z-A
logprob = log probability of next character, largest first
rev-logprob = log probability of next character, smallest first
logprob-next = word set max log probability, largest first
rev-logprob-next = word set max log probability, smallest first
logprob
safe
Optional Safe mode, filters obscene words. true or false false
lang
Optional Language code Language to use (see list) en

Example:


character/predict

Get the probability of all next characters given the left text context.

Parameter Required/optional Description Valid values Default
left
Optional Left text context A sequence of characters (none)
sort
Optional Sorting of result words alpha = alphabetically A-Z
rev-alpha = reverse alphabetically Z-A
logprob = log probability of next character, largest first
rev-logprob = log probability of next character, smallest first
logprob-next = character set max log probability, largest first
rev-logprob-next = character set log probability, smallest first
alpha
lang
Optional Language code Language to use (see list) en

Example:


character/predict/future

Get the probability of all next characters given all possible next characters and the current left text context. This is useful for interfaces that want to cache future predictions in order to hide API latency.

Parameter Required/optional Description Valid values Default
left
Optional Left text context A sequence of characters (none)
sort
Optional Sorting of result words alpha = alphabetically A-Z
rev-alpha = reverse alphabetically Z-A
logprob = log probability, largest first
rev-logprob = log probability, smallest first
alpha
lang
Optional Language code Language to use (see list) en

Example:


character/predict/next/future

Get the probability of all next characters given all word predictions based on a given left context, prefix, and right context. This is useful for interfaces that want to cache future predictions in order to hide API latency.

Parameter Required/optional Description Valid values Default
left
Optional Left text context One or more words separated by spaces (none)
right
Optional Right text context One or more words separated by spaces (none)
prefix
Optional Prefix of current word Sequence of one or more characters (none)
num
Optional Number of results Positive integer 5
vocab
Optional Filter to words in this vocabulary 1k, 5k, 10k, 20k, 40k, 100k, 500k 100k
sort
Optional Sorting of result words alpha = alphabetically A-Z
rev-alpha = reverse alphabetically Z-A
logprob = log probability of next character, largest first
rev-logprob = log probability of next character, smallest first
logprob-next = word set max log probability, largest first
rev-logprob-next = word set max log probability, smallest first
logprob
safe
Optional Safe mode, filters obscene words. true or false false
lang
Optional Language code Language to use (see list) en

Example:


sentence/likely

Returns the most likely words from a sentence. This is based on a left-to-right scoring of each word under the language model.

Parameter Required/optional Description Valid values Default
text
Required Sentence text Sequence of words separated by spaces (none)
num
Optional Number of results Positive integer 5
vocab
Optional Filter to words in this vocabulary 1k, 5k, 10k, 20k, 40k, 100k, 500k 100k
sort
Optional Sorting of result words alpha = alphabetically A-Z
rev-alpha = reverse alphabetically Z-A
logprob = log probability, largest first
rev-logprob = log probability, smallest first
logprob
safe
Optional Safe mode, filters obscene words. true or false false
lang
Optional Language code Language to use (see list) en

Example:


sentence/unlikely

Returns the least likely words from a sentence. This is based on a left-to-right scoring of each word under the language model.

Parameter Required/optional Description Valid values Default
text
Required Sentence text Sequence of words separated by spaces (none)
num
Optional Number of results Positive integer 5
vocab
Optional Filter to words in this vocabulary 1k, 5k, 10k, 20k, 40k, 100k, 500k 100k
sort
Optional Sorting of result words alpha = alphabetically A-Z
rev-alpha = reverse alphabetically Z-A
logprob = log probability, largest first
rev-logprob = log probability, smallest first
logprob
safe
Optional Safe mode, filters obscene words. true or false false
lang
Optional Language code Language to use (see list) en

Example:


sentence/oov

Returns the words that are out-of-vocabulary in a sentence with respect to a given vocabulary.

Parameter Required/optional Description Valid values Default
text
Required Sentence text Sequence of words separated by spaces (none)
num
Optional Number of results Positive integer 5
vocab
Optional Vocabulary used to determine out-of-vocabulary words 1k, 5k, 10k, 20k, 40k, 100k, 500k 100k
sort
Optional Sorting of result words alpha = alphabetically A-Z
rev-alpha = reverse alphabetically Z-A
(none)
safe
Optional Safe mode, filters obscene words. true or false false
lang
Optional Language code Language to use (see list) en

Example:


sentence/word/perplexity

Returns the average per-word perplexity of a sentence under the word language model.

Parameter Required/optional Description Valid values Default
text
Required Sentence text Sequence of words separated by spaces (none)
lang
Optional Language code Language to use (see list) en

Example:


character/perplexity

Returns the average per-character perplexity of a sentence under the character language model.

Parameter Required/optional Description Valid values Default
text
Required Sentence text Sequence of characters (none)
lang
Optional Language code Language to use (see list) en

Example:


keyboard/create

Create a new keyboard with a specified set of keys. Each key is defined by a center x- and y-coordinate, a width, a height, and at least one character├č label. Call should be via a POST containing a JSON collection with the name/value pair keys and the optional parameter lang. lang specifies the Language to use (see list) for the language of the keyboard (default is en). The keys value is a list that defines the following about each key:

Parameter Required/optional Description Valid values Default
labels Required Character label(s) for this key Array of strings (none)
x Required Center x-coordinate of the key double (none)
y Required Center y-coordinate of the key double (none)
width Required Width of the key Positive double (none)
height Required Height of the key Positive double (none)

Notes:
Returns JSON containing the following:

Name Description Type
id Unique ID for the keyboard, needed for future API calls string
numKeys Number of keys on the keyboard integer
x Center x-coordinate of the bounding box of the keyboard double
y Center y-coordinate of the bounding box of the keyboard double
width Width of the bounding box of the keyboard double
height Height of the bounding box of the keyboard double


Example POST request:
BASE_URL/keyboard/create

{"keys": [
           {"labels": ["a"], "x": 1.23, "y": 4.56, "height": 7.89, "width": 10.11},
           {"labels": ["b"], "x": 3.33, "y": 4.44, "height": 5.55, "width": 6.66},
           {"labels": [" "], "x": 6.66, "y": 7.77, "height": 8.88, "width": 9.99}
         ]}

Example response:
{"id"      : "MY_KEYBOARD_ID",
 "numKeys" : 3,
 "x"       : 3.915000,
 "y"       : 6.412500,
 "width"   : 15.480000,
 "height"  : 11.595000}


keyboard/get

Get details about an existing keyboard.

Parameter Required/optional Description Valid values Default
id Required Unique ID for the existing keyboard String returned by keyboard/create (none)
lang
Optional Language code Language to use (see list) en

Returns JSON with the same fields as keyboard/create.

Example GET request:
BASE_URL/keyboard/get?id=MY_KEYBOARD_ID
Example response:
{"id"      : "MY_KEYBOARD_ID",
 "numKeys" : 3,
 "x"       : 3.915000,
 "y"       : 6.412500,
 "width"   : 15.480000,
 "height"  : 11.595000}


keyboard/transform

Move or scale an existing keyboard.

Parameter Required/optional Description Valid values Default
id Required Unique ID for the existing keyboard String returned by keyboard/create (none)
x Optional New x-coordinate for center of keyboard bounding box Floating-point value (none)
y Optional New y-coordinate for center of keyboard bounding box Floating-point value (none)
width Optional New width for keyboard bounding box Floating-point value (none)
height Optional New height for keyboard bounding box Floating-point value (none)
lang
Optional Language code Language to use (see list) en

Returns JSON with the same fields as keyboard/create.

Example GET request:
BASE_URL/keyboard/transform?id=MY_KEYBOARD_ID&x=100&width=31
Example response:
{"id"      : "MY_KEYBOARD_ID",
 "numKeys" : 3,
 "x"       : 100.000000,
 "y"       : 6.412500,
 "width"   : 31.000000,
 "height"  : 11.595000}


rec/taps

Returns the most likely text given a sequence of taps on the specified onscreen keyboard. Caller should first create the keyboard using keyboard/create. Optionally can return word completion predictions based on the observation sequence being the prefix of a word. Call should be via a POST containing JSON with the following key/value pairs: Returns JSON containing the following:

Parameter Required/optional Description Valid values Default
keyboardId
Required Keyboard ID to use for recognition String returned by keyboard/create (none)
left
Optional Left text context One or more words separated by spaces (none)
right
Optional Right text context One or more words separated by spaces (none)
numBest
Optional Number of best recognition results Positive integer 5
numPrefix
Optional Number of prefix word completion results Non-negative integer 0
vocab
Optional Filter to text only containing words in the specified vocabulary 1k, 5k, 10k, 20k, 40k, 100k, 500k 100k
sort
Optional Sorting of result words alpha = alphabetically A-Z
rev-alpha = reverse alphabetically Z-A
logprob = log probability, largest first
rev-logprob = log probability, smallest first
logprob
safe
Optional Safe mode, remove hypotheses that contain any obscene words true or false false
singleWord
Optional Restricts recognition hypotheses to single words true or false true
taps
Required List of tap observations to recognize against See details below (none)
lang
Optional Language code Language to use (see list) en
config
Optional Configuration code Recognition configuration to use (see list) en

The taps parameter is a list of the sequence of taps made by the user. Each tap contains the following:

Parameter Required/optional Description Valid values Default
touches
Required Location/time of this tap A list with 0 or more items containing: x location, y location, time in seconds (optional). (none)
certain
Optional Fix tap to nearest key true or false false

Notes:
Example POST request:
BASE_URL/rec/taps
{
    "keyboardId" : "MY_KEYBOARD_ID",
    "left"       : "this is a",
    "right"      : "message",
    "numBest"    : 2,
    "numPrefix"  : 3,
    "vocab"      : "100k",
    "sort"       : "logprob",
    "safe"       : false,
    "singleWord" : true,
    "taps"       : [ { "touches" : [ {"x": 1.2, "y": 3.4, "time": 0.012},
                                     {"x": 1.3, "y": 3.5, "time": 0.022} ],
                       "certain" : false
                     },
                     { "touches" : [ {"x": 4.4, "y": 5.5, "time": 0.031},
                                     {"x": 4.5, "y": 5.4, "time": 0.048},
                                     {"x": 4.7, "y": 5.1, "time": 0.078} ],
                      "certain" : false
                     }
                   ]
}

Example response:
{
    "best"     : [ { "text"    : "te",
                     "logProb" : -2.749233 },
                   { "text"    : "tr",
                     "logProb" : -3.548494 } ],
    "prefix"   : [ { "text"    : "test",
                     "logProb" : -5.54844 },
                   { "text"    : "trait",
                     "logProb" : -8.484444 },
                   { "text"    : "trace",
                     "logProb" : -11.45330 } ]
}


Language codes

The language code specifies the language (e.g. English) used by the endpoints. Languages are specified by their two letter ISO 639-1 code. In the future, there may also be different models for different text genres in a language. This code controls the language model(s) loaded by the underlying recognition engine.

Code Language Genre
en English Optimized for conversations and short emails, see details.


Configuration codes

The configuration code requests a specific recognition configuration for use with noisy input sequences (e.g. when using rec/taps). The default configuration should work well for most situations (e.g. word-at-a-time input). This code controls the values of configurable parameters used in the underlying recognition engine. Here are the other available configurations and the language(s) they are available in:

Code Available languages Description
sent-abbrev en Optimized for sentence-at-a-time input where users may omit mid-word vowels. Rescores n-best list with an RNNLM.