>

These endpoints provide word predictions and auto-corrections based on a user tapping on an onscreen virtual keyboard. The process is as follows:

  1. Create a keyboard using keyboard/create.
  2. Decode a sequence of taps using rec/taps.

Here are some test pages for the endpoints:


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 Description Valid values Default
labels yes Character label(s) for this key Array of strings (none)
x yes Center x-coordinate of the key double (none)
y yes Center y-coordinate of the key double (none)
width yes Width of the key Positive double (none)
height yes 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 Description Valid values Default
id yes Unique ID for the existing keyboard String returned by keyboard/create (none)
lang no 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 Description Valid values Default
id yes Unique ID for the existing keyboard String returned by keyboard/create (none)
x no New x-coordinate for center of keyboard bounding box Floating-point value (none)
y no New y-coordinate for center of keyboard bounding box Floating-point value (none)
width no New width for keyboard bounding box Floating-point value (none)
height no New height for keyboard bounding box Floating-point value (none)
lang no 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:

Parameter Required Description Valid values Default
keyboardId yes Keyboard ID to use for recognition String returned by keyboard/create (none)
left no Left text context One or more words separated by spaces (none)
right no Right text context One or more words separated by spaces (none)
numBest no Number of best recognition results Positive integer 5
numPrefix no Number of prefix word completion results Non-negative integer 0
vocab no Filter to text only containing words in the specified vocabulary 1k, 5k, 10k, 20k, 40k, 100k, 500k (don't filter)
sort no 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 no Safe mode, remove hypotheses that contain any obscene words true or false false
singleWord no Restricts recognition hypotheses to single words true or false true
exactContext no Client is providing exact left and right context including any spaces or sentence start/end words (for experts) true or false false
lang no Language code Language to use (see list) en
config no Configuration code Recognition configuration to use (see list) en
taps yes 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:

Key Required Description Valid values Default
touches yes Location/time of this tap A list with 0 or more items containing: x location, y location, time in seconds (optional). (none)
certain no 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 } ]
}