Geocoding API 快速参考

Geocoding API 是一项网络服务,可将地址转换为坐标和地点 ID,以及将坐标或地点 ID 转换为地址。其 v4 SearchDestinations 方法还会返回目的地详情,例如建筑物入口、导航点、建筑物和场地轮廓以及附近的地标。

Geocoding API:关键信息

  • 产品:Geocoding API
  • 类别:地点
  • 平台:Web 服务 (REST)
  • 运行位置:服务器(后端代码)
  • 发布阶段:GA
  • 生命周期:有效
  • 概览:Geocoding API 概览

Geocoding API:适用情形

在以下情况下使用 Geocoding API:

  • 您需要在后端服务器上将街道地址转换为纬度/经度坐标和地点 ID。
  • 您需要提供 GPS 坐标或已知地点 ID 的显示地址或行政区(城市、邮政编码)。
  • 您需要建筑物入口、可规划路线的导航点或建筑物/场地轮廓,以便为司机或配送员规划前往目的地的路线。
  • 您需要将大型建筑群(机场、购物中心、校园)内的目的地解析为子目的地或附近地标。

在以下情况下,请勿使用 Geocoding API:

  • 您需要通过客户端浏览器 JavaScript 进行地理编码;使用公开的 API 密钥调用 v4 会带来安全风险。请改用 Maps JavaScript API。
  • 您需要计算前往经过地理编码的目的地的路线或预计到达时间。请改用 Routes API。
  • 您需要在 Android 应用中获取前往导航点令牌的精细导航。请改用 Navigation SDK for Android。
  • 您需要在 iOS 应用中获取前往导航点令牌的精细导航。请改用 Navigation SDK for iOS。

Geocoding API:设置

Geocoding API:常见错误

  • 问题:不带字段掩码的 SearchDestinations 请求会失败并报错;与 GeocodeAddress、GeocodeLocation 和 GeocodePlace 不同,字段掩码是必需的。解决方法:在每个 SearchDestinations 请求中设置 X-Goog-FieldMask 标头或 $fields 参数。请参阅 /maps/documentation/geocoding/choose-fields。
  • 问题:v4 GeocodeAddress 没有硬性组件过滤条件(v3 components=country:US)。结构化 address.* 参数会合并到一个地址中,不会过滤结果;regionCode 在 v4 中也没有默认值(v3 默认为 us)。解决方法:在客户端过滤 results:将大写的 regionCode 与 postalAddress.regionCode 匹配;将大写的 2 字母行政区与 postalAddress.administrativeArea 和 administrative_area_level_n addressComponents (shortText) 匹配;对输入和 postalAddress.postalCode 进行标准化(去除空格/连字符并应用区域规则)。请参阅 /maps/documentation/geocoding/geocoding-v4-migrate。
  • 问题:直接从浏览器 JavaScript 调用 Geocoding API v4 会暴露 API 密钥;伪造 Referer 标头可以绕过 HTTP 引荐来源网址限制。解决方法:使用受保护的密钥从您自己的后端调用 v4,或使用 Maps JavaScript API 地理编码服务(v3 后端)满足客户端需求。请参阅 /maps/documentation/geocoding/geocoding-v4-migrate。
  • 问题:与 v3 和其他 v4 方法不同,SearchDestinations 可能会返回没有精确主要地址的结果。解决方法:如果您只需要具有精确主要地址的结果,请将 placeFilter.addressability 设置为 PRIMARY。请参阅 /maps/documentation/geocoding/geocoding-v4-migrate。
  • 问题:为 Geocoding API v3 编写的代码在 v4 REST 响应中会出错:v4 使用小驼峰式命名的字段名称(addressComponents,而非 address_components),移除了 status 和 error_message,并从 GeocodePlace 返回单个根对象,而不是 results 数组。修复方法:检查 v4 REST 调用的 HTTP 状态代码和错误正文,读取 lowerCamelCase 字段(addressComponents、postalAddress),并注意 gRPC 响应仍使用蛇形命名法。请参阅 /maps/documentation/geocoding/geocoding-v4-migrate。

Geocoding API:旧版和已弃用的功能

  • Geocoding API v3 超本地化数据(extra_computations:BUILDING_AND_ENTRANCES、NAVIGATION_POINTS、GROUNDS;响应字段 buildings.entrances、navigation_points、buildings.building_outlines、grounds):自 2025 年 8 月 13 日起弃用。替代方案:Geocoding API v4 SearchDestinations 方法 (POST /v4/geocode/destinations)。请参阅迁移指南。

Geocoding API 的用途

请参阅下面链接的指南,了解每项任务,或在功能探索器中比较不同产品。