This endpoint provides word predictions and auto-corrections based on a user tapping on an onscreen virtual keyboard. It includes results based on a potential tap located at the center of each key on the keyboard. This is useful for interfaces that want to cache future predictions in order to hide API latency. For predictions based only on the taps the user has entered already, see tap predictions. The process is as follows:
keyboard/create.rec/taps/future.Here are some test pages for the endpoints:
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) |
| type | no | The type of keyboard class to create | [GAUSSIAN2D, STEP, STEPUNCERTAIN] | GAUSSIAN2D |
Notes:
labels is a list with just a single character.labels is a list of all characters assigned to a key. Each character is assumed to be equally likely as far as the keyboard model is concerned.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}
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_IDExample response:
{"id" : "MY_KEYBOARD_ID",
"numKeys" : 3,
"x" : 3.915000,
"y" : 6.412500,
"width" : 15.480000,
"height" : 11.595000}
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}
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:
numPrefix > 0, returns the most probable words given surrounding text.singleWord is true, input is assumed to potentially contain observations from multiple words with or without spaces between them.certain to true results in locking the corresponding character during the recognition. This can allow users to avoid auto-correct errors for difficult words.time is the time of the observation in seconds from some arbitrary starting reference point (e.g. the start of input).Example POST request:
BASE_URL/rec/taps/future
{
"keyboardId" : "MY_KEYBOARD_ID",
"left" : "this is a",
"right" : "",
"numBest" : 3,
"numPrefix" : 3,
"vocab" : "100k",
"sort" : "logprob",
"safe" : false,
"singleWord" : true,
"taps" : [
{"touches" : [{"x": 144, "y": 274}]},
{"touches" : [{"x": 80, "y": 274}]}
]
}
Example response:
{
"futures": [
{
"next": "",
"predictions": {
"best": [
{
"text": "te",
"logProb": -23.548841
},
{
"text": "the",
"logProb": -24.668632
},
{
"text": "re",
"logProb": -24.888456
}
],
"prefix": [
{
"text": "terrible",
"logProb": -19.028499
},
{
"text": "test",
"logProb": -19.373188
},
{
"text": "temporary",
"logProb": -20.076184
}
]
}
},
{
"next": "q",
"predictions": {
"best": [
{
"text": "tea",
"logProb": -33.68727
},
{
"text": "tew",
"logProb": -35.711799
},
{
"text": "stew",
"logProb": -37.53143
}
],
"prefix": [
{
"text": "request",
"logProb": -30.5528
},
{
"text": "requirement",
"logProb": -31.447723
},
{
"text": "requirements",
"logProb": -31.463005
}
]
}
},
{
"next": "w",
"predictions": {
"best": [
{
"text": "tew",
"logProb": -32.682213
},
{
"text": "tea",
"logProb": -33.876619
},
{
"text": "stew",
"logProb": -34.501844
}
],
"prefix": [
{
"text": "test",
"logProb": -31.181491
},
{
"text": "reward",
"logProb": -32.243035
},
{
"text": "team",
"logProb": -32.525489
}
]
}
},
{
"next": "e",
"predictions": {
"best": [
{
"text": "tee",
"logProb": -31.832011
},
{
"text": "red",
"logProb": -34.779111
},
{
"text": "ree",
"logProb": -35.188168
}
],
"prefix": [
{
"text": "terrible",
"logProb": -29.4154
},
{
"text": "teenager",
"logProb": -30.172349
},
{
"text": "terrific",
"logProb": -30.503668
}
]
}
},
{
"next": "r",
"predictions": {
"best": [
{
"text": "ter",
"logProb": -32.398087
},
{
"text": "test",
"logProb": -33.214566
},
{
"text": "tee",
"logProb": -34.861597
}
],
"prefix": [
{
"text": "terrible",
"logProb": -26.394238
},
{
"text": "terrific",
"logProb": -27.482922
},
{
"text": "term",
"logProb": -28.195317
}
]
}
},
{
"next": "t",
"predictions": {
"best": [
{
"text": "test",
"logProb": -30.184981
},
{
"text": "tet",
"logProb": -33.086126
},
{
"text": "get",
"logProb": -33.526604
}
],
"prefix": [
{
"text": "terrible",
"logProb": -29.4154
},
{
"text": "test",
"logProb": -30.172014
},
{
"text": "terrific",
"logProb": -30.503668
}
]
}
},
{
"next": "y",
"predictions": {
"best": [
{
"text": "try",
"logProb": -32.558047
},
{
"text": "test",
"logProb": -33.214566
},
{
"text": "tey",
"logProb": -33.501265
}
],
"prefix": [
{
"text": "try",
"logProb": -32.558047
},
{
"text": "test",
"logProb": -32.968563
},
{
"text": "true",
"logProb": -32.984181
}
]
}
},
{
"next": "u",
"predictions": {
"best": [
{
"text": "try",
"logProb": -35.587632
},
{
"text": "tey",
"logProb": -36.53085
},
{
"text": "tri",
"logProb": -36.837787
}
],
"prefix": [
{
"text": "true",
"logProb": -29.963449
},
{
"text": "truly",
"logProb": -31.203956
},
{
"text": "truth",
"logProb": -31.733953
}
]
}
},
{
"next": "i",
"predictions": {
"best": [
{
"text": "tri",
"logProb": -33.808201
},
{
"text": "two",
"logProb": -33.882693
},
{
"text": "twi",
"logProb": -35.246041
}
],
"prefix": [
{
"text": "tricky",
"logProb": -30.209956
},
{
"text": "trick",
"logProb": -30.432553
},
{
"text": "trivial",
"logProb": -31.057037
}
]
}
},
{
"next": "o",
"predictions": {
"best": [
{
"text": "two",
"logProb": -30.853107
},
{
"text": "step",
"logProb": -33.410677
},
{
"text": "teo",
"logProb": -33.445727
}
],
"prefix": [
{
"text": "two",
"logProb": -30.853107
},
{
"text": "trouble",
"logProb": -32.525376
},
{
"text": "trojan",
"logProb": -32.543931
}
]
}
},
{
"next": "p",
"predictions": {
"best": [
{
"text": "step",
"logProb": -30.381091
},
{
"text": "temp",
"logProb": -32.75644
},
{
"text": "rep",
"logProb": -32.88077
}
],
"prefix": [
{
"text": "step",
"logProb": -30.381091
},
{
"text": "temporary",
"logProb": -30.875009
},
{
"text": "report",
"logProb": -30.887258
}
]
}
},
{
"next": "a",
"predictions": {
"best": [
{
"text": "tea",
"logProb": -29.240339
},
{
"text": "rea",
"logProb": -34.537636
},
{
"text": "tes",
"logProb": -34.656668
}
],
"prefix": [
{
"text": "team",
"logProb": -27.932167
},
{
"text": "real",
"logProb": -28.35235
},
{
"text": "really",
"logProb": -28.375244
}
]
}
},
{
"next": "s",
"predictions": {
"best": [
{
"text": "tes",
"logProb": -31.627361
},
{
"text": "tea",
"logProb": -32.269925
},
{
"text": "red",
"logProb": -33.361766
}
],
"prefix": [
{
"text": "test",
"logProb": -26.771317
},
{
"text": "testing",
"logProb": -28.711607
},
{
"text": "testament",
"logProb": -29.550635
}
]
}
},
{
"next": "d",
"predictions": {
"best": [
{
"text": "red",
"logProb": -30.33218
},
{
"text": "ted",
"logProb": -31.135791
},
{
"text": "tes",
"logProb": -34.656668
}
],
"prefix": [
{
"text": "test",
"logProb": -29.792191
},
{
"text": "red",
"logProb": -30.33218
},
{
"text": "teddy",
"logProb": -30.752142
}
]
}
},
{
"next": "f",
"predictions": {
"best": [
{
"text": "ref",
"logProb": -33.264462
},
{
"text": "red",
"logProb": -33.361766
},
{
"text": "ted",
"logProb": -34.165376
}
],
"prefix": [
{
"text": "terrible",
"logProb": -30.805562
},
{
"text": "reference",
"logProb": -30.892951
},
{
"text": "technical",
"logProb": -31.43028
}
]
}
},
{
"next": "g",
"predictions": {
"best": [
{
"text": "reg",
"logProb": -33.722708
},
{
"text": "teg",
"logProb": -33.876653
},
{
"text": "test",
"logProb": -34.631911
}
],
"prefix": [
{
"text": "regular",
"logProb": -30.263232
},
{
"text": "registered",
"logProb": -32.241077
},
{
"text": "regional",
"logProb": -32.330661
}
]
}
},
{
"next": "h",
"predictions": {
"best": [
{
"text": "tech",
"logProb": -32.535427
},
{
"text": "teh",
"logProb": -33.372628
},
{
"text": "ten",
"logProb": -36.226453
}
],
"prefix": [
{
"text": "technical",
"logProb": -31.068574
},
{
"text": "technique",
"logProb": -31.519284
},
{
"text": "technology",
"logProb": -32.129402
}
]
}
},
{
"next": "j",
"predictions": {
"best": [
{
"text": "ten",
"logProb": -33.196867
},
{
"text": "tej",
"logProb": -33.962509
},
{
"text": "tech",
"logProb": -35.565013
}
],
"prefix": [
{
"text": "rejection",
"logProb": -33.097583
},
{
"text": "ten",
"logProb": -33.196867
},
{
"text": "reject",
"logProb": -33.583568
}
]
}
},
{
"next": "k",
"predictions": {
"best": [
{
"text": "tek",
"logProb": -32.627051
},
{
"text": "tel",
"logProb": -34.725241
},
{
"text": "term",
"logProb": -35.389801
}
],
"prefix": [
{
"text": "temporary",
"logProb": -31.255385
},
{
"text": "telephone",
"logProb": -32.251878
},
{
"text": "template",
"logProb": -32.48623
}
]
}
},
{
"next": "l",
"predictions": {
"best": [
{
"text": "tel",
"logProb": -31.695655
},
{
"text": "rel",
"logProb": -34.34007
},
{
"text": "step",
"logProb": -35.017371
}
],
"prefix": [
{
"text": "telephone",
"logProb": -29.222292
},
{
"text": "television",
"logProb": -29.718931
},
{
"text": "tell",
"logProb": -30.314076
}
]
}
},
{
"next": "z",
"predictions": {
"best": [
{
"text": "rez",
"logProb": -34.24867
},
{
"text": "tex",
"logProb": -34.408198
},
{
"text": "tes",
"logProb": -35.408004
}
],
"prefix": [
{
"text": "test",
"logProb": -30.53372
},
{
"text": "text",
"logProb": -30.829218
},
{
"text": "textbook",
"logProb": -32.202483
}
]
}
},
{
"next": "x",
"predictions": {
"best": [
{
"text": "tex",
"logProb": -31.378613
},
{
"text": "red",
"logProb": -34.11343
},
{
"text": "rex",
"logProb": -34.30278
}
],
"prefix": [
{
"text": "text",
"logProb": -27.808056
},
{
"text": "textbook",
"logProb": -29.181751
},
{
"text": "texas",
"logProb": -30.001772
}
]
}
},
{
"next": "c",
"predictions": {
"best": [
{
"text": "tec",
"logProb": -31.474081
},
{
"text": "rec",
"logProb": -33.449363
},
{
"text": "tex",
"logProb": -34.408198
}
],
"prefix": [
{
"text": "technical",
"logProb": -27.667877
},
{
"text": "technique",
"logProb": -28.118587
},
{
"text": "technology",
"logProb": -28.728705
}
]
}
},
{
"next": "v",
"predictions": {
"best": [
{
"text": "rev",
"logProb": -33.790292
},
{
"text": "tec",
"logProb": -34.503388
},
{
"text": "rec",
"logProb": -36.478949
}
],
"prefix": [
{
"text": "technical",
"logProb": -30.688763
},
{
"text": "technique",
"logProb": -31.139473
},
{
"text": "review",
"logProb": -31.293677
}
]
}
},
{
"next": "b",
"predictions": {
"best": [
{
"text": "ten",
"logProb": -32.445203
},
{
"text": "reb",
"logProb": -35.884281
},
{
"text": "tech",
"logProb": -36.316677
}
],
"prefix": [
{
"text": "ten",
"logProb": -32.436349
},
{
"text": "reboot",
"logProb": -32.862618
},
{
"text": "rebel",
"logProb": -32.96332
}
]
}
},
{
"next": "n",
"predictions": {
"best": [
{
"text": "ten",
"logProb": -29.415617
},
{
"text": "term",
"logProb": -34.638136
},
{
"text": "ren",
"logProb": -34.737654
}
],
"prefix": [
{
"text": "ten",
"logProb": -29.415617
},
{
"text": "tendency",
"logProb": -30.082911
},
{
"text": "tent",
"logProb": -30.145376
}
]
}
},
{
"next": "m",
"predictions": {
"best": [
{
"text": "term",
"logProb": -31.608551
},
{
"text": "ten",
"logProb": -32.445203
},
{
"text": "stem",
"logProb": -33.689592
}
],
"prefix": [
{
"text": "temporary",
"logProb": -27.474312
},
{
"text": "template",
"logProb": -28.705587
},
{
"text": "temple",
"logProb": -28.947206
}
]
}
},
{
"next": "<sp>",
"predictions": {
"best": [
{
"text": "rev",
"logProb": -37.571542
},
{
"text": "tec",
"logProb": -38.272164
},
{
"text": "te",
"logProb": -38.69951
}
],
"prefix": [
{
"text": "technical",
"logProb": -34.140555
},
{
"text": "terrible",
"logProb": -34.146765
},
{
"text": "test",
"logProb": -34.491454
}
]
}
}
]
}