为什么要迁移到 Routes API?

Routes API 改进了路线、距离和行程时间的计算性能,因此值得取代目前使用 Directions API 和 Distance Matrix API 的应用。Routes API 的大部分功能都向后兼容 Directions API 和 Distance Matrix API。

使用本指南可以了解 Routes API 与其所取代产品之间的主要区别,以及如何处理必要的更改。如需详细了解其他 Routes API 功能,请参阅产品概览

主要改进

本部分将介绍在您的应用中使用 Routes API 时可以获得的一些增强功能。

提高请求限制

Routes API
  • 除非您指定 TRAFFIC_AWARE_OPTIMAL,否则最多 625 个元素。
  • TRAFFIC_AWARE_OPTIMAL 最多包含 100 个元素。请参阅增强型路由偏好设置
  • 使用地点 ID 的航点数(出发地 + 目的地)不得超过 50 个。
Distance Matrix API
  • 每个请求最多包含 25 个出发地或 25 个目的地。
  • 每个服务器端请求最多包含 100 个元素(出发地数量 × 目的地数量)。

加快请求响应速度

计算路由矩阵功能可提供以下延迟时间方面的改进:

  • 在计算整个矩阵之前接收响应的流式传输元素
  • 使用字段掩码自定义响应详细信息,仅请求所需的数据,这是一种有助于降低费用的最佳实践。
  • 增强了流量路由计算,以便在数据质量和响应时间之间做出权衡。

路由增强功能

计算路由功能提供以下路由增强功能:

  • 通行费信息以及距离和预计到达时间。
  • 双轮机动车路线
  • 限定经停航点以确保安全。
  • 通过为航点设置行程方向和道路一侧,提高了预计到达时间 (ETA) 的准确度

仅请求您需要的数据

现在,您可以指定要返回的字段,从而缩短处理时间和结算费用。

Routes API 您的请求必须使用字段掩码来指定您希望在响应中返回的字段。字段遮盖可确保您不会请求不必要的数据,从而避免不必要的处理时间和结算费用。
如需了解详情,请参阅选择要返回的字段
Directions API
Distance Matrix API
返回默认的字段列表,即使您的应用并不严格需要这些字段。这可能会导致不必要的处理时间和结算费用。

增强型流量路线计算

Routes API 支持三种路由偏好设置,您在请求流量信息时,可以使用这些偏好设置在响应延迟时间和数据质量之间取得平衡。

如需了解详情,请参阅配置质量与延迟时间

TRAFFIC_UNAWARE
(默认)
使用与时间无关的平均流量数据(而非实时路况数据)来计算路线,从而将响应延迟时间降至最低。此设置等同于 Directions API 和 Distance Matrix API 中未使用路况时的情况。
TRAFFIC_AWARE
(新增)
针对性能进行了优化的实时流量质量,缩短延迟时间。与 TRAFFIC_AWARE_OPTIMAL 相比,此设置会应用优化来显著缩短延迟时间。 此设置也是 Routes API 的新功能,但在 Directions API 或 Distance Matrix API 中没有对应项。
TRAFFIC_AWARE_OPTIMAL 优质、全面的流量数据。此设置的延迟时间最长,等同于 Directions API 和 Distance Matrix API 中的 departure_time 设置。
此偏好设置等同于 maps.google.com 和 Google 地图移动应用使用的模式。

路线计算比较

下表比较了 Routes APIDirections APIDistance Matrix API 服务的路线选项。

流量选项 Routes API Directions API
Distance Matrix API
延迟时间
没有实时路况 TRAFFIC_UNAWARE 未设置 departure_time 属性 三种模式中的最快延迟时间。
已应用实时路况信息 TRAFFIC_AWARE 无对应报告

Routes API 添加的新模式。它的延迟时间比 TRAFFIC_UNAWARE 略长,但 ETA 质量的成本较低。

它的延迟时间比 TRAFFIC_AWARE_OPTIMAL 低得多。

应用优质、全面的实时路况数据 TRAFFIC_AWARE_OPTIMAL 已设置 departure_time 个媒体资源

相当于 maps.google.com 和 Google 地图移动应用使用的模式。

对于计算路线矩阵,请求中的元素数量(出发地数量 × 目的地数量)不能超过 100。

主要区别

本部分介绍了 Routes API 与其所取代的服务之间的主要区别,以及从现有应用中的这些服务迁移时可以应对这些差异的方法。

调用一项服务,而不是两项服务

Routes API 请在 API 控制台中仅为应用启用一项服务,以便使用“计算路线”和“计算路线矩阵”。
如需了解详情,请参阅在 Google API 控制台中进行设置
Directions API
Distance Matrix API
启用两项服务:在 API 控制台中将 Directions API 和 Distance Matrix API 作为单独的服务。

使用 HTTPS POST 请求

Routes API 将参数作为 HTTP POST 请求的一部分在请求正文或标头中传递。
如需查看示例,请参阅:
- 计算路线
- 计算路线矩阵
Directions API
Distance Matrix API
使用 HTTP GET 请求传递网址参数。

预计到达时间响应差异

Routes API 返回预计到达时间,使用 duration 响应属性的方式不同于 Directions API 和 Distance Matrix API 服务,如下表所示。

预计到达时间的类型 Routes API Directions API
Distance Matrix API
无法感知流量且与时间无关的预计到达时间。

使用 TRAFFIC_UNAWARE 进行设置。

  • duration 响应属性中包含的预计到达时间。
  • durationstaticDuration 响应属性包含相同的值。

对应于请求中未设置的 departure_time

  • duration 响应属性中包含的预计到达时间。
  • 系统不会返回 duration_in_traffic 响应属性。
考虑实时流量的预计到达时间。

使用 TRAFFIC_AWARETRAFFIC_AWARE_OPTIMAL 进行设置。

  • duration 响应属性中包含考虑实时流量的预计到达时间。
  • staticDuration 响应属性包含不考虑路况信息的情况下路线的行程时长。
  • 不再返回 duration_in_traffic 属性。

在请求中使用 departure_time 进行设置。

  • duration_in_traffic 响应属性中包含考虑实时流量的预计到达时间。

多段线航点

您无需再通过此服务将纬度/经度坐标转换为多段线航点,此服务支持 POST 请求正文,因此不再受网址字符串限制的影响。Distance Matrix API 的一些用户通过将纬度/经度点转换为多段线航点解决了请求限制问题。

设置了格式的地址(反向地理编码)

Routes API 不在响应中提供设置了格式的地址。如需获取设置了格式的地址,请使用专为此用例打造且可提供更优质结果的 Geocoding API。

可用的出行方式

与 Directions API 一样,当路线请求未指定出行模式时,Routes API 会将 DRIVE 用作默认模式。但是,如果请求确实为路线指定了出行方式,则 Routes API 不会返回可用出行方式数组作为请求的备用选项。如果您的用例需要此功能,请提交问题以描述您如何使用该功能,以便我们跟进。

使用 XML 作为响应格式

Routes API 不提供 XML 作为响应格式。您可以在线找到一些 JSON 到 XML 转换器,以满足自己的需求。