一切就绪!

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

激活 Google Maps Geocoding API

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

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

新版正向地理编码器常见问题解答

本常见问题解答涵盖的问题只涉及博文 Google Maps APIs 中的地址地理编码中宣布的新版正向地理编码器。另请参阅对地址进行地理编码时的最佳做法

对于涉及所有 Google Maps APIs 的共性问题,请参阅 Google Maps APIs 常见问题解答

入门指南

故障排除

入门指南

新版正向地理编码器将在何时成为默认地理编码器?
  • 对于发送给地理编码服务的 Google Maps Geocoding API 和 Google Maps JavaScript API 请求,新版正向地理编码器现已成为无法识别请求和标准计划客户的默认地理编码器。对于使用这些 API 的 Premium Plan 客户,此变更计划于 2017 年 1 月 17 日实施。
  • 对于所有使用 Google Maps Directions API、Google Maps Distance Matrix API、Google Static Maps API 和 Google Street View Image API 的客户(标准计划和Premium Plan),以及对于发送给 Directions 和 Distance Matrix 服务的 Google Maps JavaScript API 请求,新版正向地理编码器计划于 2017 年 1 月 24 日成为默认地理编码器。
  • 旧版地理编码器将在 2017 年 3 月末永久性退役。

如果遭遇无法预见的问题,或有其他功能同时发布,上述日期可能随时推迟。如果想在新版地理编码器全面实施前对系统进行任何变更,应该计划在上述日期前实施这些变更。

将有哪些 API 使用新版正向地理编码器?

下列 Google Maps APIs 利用同一地理编码器来处理以下请求:

:新版正向地理编码器从不在检索地点 ID 详情时使用。

在新版正向地理编码器成为默认地理编码器前该如何使用?

现在就可以通过 Geocoding API、Directions API、Distance Matrix API 以及 Maps JavaScript API 中提供的 GeocodingDirectionsDistance Matrix 服务使用新版正向地理编码器。

对于 Geocoding API、Directions API 以及 Distance Matrix API,请为请求添加 new_forward_geocoder=true 可选参数。

对于 Google Maps APIs 网络服务客户端内容库,要想使用新版正向地理编码器,请为请求添加 new_forward_geocoder=true。这是一个近期添加到客户端内容库中的自定义网址参数。

在 Maps JavaScript API 中提供的 GeocodingDirectionsDistance Matrix 服务中,在相应的请求对象中设置新增的可选参数 newForwardGeocoder: true。实验性和发行版本中都提供了这个参数。

Google Maps API 地理编码器工具更新了一项可选设置。使用该工具时,如果想根据新版正向地理编码器功能生成结果,请选中“Use the new forward geocoder”。

注:Static Maps API 和 Street View Image API 中尚未提供新版正向地理编码器。

在旧版正向地理编码器不再是默认地理编码器后该如何使用?

在 2017 年 3 月 29 日旧版正向地理编码器永久性退役前,可以继续使用该编码器。

对于 Geocoding API、Directions API 和 Distance Matrix API,请为请求添加 new_forward_geocoder=false 可选参数。

对于 Google Maps APIs 网络服务客户端内容库,要想使用旧版正向地理编码器,请为请求添加 new_forward_geocoder=false。这是一个近期添加到客户端内容库中的自定义网址参数。

在 Maps JavaScript API 中提供的 GeocodingDirectionsDistance Matrix 服务中,在相应的请求对象中设置新增的可选参数 newForwardGeocoder: false。实验性和发行版本中都提供了这个参数。

注:对于 Static Maps API 和 Street View Image API,新版正向地理编码器尚无法使用,因此无需将此选项设置为 false。Static Maps API 和 Street View Image API 暂时继续使用旧版正向地理编码器。

为何要进行这一变更?

新版正向地理编码器与消费性 Google 地图应用使用的地理编码器相同。旧版地理编码器已弃用,将会退役。

这一变更是否向后兼容?

是的,Geocoding API 保留了相同的请求和响应格式。新版地理编码器在处理许多查询时可能都会产生不同的结果集,但请求在现有格式下仍然有效,并且新结果返回的字段也相同。

故障排除

我使用新版地理编码器时返回 ZERO_RESULTS 的查询增加。这是怎么回事?

使用新版地理编码器时,模糊、不完整和格式混乱的查询容易产生 ZERO_RESULTS。使用旧版地理编码器时,这些查询通常会产生不正确的结果,例如找不到地址时返回郊区。我们认为,在此类情况下返回 ZERO_RESULTS 实际上是更为正确的响应。

