Skip to content

Predictions

Prediction Suggestion

The suggestion features provides entity 'suggestions' based on a few characters of input. It's possible that desired entity result may be found after just a few characters of text input which reduces the amount of text entry for the user. This feature is designed to be very fast and to be executed in rapid succession as user is entering text into a query box. Suggested results can be returned with a minimum of 2 characters of input. Results become more targeted as additional characters are entered.

Here are some examples in the the table below:

Query ‘pr’ (2 char input) ‘pre’ (3 char input) ‘pres’ (4 char input)
Result 1 Provo, UT Preztel Presidio Golf Course, 300 Finley Rd, San Francisco CA
Result 2 Providence, RI Presidio Golf Course, 300 Finley Rd, San Francisco CA Presideio Officer’s Club, Moraga Ave, San Francisco CA
Result 3 Pr Vantage, 90 Montgomery St, San Francisco CA Presidio Officer’s Club, Moraga Ave, San Francisco CA Presidio Height Playground, Clay St, San Francisco CA
Result 4 Pratt Pl, San Francisco CA Presidio Height Playground, Clay St, San Francisco CA Presidio Library Mini Park, Clay St, San Francisco CA
Result 5 Prosper St, San Francisco CA Precita Park, 300 Precita Ave, San Francisco CA Presidio Ave, San Francisco CA

This feature is similar to query search in that the only requirements are query text and location.

Notes:
1. Auto suggest can return slightly different results than search for the same query.
2. Search can consider more variables than suggest which can cause variants in results.

Since auto suggest is very fast, it is recommended that suggest feature is used for character by character entry and search is used on specific signal (user specifically presses a search button).

Request URI

Request URI Supported Methods
/v5/prediction/suggestion/json GET, POST

GET

Request Parameters

Name Description Required
include_entity If set true, the result will return the entity's details. Default value: false. No
limit Number of results in response. Default value: 10 No
locale The preferred language for the response content. No
location Geo-coordinate of the user location (latitude and longitude separated by ","). Yes
query Support free text query. No
user_id The id associated with the user who is sending the request. No 
1
${host}/entity/v5/prediction/suggestion/json?locale=en-US&query=star&location=37.78509,-122.41988&limit=2

POST

Request Body

Name Data Type Required/Optional Description
requestParam EntityPredictionSuggestionRequest required Request object to customize the request 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "category": "241",
  "location": {
    "latitude": 37.78509,
    "longitude": -122.41988
  },
  "query": "star",
  "suggestion_options": {
    "include_entity": true
  },
  "limit": 5
}

Response Body

Top-level JSON object:

Name Data Type Required/Optional Description
status Status required Status
response_time Number required Response time in milliseconds.
reference_id String required Reference id associated with response.
results [ Suggestion ] required List of results that match search criteria. 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
{
  "status":{
    "status":12200,
    "message":"SUCCESS"
  },
  "reference_id":"7dc33a65-f017-4b3c-ab3a-35fb9836e457",
  "results":[
    {
      "type":"QUERY",
      "formatted_label":"Starbucks",
      "query":"BRAND=Starbucks;sid=d0bdb8f4-3a08-48b2-a2d7-184ddca3d50b;position=0;originalQuery=star;source=autosuggest;"
    },
    {
      "id":"P-YP-V80WBfUpDVmi-K_0DA6yIQ",
      "type":"ENTITY",
      "formatted_label":"Star, San Francisco CA 94102, USA",
      "query":"ENTITY_ID=P-YP-V80WBfUpDVmi-K_0DA6yIQ;sid=d0bdb8f4-3a08-48b2-a2d7-184ddca3d50b;position=1;originalQuery=star;source=autosuggest;",
      "entity":{
        "id":"P-YP-V80WBfUpDVmi-K_0DA6yIQ",
        "type":"PLACE",
        "place":{
          "name":"Star",
          "alias_names":[
            {
              "name":"Star",
              "language":"ENG"
            }
          ],
          "phone_numbers":[
            "14155381013"
          ],
          "address":{
            "formatted_address":"San Francisco CA 94102, USA",
            "street":{

            },
            "city":"San Francisco",
            "state":"CA",
            "country":"USA",
            "postal_code":"94102",
            "geo_coordinates":{
              "latitude":37.77991,
              "longitude":-122.42112
            },
            "nav_coordinates":{
              "latitude":37.77991,
              "longitude":-122.42112
            }
          }
        },
        "distance":585
      }
    }
  ],
  "response_time":235
}

Status Code

Code Message Description
12200 SUCCESS Indicates that no errors occurred.
12400 INVALID_REQUEST Indicates either that a required parameter is missing or value of a parameter cannot be parsed.
12500 INTERNAL_SERVER_ERROR Indicates technical difficulties on API.

Prediction Word

The word prediction feature provides suggested words based on few characters of input. This is an alternate method to reduce user keystrokes. This feature is designed to be very fast and to be executed in rapid succession as user is entering text into a query box. Word prediction can be called starting with 2 characters input. Results become more targeted as additional characters are entered.

Similar to suggest, the minimum information required to execute this feature is a query text of the partial word and a location.

Here are some examples in the table below:

Word prediction illustration table:

Query "ma" (2 char) "mar" (3 char) "mark" (4 char)
Result 1 Mall Marriott Marketplace
Result 2 Manicurists Mark's Mark's
Result 3 Macy's Marlene Market
Result 4 Ma Marshalls Marksville
Result 5 Management Marx Marked

Request URI

Request URI Supported Methods
/v5/prediction/word/json GET, POST

GET

Request Parameters

Name Description Required
location Geo-coordinate of the user location (latitude and longitude separated by ","). Yes
query Support free text query Yes
limit Number of results in response. Default value: 10 No
locale The preferred language for the response content. No
user_id The id associated with the user who is sending the request. No 
1
{host}/entity/v5/prediction/word/json?locale=en-US&query=st&location=37.78509%2C-122.41988&limit=2

POST

Request Body

Name Data Type Required/Optional Description
requestParam EntityPredictionWordRequest required Request object to customize the request 
1
2
3
4
5
6
7
8
9
{
  "category":"241",
  "location":{
    "latitude":37.78509,
    "longitude":-122.41988
  },
  "query":"st",
  "limit":5
}

Response Body

Top-level JSON object:

Name Data Type Required/Optional Description
status Status required Status
response_time Number required Response time in milliseconds.
reference_id String required Reference id associated with response.
results [ WordPrediction ] required List of results that match search criteria. 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
  "status":{
    "code":12200,
    "message":"SUCCESS"
  },
  "response_time":29,
  "reference_id":"94267c2c-dbb2-4a9d-b470-6d8b4a0e3c44",
  "results":[
    {
      "predict_word":"Steak",
      "type":"PREFIX",
      "active_word":"st"
    },
    {
      "predict_word":"Stage",
      "type":"PREFIX",
      "active_word":"st"
    },
    {
      "predict_word":"St",
      "type":"PREFIX",
      "active_word":"st"
    },
    {
      "predict_word":"Staples",
      "type":"PREFIX",
      "active_word":"st"
    },
    {
      "predict_word":"St.",
      "type":"PREFIX",
      "active_word":"st"
    }
  ]
}

Status Code

Code Message Description
12200 SUCCESS Indicates that no errors occurred.
12400 INVALID_REQUEST Indicates either that a required parameter is missing or value of a parameter cannot be parsed.
12500 INTERNAL_SERVER_ERROR Indicates technical difficulties on API.