地理编码是将地址（如街道地址）转换为地理坐标（纬度和经度）的过程，您可以根据地理编码在地图上放置标记，或在地图上定位。本文档旨在阐明对地址进行地理编码时所涉及的注意事项。其中介绍了使用 Geocoding API 的最佳时机，以及何时使用 Places API 的“地点自动补全”服务有益。
一般而言，在对完整地址（例如，“48 Pirrama Rd, Pyrmont, NSW, Australia”）进行地理编码时使用 Geocoding API。在对不确定（不完整）的地址进行地理编码时使用，或用于对延迟时间敏感的应用（例如响应用户输入时）使用 Places API 地点自动补全服务。
用例和 API 建议
| 用例和 API 建议 | |
|---|---|
| 实时响应用户输入（包括用户输入的模糊、不完整、格式有误或拼写错误的地址） | 使用 Places API 的“地点自动补全”服务获取地点 ID，然后使用 Geocoding API 将地点 ID 地理编码为纬度/经度。 |
| 自动系统处理完整、不模糊、邮寄地址（例如“48 Pirrama Rd, Pyrmont, NSW, Australia”） | 使用 Geocoding API 网络服务。 |
| 自动化系统处理不明确的查询（例如，不完整、格式有误或拼写错误的地址） | 推荐自动化系统使用 Geocoding API 网络服务。但是，如果根据用户输入衍生出大量不明确、不完整或拼写错误的查询，自动系统或许可以从添加互动式地点自动补全微件中获益，让用户可以选择搜索结果，从而避免地址拼写错误。 |
| 使用 Directions API 或 Distance Matrix API 遇到的延迟问题（将出发地、目的地或航点指定为地址字符串） | 使用 Places API 的“地点自动补全”服务获取地点 ID，然后将地点 ID 传递给 Directions API 或 Distance Matrix API，从而缩短地理编码延迟时间。 |
响应用户输入
实时响应用户输入的应用有两个主要考虑因素会影响 API 的选择：
- 用户输入通常涉及逐步输入地址（如“123 Main Street”），因此能够对不完整、含糊不清的地址进行地理编码是有益的，因为它可以让用户更快地获得结果。
- 响应用户输入的应用极易受到延迟时间的影响。
这两个注意事项使得 Places API 中的地点自动补全服务非常适合响应用户输入的用例。地点自动补全功能旨在返回多个可能的选项，并允许用户从中选择。Places API 可以限制为仅搜索地理编码或地址，同时排除商家。此外，自动补全查询功能可能会偏向为返回特定于某个位置的结果。Places API 会返回地点 ID，该 ID 可作为完全消除歧义的位置传递给 Geocoding API 网络服务，然后该服务会返回完整的地址详细信息，并将地址地理编码为 latlng。地点 ID 也可以传递给其他 API，例如 Directions API 和 Distance Matrix API（请参阅下文）。
Geocoding API 中的地址地理编码延迟时间要长得多，对不完整或模糊查询产生的结果也不太准确，因此不建议需要实时响应用户输入的应用使用地理编码。
详细了解适用于 Android、iOS、JavaScript 和 Places API 的地点自动补全服务。
自动化系统
自动化系统处理，完整且清楚的邮政地址：明确邮政地址字符串（如“48 Pirrama Rd, Pyrmont, NSW, Australia”）等不模糊查询最好由 Geocoding API 网络服务处理。地址地理编码后端可覆盖全球范围内的地址，并针对这些类型的完整、不模糊查询进行了优化，以获得优质结果。
自动化系统处理模糊查询：模糊查询是指地址格式不正确、地址或地址拼写错误。对于自动化系统，我们建议使用 Geocoding API 网络服务。但是，Geocoding API 无法应对模糊查询，在响应不确定查询时，生成的结果可能不准确或者为零。 如果您的自动化系统会处理大量来自用户输入的模糊查询，您不妨使用 Places API 中的地点自动补全服务向您的应用添加交互式元素，因为这种设计旨在返回多个可能的选项，并允许用户从这些选项中进行选择。Places API 会返回一个地点 ID，它可以作为完全消除歧义的位置传递给 Geocoding API 网络服务，然后该服务会返回完整的地址详细信息，并将地址地理编码为 latlng。详细了解适用于 Android、iOS、JavaScript 和 Places API 的地点自动补全服务。
缩短 Directions API 和 Distance Matrix API 的延迟时间
如果将出发地、目的地或航点指定为地址字符串，则 Directions API 和 Distance Matrix API 会使用与 Geocoding API 相同的后端对这些地址进行地理编码，然后再计算路线。与指定与经纬度或地点 ID 相同的位置相比，这会显著增加延迟时间。
如果您的应用使用 Directions API 或 Distance Matrix API（例如响应用户输入），并且起点、目的地或航点最初指定为地址字符串，那么我们建议您先使用 Places API 的“地点自动补全”服务将地址字符串转换为地点 ID，然后将地点 ID 传递给 Directions API 或 Distance Matrix API，以尽量缩短延迟时间。详细了解适用于 Android、iOS、JavaScript 和 Places API 的地点自动补全服务。 另请参阅地点自动补全和路线的 JavaScript 示例。
总结
根据您的用例，在对地址进行地理编码时，使用 Geocoding API 或将地点自动补全服务与 Geocoding API 结合使用，即可创建能向用户提供准确地理编码结果并缩短延迟时间的应用。
管理错误和重试
如果您收到 UNKNOWN_ERROR 响应，则说明这些是暂时性错误所导致的，在短暂延迟后重试是最佳解决方案。我们建议使用 Google Maps Platform 网络服务客户端库，其中包含重试逻辑并支持 Google Maps Platform 高级计划身份验证。适用于 Google 地图服务的 Java 客户端、Python 客户端、Go 客户端和 Node.js 客户端是社区支持的客户端库，可在 GitHub 上下载和贡献内容，您还可以在其中找到安装说明和示例代码。
如果您收到 OVER_QUERY_LIMIT 状态代码作为响应，则表示您已超出该 API 的使用限制。建议您尝试这些使用情况优化策略。