如果应用需要处理用户输入的地址,Places API 中的地点自动填充功能生成的结果质量可能更好。地点自动填充根据用户已键入的内容让其从一组结果中进行选择,便于用户在名称相似的结果之间做出选择,以及在地址拼写错误时调整查询内容。

如果应用输入来自无需用户从一组自动填充建议中进行选择的自动化系统,并且可能需要处理模糊或不完整的查询,或者可能包含商家名称等非地址组成部分的查询,则 Places API Text Search 或许是更好的选择。Text Search 更有可能为模糊查询返回结果,因为这些类型的查询可能包含 Geocoding API 不予考虑的商家名称。

如果应用需要处理模糊或不完整的查询,或者可能包含非地址组成部分的查询,我们建议您使用 Places API,而不要使用 Geocoding API 中提供的正向地理编码器。欲知更多详情,请参阅对地址进行地理编码时的最佳做法Google Maps API 博文中的“地址地理编码”

我需要快速响应,新版地理编码器响应过慢,无法满足我的应用需求。我可以使用什么来加快响应速度呢?

对于因需要响应用户输入而极易受到延迟时间影响的应用,我们建议使用 Places API 中提供的地点自动填充功能(JavaScriptAndroidiOS 中亦有提供),而不要使用地址地理编码。地点自动填充针对交互式用途进行了优化,因此延迟时间很短。

Geocoding API 中的地址地理编码经过专门优化,适合处理完整、不模糊、格式正确的地址(例如输入到现在表单中的递送地址),因此延迟时间长于地点自动填充。旧版正向地理编码器就已如此。地点自动填充与新版正向地理编码器之间在延迟时间上的差距进一步拉大,因为新版地理编码器覆盖范围更广,结果质量更佳,但代价是延迟时间又有些许增加。

我如何才能缩短 Directions API 和 Distance Matrix API 上的延迟时间呢?

请不要使用地址,而是使用地点 ID 来指定路径点、起点和终点。最好通过 Places API 中的地点自动填充功能或 Maps JavaScript API 中的 Places 内容库获得地点 ID。另请参阅有关 placeIdOnly 选项的信息,可利用该选项来减少地点自动填充的系统开销。

通过地址字符串而不是地点 ID 或经纬度查询 Directions API 或 Distance Matrix API 时,他们会使用与 Geocoding API 相同的后端将该地址转换成地点 ID,然后再计算路线。地点自动填充的速度快于地址地理编码。对于在极易受到延迟时间影响的情境(例如响应用户输入)下使用 Directions API 或 Distance Matrix API 的应用,我们建议您利用地点自动填充获取这些地址对应的地点 ID,然后将地点 ID 传递给 Directions API 或 Distance Matrix API。即便是与旧版地址地理编码器相比,这种方法对延迟时间的缩短幅度也很大。请参阅我们的文档中有关如何利用地点自动填充计算路线的示例

我是的客户,Places API 成本过高。我能采取什么措施来降低成本吗?

我们建议使用 Maps JavaScript API Place autocomplete 小部件。要想减少使用 autocomplete 小部件的系统开销,请利用新增的 placeIdOnly 选项启用 Place Autocomplete 服务对地点 ID 的直接获取。对于只需要商家地址而不需要其完整详情的应用,placeIdOnly 选项会跳过地点详情请求。要获取对应的地址,请将地点 ID 传递给 Geocoding 服务或 Geocoding API。还可以将地点 ID(而不是地址文本字符串或纬度/经度对)传递给 Directions 或 Distance Matrix 服务,或者 Directions API 或 Distance Matrix API。

Google Maps API 地理编码工具 Place Autocomplete 和 Directions 示例已更新内容,以说明新增 placeIdOnly 选项的用法。

如何在新版地理编码器中报告错误?

如果对新版正向地理编码器服务有任何错误报告功能请求,请利用我们的公共 Issue Tracker 告知。

我在自己的用例中使用新版地理编码器未能获得满意的结果。我可以获得哪些帮助?

请利用我们的公共 Issue Tracker 分享几个使用新版地理编码器时产生更低质量结果的具体查询,让我们了解相关情况,以便通过调查确认是否存在任何造成结果质量问题的错误或系统问题,或者是否可以对最佳做法指南做出任何更改,以帮助开发者提高结果质量。

新版地理编码器中的组成部分过滤工作方式不同于旧版地理编码器。在新版地理编码器中如何使用组成部分过滤才能获得最佳效果?

