一切就绪!

着手开发前,请先阅读我们的开发者文档

激活 Google Maps Geocoding API

为帮助您起步,我们将引导您在 Google Developers Console 中先完成几项任务:

  1. 创建或选择项目
  2. 激活 Google Maps Geocoding API
  3. 创建相应密钥
继续

对地址进行地理编码时的最佳做法

地理编码是将地址(如街道地址)转换为地理坐标(纬度和经度)的过程,可以利用地理编码在地图上放置标记,或在地图上定位。本文的重点是澄清在对地址进行地理编码时涉及的一些注意事项。它介绍了使用 Google Maps Geocoding API 的最佳时机,以及使用 Places API Place Autocomplete 服务或 Places API Text Search 服务的有利时机。

一般而言,Google Maps Geocoding API 适合在对完整地址(例如“48 Pirrama Rd, Pyrmont, NSW, Australia”)进行地理编码时使用。Places API Place Autocomplete 服务适合在对模糊(不完整)地址进行地理编码时或者延迟时间较高的情境(比如响应用户输入时)下使用。如果是在无需用户根据自动填充建议选择输入项的自动化系统内对模糊地址进行地理编码,则适合改用 Places API Text Search 服务来替代 Place Autocomplete 服务。

用例和 API 建议

用例 API 建议
完整、不模糊的邮政地址 Google Maps Geocoding API 网络服务
用户输入的模糊查询(例如,不完整或格式混乱的地址) 利用 Places API Place Autocomplete 服务获得地点 ID,然后利用 Geocoding API 对地点 ID 进行地理编码,得到经纬度。
自动化系统内的模糊查询(例如,不完整或格式混乱的地址) 利用 Places API Text Search 服务获得地点 ID,然后利用 Geocoding API 对地点 ID 进行地理编码,得到经纬度。
实时响应用户输入 利用 Places API Place Autocomplete 服务获得地点 ID,然后利用 Geocoding API 对地点 ID 进行地理编码,得到经纬度。
以地址字符串形式指定起点、终点或路径点的情况下使用 Google Maps Directions API 或 Distance Matrix API 时的延迟时间问题 通过先利用 Places API Place Autocomplete 服务获得地点 ID,然后将地点 ID 传递给 Directions API 或 Distance Matrix API 来缩短地理编码延迟时间。

完整地址

完整邮政地址字符串(例如“48 Pirrama Rd, Pyrmont, NSW, Australia”)等不模糊查询利用 Geocoding API 网络服务进行处理的效果最好。其地址地理编码后端提供的全球地址覆盖范围更广,并且经过专门优化,可在进行这些类型的完整、不模糊查询时获得高质量结果。

模糊查询

模糊查询是指包含格式混乱地址、不完整地址或多余地址部分的查询。Geocoding API 网络服务地理编码器并非设计用于处理模糊查询,在响应模糊查询时产生的结果可能不太准确或不产生任何结果,如果查询包含多处拼写错误或无关的非地址词语,这种弱点就体现得更加明显。

如果在您的用例中用户可能会输入模糊查询(例如“123 Main Street”),我们建议使用 Places API 中的 Place Autocomplete 服务,因为该服务专为返回多个可能选项以及允许用户从这些选项中做出选择而设计。可限制 Places API 只搜索地理编码或地址,同时将商家排除在外。此外,自动填充查询功能可进行倾向性设置,使其只返回特定位置的结果。Places API 返回的地点 ID 可以全无歧义位置形式传递给 Geocoding API 网络服务,后者随即返回完整的地址详情,并对地址进行地理编码,得到经纬度。获得有关适用于 AndroidiOSJavaScript 以及 Places API Web Service 的 Place Autocomplete 服务的更多信息。

如果需要在无需用户从多个可能结果中进行选择的自动化系统内使用地址地理编码,但查询可能属于模糊或不完整查询,则可使用 Places API Text Search 服务来替代 Place Autocomplete 服务。Place Search 在处理模糊查询方面优于 Geocoding API,并且可以将搜索范围限定在指定区域,或者按距离对结果排名,从而提高模糊或不完整查询的结果过滤和排名精确度。

响应用户输入

实时响应用户输入的应用有两大因素会影响 API 的选择:

  1. 用户输入一般涉及渐进式输入地址,因此能够对不完整的模糊地址进行地理编码是有利的,因为它能让用户更快地获得结果。
  2. 响应用户输入的应用极易受到延迟时间的影响。

这两个因素使 Places API 中的 Place Autocomplete 服务成为响应用户输入用例的理想选择。Geocoding API 中的地址地理编码延迟时间长得多,在处理不完整或模糊查询时产生的结果也不太准确,因此对于需要实时响应用户输入的应用,不建议使用该 API。获得有关适用于 AndroidiOSJavaScript 以及 Places API Web Service 的 Place Autocomplete 服务的更多信息。

缩短 Directions API 和 Distance Matrix API 的延迟时间

以地址字符串形式指定起点、终点或路径点时,Google Maps Directions API Distance Matrix API 使用同一后端作为Geocoding API 来对这些地址进行地理编码,然后再计算路线。和指定与经纬度或地点 ID 相同的位置相比,这会使延迟时间显著增加。

如果应用使用 Directions API 或 Distance Matrix API 的情境容易受到延迟时间的影响(例如响应用户输入),并且起点、终点或路径点最初是以地址字符串形式指定,我们建议您通过以下方式最大限度缩短延迟时间:使用 Places API 的 Place Autocomplete 服务将地址字符串转换为地点 ID,然后将这些地点 ID 传递给 Directions API 或 Distance Matrix API。获得有关适用于 AndroidiOSJavaScript 以及 Places API Web Service 的 Place Autocomplete 服务的更多信息。另请参阅 JavaScript 地点自动填充和路线示例

结论

对地址进行地理编码时,根据具体用例使用 Geocoding API 或 Places API,或将 Place Autocomplete 服务或 Place Search 服务与 Geocoding API 结合使用,可以开发出既能为用户提供准确的地理编码结果,又能缩短延迟时间的应用。

管理错误和重试

如果收到 UNKNOWN_ERROR 响应,它们是由瞬时错误导致的,短暂延迟后重试是最佳应对方法。我们建议利用包括重试逻辑并支持Google Maps APIs Premium Plan 身份验证的 Google Maps APIs 网络服务客户端内容库Java ClientPython ClientGo ClientNode.js Client for Google Maps Services 是社区支持的客户端内容库,可从 GitHub 下载以及向其贡献代码,GitHub 上还提供了安装说明和示例代码。

如果超过了 API 的使用限额,作为响应,您会收到 OVER_QUERY_LIMIT 状态代码。我们建议您尝试这些使用优化策略

发送以下问题的反馈:

此网页
Google Maps Geocoding API
Google Maps Geocoding API
需要帮助?请访问我们的支持页面