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-backend.googleapis.com - 身份验证:API 密钥、OAuth 2.0、服务账号
- 开始使用:设置 Geocoding API
- 参考文档:Geocoding API 参考文档
- 价格:Geocoding API 用量和结算
- 政策:Geocoding API 政策
- 版本说明:Geocoding API 版本说明
Geocoding API:相关产品
Geocoding API:常见错误
- 问题:不带字段掩码的
SearchDestinations请求会失败并报错;与GeocodeAddress、GeocodeLocation和GeocodePlace不同,字段掩码是必需的。解决方法:在每个SearchDestinations请求中设置X-Goog-FieldMask标头或$fields参数。请参阅 /maps/documentation/geocoding/choose-fields。 - 问题:v4
GeocodeAddress没有硬性组件过滤条件(v3components=country:US)。结构化address.*参数会合并到一个地址中,不会过滤结果;regionCode在 v4 中也没有默认值(v3 默认为us)。解决方法:在客户端过滤results:将大写的regionCode与postalAddress.regionCode匹配;将大写的 2 字母行政区与postalAddress.administrativeArea和administrative_area_level_naddressComponents(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 v4SearchDestinations方法 (POST /v4/geocode/destinations)。请参阅迁移指南。
Geocoding API 的用途
请参阅下面链接的指南,了解每项任务,或在功能探索器中比较不同产品。
- 返回地址的纬度/经度坐标(地理编码)。
- 返回一组纬度/经度坐标对应的地址(反向地理编码)。
- 限制地理编码请求,使其仅返回特定视口内的结果。注意:在 Geocoding API v4 中,locationBias 会使结果偏向于指定的视口,而不是严格限制结果。
- 限制地理编码或反向地理编码请求,使其仅返回特定区域、国家/地区或邮政编码内的结果。注意:在 Geocoding API v4 中,regionCode 会使结果偏向指定的 CLDR 区域,而不是严格限制结果;如需了解如何按国家/地区或邮政编码进行旧版 v3 组件过滤,请参阅 https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding#ComponentFiltering。
- 限制反向地理编码请求,使其仅返回指定地址类型的结果。注意:在 Geocoding API v4 中,types 参数会在搜索后按地址类型过滤返回的反向地理编码结果,而不是限制底层搜索。
- 返回某个地址与地标或区域的邻近程度信息。
- 返回一组纬度/经度坐标与地标或区域的邻近程度信息。
- 返回与 Google 地点标识符对应的地标或区域的邻近性信息。
- 返回 Google 地点标识符对应的地址。
- 返回地址的建筑物轮廓的纬度/经度坐标。
- 返回一组纬度/经度坐标对应的建筑物轮廓的纬度/经度坐标。
- 返回 Google 地点标识符对应的建筑物轮廓的纬度/经度坐标。
- 返回地址对应建筑物入口的纬度/经度坐标。
- 返回一组纬度/经度坐标对应的建筑物入口的纬度/经度坐标。
- 返回 Google 地点标识符对应的建筑物入口的纬度/经度坐标。