Text prediction REST API, v2.3


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)

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

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

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

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

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

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

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

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

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

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)

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)

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. 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)

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)

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)

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 } ]
}