提高地理编码准确性

欧洲经济区 (EEA) 开发者

GeocodeAddress 和 SearchDestinations 方法支持可选的 effort 参数，该参数可让您控制响应延迟时间与地址解析准确率之间的权衡。

虽然标准地理编码可以在不到一秒的时间内处理格式正确的邮政地址，但实际输入的内容通常不完整、不正式或很复杂（例如 "Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West, Mumbai" 或 "where the warriors play, sf"）。通过配置更高的 effort 级别，您可以指示 Geocoding API 应用扩展推理和消除歧义来解析困难地址。

工作量级别

为 effort 参数指定以下值之一：

工作量级别 说明 典型延迟时间 推荐的用例
EFFORT_UNSPECIFIED 默认值。行为与 LOW 努力相同。 亚秒级 默认标准地理编码。
LOW 注重提升响应速度。不会对难以识别的地址执行扩展搜索或消除歧义。 亚秒级 实时交互式查找、大批量标准地址验证。
MEDIUM 兼顾速度和准确性。大多数请求都会以标准的低延迟返回。对于不明确或复杂的地址，该服务会进行额外处理以提高准确性，这可能需要几秒钟的时间。 标准地址：不到 1 秒；模糊地址：最多几秒（≤ 4 秒） 用户可以容忍短暂暂停的交互式用户工作流（例如结账时的地址确认）。
HIGH 针对不完整、非正式或复杂的地址，最大限度地提高地址解析准确率。响应时间可能会显著延长。 对于复杂地址，最长 20 秒 后台处理、批量地理编码、物流调度或结账后异步地址优化。

请求示例

搜索目的地 (SearchDestinations)

在针对 https://geocode.googleapis.com/v4alpha/geocode/destinations 的 POST 请求的 JSON 请求正文中添加 effort 字段。effort 参数主要影响 addressQuery 解析：

curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West, Mumbai"
  },
  "effort": "HIGH"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations

对地址进行地理编码 (GeocodeAddress)

在向 /v4alpha/ 端点发出的 GET 请求中，将 effort 参数作为网址查询参数传递：

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4alpha/geocode/address/where+the+warriors+play,+sf?effort=MEDIUM"

减轻延迟时间影响

在应用中使用 MEDIUM 或 HIGH 努力程度时，发送单次请求是最简单的集成方式，但这些模式下的请求可能会导致延迟时间较长，从而延迟同步、面向用户和对延迟时间敏感的工作流。

为了缓解这种延迟时间对互动式用户体验流程（例如结账或预订）的影响，您可以使用多阶段工作流：

  1. 第 1 阶段（交互式）：发送带有 effort=LOW（或默认）的同步请求，以在不到一秒的时间内立即验证地址。
  2. 第 2 阶段（后台）：发送包含 effort=MEDIUM 或 effort=HIGH 的异步后续请求（例如，在结账后或发货前），将复杂地址解析为高精度坐标、入口和导航点，而不会阻碍用户。

用量限额

在实验性 (v4alpha) 发布阶段，effort 设置为 MEDIUM 或 HIGH 的请求受到的速率限制比标准 (LOW) 请求更严格。如果您的应用超出这些速率限制，API 会返回 RESOURCE_EXHAUSTED (HTTP 429) 错误。如果您遇到 HTTP 429 错误或需要更高的配额来满足您的应用场景，请通过反馈渠道与我们联系。

反馈

这是 Geocoding API 的一项实验性功能。欢迎您通过 geocoding-feedback-channel@google.com 提供反馈。