Skip to content

Predictions

The prediction packages contains the classes used to build features to anticipate (or predict) user data entry action based on just a few characters of information. These classes are designed with fast performance and are designed to be executed or called after every character of input. The primary features implemented include suggestion which proposes entity results based on just a few characters of input while the word prediction features proposes intended word based on few characters of input.

Please see the API reference for the main classes related to Prediction.

Get Suggestion Prediction

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 is designed 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. As below table indicates, results become more targeted as additional characters are entered.

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 only requirements are query text and location. However, note that auto suggest can return slightly different results than search for the same query. Note that 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 that search is used on specific signal (user specifically presses a search button).

Key methods

Method Details
setLocation(double latitude, double longitude) The anchor location from where suggest results will be based
setQuery(String query) The suggestion text in the form of a partial query

Sample code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
entityClient.suggestionPredictionRequest()
    .setLocation(37.12419, -121.98828)
    .setQuery("Pierce Rd")
    .asyncCall(new Callback<EntitySuggestionPredictionResponse>() {

        @Override
        public void onSuccess(EntitySuggestionPredictionResponse response) {
            // log response in JSON format
            LOG.info(EntityJsonConverter.toPrettyJson(response));

            List<Suggestion> suggestions = response.getResults();
            for (Suggestion suggestion : suggestions) {
                LOG.info("Suggestion:" + suggestion.getFormattedLabel());
            }
        }

        @Override
        public void onFailure(Throwable t) {
            LOG.error("Get unsuccessful response or throwable happened when executing the request.", t);
        }
    });
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
entityClient.suggestionPredictionRequest()
    .setLocation(37.12419, -121.98828)
    .setQuery("Pierce Rd")
    .asyncCall(object : Callback<EntitySuggestionPredictionResponse> {

        override fun onSuccess(response: EntitySuggestionPredictionResponse) {
            // log response in JSON format
            Log.i("sdk", EntityJsonConverter.toPrettyJson(response))

            for (suggestion in response.results) {
                Log.i("sdk", "Suggestion: ${suggestion.getFormattedLabel()}")
            }
        }

        override fun onFailure(t: Throwable) {
            Log.e("sdk", "Get unsuccessful response or throwable happened when executing the request.", t)
        }
    })

Response example

 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
{
  "code": "SUCCESS",
  "message": "SUCCESS",
  "reference_id": "f3914582-3638-459d-b1cf-bc1c48bc0115",
  "results": [
    {
      "id": "Yz1sb3MgZ2F0b3M7Y289dXM7c2ZuPXBpZXJjZSByZDt6PTk1MDMzO3M9Y2E7aWQ9MTA2NDk0OTg2O2x0PTM3LjEyNTg3O2xuPS0xMjEuOTkwMztyZ2M9ZmFsc2U7dHQ9c3RyZWV0OwV6",
      "type": "ENTITY",
      "formatted_label": "Pierce Rd, Los Gatos CA 95033, USA",
      "query": "ENTITY_ID=Yz1sb3MgZ2F0b3M7Y289dXM7c2ZuPXBpZXJjZSByZDt6PTk1MDMzO3M9Y2E7aWQ9MTA2NDk0OTg2O2x0PTM3LjEyNTg3O2xuPS0xMjEuOTkwMztyZ2M9ZmFsc2U7dHQ9c3RyZWV0OwV6;sid=5f2349af-48fd-4571-aa3d-9ee636ff0b05;position=0;originalQuery=Pierce Rd;source=autosuggest;",
      "entity": {
        "id": "Yz1sb3MgZ2F0b3M7Y289dXM7c2ZuPXBpZXJjZSByZDt6PTk1MDMzO3M9Y2E7aWQ9MTA2NDk0OTg2O2x0PTM3LjEyNTg3O2xuPS0xMjEuOTkwMztyZ2M9ZmFsc2U7dHQ9c3RyZWV0OwV6",
        "type": "ADDRESS",
        "address": {
          "address_type": "STREET",
          "formatted_address": "Pierce Rd, Los Gatos CA 95033",
          "street": {
            "body": "pierce rd",
            "type": "",
            "formatted_name": "Pierce Rd"
          },
          "city": "Los Gatos",
          "state": "CA",
          "country": "USA",
          "postal_code": "95033",
          "geo_coordinates": {
            "latitude": 37.12587,
            "longitude": -121.9903
          },
          "nav_coordinates": {
            "latitude": 37.12587,
            "longitude": -121.9903
          },
          "address_lines": [
            "Pierce Rd, Los Gatos CA 95033"
          ]
        },
        "distance": 258.0
      }
    },
    ...
  ],
  "response_time": 23
}

Get Word Prediction

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 is designed to be executed in rapid succession as user is entering text into a query box. Word can be prediction can be called starting with 1 characters of input. As below table indicates, 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.
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

Key methods

Method Details
setLocation(double latitude, double longitude) The anchor location from where suggest results will be based
setQuery(String query) The partial word text

Sample code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
entityClient.wordPredictionRequest()
    .setLocation(37.12419, -121.98828)
    .setQuery("Mcd")
    .asyncCall(new Callback<EntityWordPredictionResponse>() {

        @Override
        public void onSuccess(EntityWordPredictionResponse response) {
            // log response in JSON format
            LOG.info(EntityJsonConverter.toPrettyJson(response));

            List<WordPrediction> predictions = response.getResults();
            for (WordPrediction prediction : predictions) {
                LOG.info("Found predicted word: " + prediction.getPredictWord());
            }
        }

        @Override
        public void onFailure(Throwable t) {
            LOG.error("Get unsuccessful response or throwable happened when executing the request.", t);
        }
    });
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
entityClient.wordPredictionRequest()
    .setLocation(37.12419, -121.98828)
    .setQuery("Mcd")
    .asyncCall(object : Callback<EntityWordPredictionResponse> {

        override fun onSuccess(response: EntityWordPredictionResponse) {
            // log response in JSON format
            Log.i("sdk", EntityJsonConverter.toPrettyJson(response))

            val predictions = response.results
            for (prediction in predictions) {
                Log.i("sdk", "Found predicted word: ${prediction.predictWord}")
            }
        }

        override fun onFailure(t: Throwable) {
            Log.e("sdk", "Get unsuccessful response or throwable happened when executing the request.", t)
        }
    })

Response example

 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
{
  "code": "SUCCESS",
  "message": "SUCCESS",
  "reference_id": "0d46161d-9ac7-4135-8fec-5d460deb2430",
  "results": [
    {
      "predict_word": "Mcdonald's",
      "type": "PREFIX",
      "active_word": "Mcd"
    },
    {
      "predict_word": "McDonough",
      "type": "PREFIX",
      "active_word": "Mcd"
    },
    {
      "predict_word": "McDougall",
      "type": "PREFIX",
      "active_word": "Mcd"
    },
    {
      "predict_word": "McDowell",
      "type": "PREFIX",
      "active_word": "Mcd"
    }
  ],
  "response_time": 53
}