预测

prediction 包提供了一系列类，用于在用户仅输入少量字符时，提前预测其输入意图。这些类专为高性能场景设计，可在用户每输入一个字符后立即调用。其主要包含两类能力：suggestion（基于少量字符给出 entity 候选结果）与 word prediction（基于少量字符预测目标单词）。

主要的 Prediction 相关类请参见 API reference。

Get Suggestion Prediction

suggestion 能力会基于少量输入字符返回 entity 候选结果。很多时候用户只输入几个字符就能找到目标 entity，从而显著减少输入量。该能力针对极高性能优化，可在用户连续输入文本时高频调用。最少输入 2 个字符即可返回候选结果，且随着字符增多，结果会越来越精准（见下表）：

查询	'pr'（2 字符输入）	'pre'（3 字符输入）	'pres'（4 字符输入）
结果 1	Provo, UT	Preztel	Presidio Golf Course, 300 Finley Rd, San Francisco CA
结果 2	Providence, RI	Presidio Golf Course, 300 Finley Rd, San Francisco CA	Presideio Officer's Club, Moraga Ave, San Francisco CA
结果 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
结果 4	Pratt Pl, San Francisco CA	Presidio Height Playground, Clay St, San Francisco CA	Presidio Library Mini Park, Clay St, San Francisco CA
结果 5	Prosper St, San Francisco CA	Precita Park, 300 Precita Ave, San Francisco CA	Presidio Ave, San Francisco CA

suggestion 与常规 search 类似，仅需提供查询文本和位置即可。但需要注意：对于同一个查询文本，auto suggest 与 search 返回的结果可能略有差异——search 会综合考虑更多因素，因此结果会有所不同。由于 auto suggest 性能极高，建议在用户逐字符输入时使用 suggest，而在用户主动触发搜索动作（例如点击搜索按钮）时使用 search。

关键方法

方法	说明
setLocation(double latitude, double longitude)	用户当前位置坐标，作为 suggest 结果的锚点位置。必填
setQuery(String query)	部分查询文本（即用户已输入的前几个字符），支持自由文本查询。最少 2 个字符即可返回结果。选填
setLimit(Integer limit)	返回结果数量，默认值 10。选填
setLocale(Locale locale)	响应内容的语言偏好，例如 `Locale.US`。选填

示例代码

Java

entityClient.suggestionPredictionRequest()
    .setLocation(37.12419, -121.98828)
    .setQuery("Pierce Rd")
    .asyncCall(new Callback<EntitySuggestionPredictionResponse>() {

        @Override
        public void onSuccess(EntitySuggestionPredictionResponse response) {
            // 以 JSON 格式打印响应
            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);
        }
    });

Kotlin

entityClient.suggestionPredictionRequest()
    .setLocation(37.12419, -121.98828)
    .setQuery("Pierce Rd")
    .asyncCall(object : Callback<EntitySuggestionPredictionResponse> {

        override fun onSuccess(response: EntitySuggestionPredictionResponse) {
            // 以 JSON 格式打印响应
            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)
        }
    })

响应示例

JSON

{
  "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

word prediction 能力会基于少量输入字符给出建议单词，是另一种减少用户击键次数的方式。它同样为高性能场景设计，可在用户连续输入时高频调用。最少输入 2 个字符即可返回结果，且随着字符增多，结果会越来越精准（见下表）。

与 suggest 类似，调用该能力的最低要求是：一段部分单词的查询文本，以及一个位置。
word prediction 示例表：

查询	"ma"（2 字符）	"mar"（3 字符）	"mark"（4 字符）
结果 1	Mall	Marriott	Marketplace
结果 2	Manicurists	Mark's	Mark's
结果 3	Macy's	Marlene	Market
结果 4	Ma	Marshalls	Marksville
结果 5	Management	Marx	Marked

关键方法

方法	说明
setLocation(double latitude, double longitude)	用户当前位置坐标，作为 word prediction 结果的锚点位置。必填
setQuery(String query)	部分单词文本（用户已输入的前几个字符），支持自由文本查询。最少 2 个字符即可返回结果。必填
setLimit(Integer limit)	返回结果数量，默认值 10。选填
setLocale(Locale locale)	响应内容的语言偏好，例如 `Locale.US`。选填

示例代码

Java

entityClient.wordPredictionRequest()
    .setLocation(37.12419, -121.98828)
    .setQuery("Mcd")
    .asyncCall(new Callback<EntityWordPredictionResponse>() {

        @Override
        public void onSuccess(EntityWordPredictionResponse response) {
            // 以 JSON 格式打印响应
            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);
        }
    });

Kotlin

entityClient.wordPredictionRequest()
    .setLocation(37.12419, -121.98828)
    .setQuery("Mcd")
    .asyncCall(object : Callback<EntityWordPredictionResponse> {

        override fun onSuccess(response: EntityWordPredictionResponse) {
            // 以 JSON 格式打印响应
            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)
        }
    })

响应示例

JSON

{
  "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
}

响应参数

Suggestion 响应

EntitySuggestionPredictionResponse 包含以下字段：

方法 / 字段	说明
getStatus() / getCode()	请求状态
getResponseTime()	响应时间（毫秒）
getReferenceId()	响应关联的 reference id
getResults()	匹配查询条件的 suggestion 结果列表

每个 Suggestion 对象包含：

字段	说明
getType()	建议类型，如 `QUERY`（查询建议）或 `ENTITY`（entity 建议）
getFormattedLabel()	格式化显示标签
getQuery()	可用于后续搜索的结构化查询字符串
getEntity()	当 type 为 `ENTITY` 时，返回关联的 entity 详情

Word Prediction 响应

EntityWordPredictionResponse 包含以下字段：

方法 / 字段	说明
getStatus() / getCode()	请求状态
getResponseTime()	响应时间（毫秒）
getReferenceId()	响应关联的 reference id
getResults()	匹配查询条件的 word prediction 结果列表

每个 WordPrediction 对象包含：

字段	说明
getPredictWord()	预测的完整单词
getType()	预测类型，如 `PREFIX`（前缀匹配）
getActiveWord()	用户当前输入的部分单词

状态码

状态码	消息	说明
12200	SUCCESS	请求成功，未发生错误
12400	INVALID_REQUEST	缺少必填参数，或参数值无法解析
12500	INTERNAL_SERVER_ERROR	API 服务端内部错误