在新版地理编码器中,只完整支持地址一级结果的组成部分过滤。对于行政区划和更高一级结果,部分支持国家代码(例如 components=country:GB)和邮政编码限制。以下示例说明了如何根据所需结果最充分地利用组成部分过滤。务必将示例请求网址中的“YOUR_API_KEY”替换为实际使用的 API 密钥。

  • 要将地址(包括建筑物、街道和道路)范围限定在某个政治区域(国家、行政区划等),请按使用旧版地理编码器的相同方式使用组成部分过滤。新版地理编码器支持这一用法。例如:address=gordon&components=locality:dublin 返回“Gordon Way, Dublin, OH 43017, USA”。
    https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=true&address=gordon&components=locality:dublin&key=YOUR_API_KEY
    
  • 要将邮政编码范围限定在特定国家,请按使用旧版地理编码器的相同方式使用组成部分过滤,但务必使用 ISO 3166-2 国家代码指定国家限制。新版地理编码器支持这一用法。例如:components=country:CH|postal_code:2000 返回“2000 Neuchâtel, Switzerland”。
    https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=true&components=country:CH%7Cpostal_code:2000&key=YOUR_API_KEY
    
  • 要将其他非地址(例如城市或街区)查询范围限定在特定国家,请按使用旧版地理编码器的相同方式使用组成部分过滤,但务必使用 ISO 3166-2 国家代码指定国家限制。在新版地理编码器中,不再保证找到与旧版地理编码器相同的结果。将范围限定在所需国家时,使用地点自动填充可获得质量更高的结果。

    示例:

    • 使用旧版地理编码器时,对 components=country:US%7Clocality:paris 的地理编码会返回若干个名为“Paris”的美国城市。
      https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=false&components=country:US%7Clocality:paris&key=YOUR_API_KEY
      
    • 使用新版地理编码器时,对 components=country:US%7Clocality:paris 的地理编码会返回“Paris, TX, USA”,但不会返回任何其他名为“Paris”的美国城市。
      https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=true&components=country:US%7Clocality:paris&key=YOUR_API_KEY
      
    • 如果为 input=paris&components=country:us&types=(regions) 使用地点自动填充,同时使用 locationradius 指定视口来使位置结果产生偏向性,则生成的响应价格包含若干个名为“Paris”的美国城市。
      https://maps.googleapis.com/maps/api/place/autocomplete/json?location=37.386052,-122.083851&radius=10000&input=paris&components=country:us&types=(regions)&key=YOUR_API_KEY
      
  • 要将其他非地址(例如城市或街区)查询范围限定在特定国家以外的其他区域,使用新版地理编码器中的组成部分过滤无法保证能够找到与旧版地理编码器相同的结果。将范围偏向于指定区域(locationradius)时,使用地点自动填充可获得质量更高的结果。还可以利用新增的 strictbounds 参数将结果范围限定在指定区域。

    示例:

    • 使用旧版地理编码器时,对 administrative_area:Anaga|locality:Santa+Cruz 的地理编码会返回 Santa Cruz de Tenerife 的行政区划以及 Anaga 的行政区域。
      https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=false&components=administrative_area:Anaga%7Clocality:Santa%20Cruz&key=YOUR_API_KEY
      
    • 使用新版地理编码器时,对 administrative_area:Anaga|locality:Santa+Cruz 的地理编码只会返回 Anaga 的行政区域,而不会返回所需的 Santa Cruz de Tenerife 的行政区划。
      https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=true&components=administrative_area:Anaga%7Clocality:Santa%20Cruz&key=YOUR_API_KEY
      
    • input=santa+cruz&location=28.494168,-16.275751&radius=20000&types=geocode 使用地点自动填充时,会先返回“Santa Cruz de Tenerife, Spain”,也会返回其他城市,例如“Santa Cruz de La Palma”(在另一座岛上)和“Santa Cruz, CA, United States”。
      https://maps.googleapis.com/maps/api/place/autocomplete/json?input=santa+cruz&location=28.494168,-16.275751&radius=20000&types=geocode&key=YOUR_API_KEY
      
    • 为以上地点自动填充请求添加 strictbounds 可将返回的结果范围限定在指定区域(“Anaga”)。
      https://maps.googleapis.com/maps/api/place/autocomplete/json?input=santa+cruz&location=28.494168,-16.275751&radius=20000&types=geocode&strictbounds&key=YOUR_API_KEY
      

发送以下问题的反馈:

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