为什么要迁移到 Routes API？

Routes API 在计算路线、距离和行程时间方面的性能得到了提升，因此值得替换目前使用 Directions API 和 Distance Matrix API 的应用。Routes API 的大多数功能都向后兼容 Directions API 和 Distance Matrix API。

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

主要改进

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

提高了请求限制

Routes API
  • 最多 625 个元素，除非您指定 TRAFFIC_AWARE_OPTIMAL。
  • 最多可包含 100 个元素，其中包括 TRAFFIC_AWARE_OPTIMAL。请参阅增强型路由偏好设置。
  • 使用地点 ID 时，航点（出发地 + 目的地）的数量上限为 50 个。
Distance Matrix API
  • 每个请求最多包含 25 个出发地或 25 个目的地。
  • 每个服务器端请求最多包含 100 个元素（出发地数量 × 目的地数量）。

更快的请求响应

计算路线矩阵功能可缩短以下延迟时间：

  • 在计算整个矩阵之前接收响应的流式元素。
  • 使用字段掩码自定义响应详情，仅请求所需的数据，这也是一项有助于降低费用的最佳实践。
  • 增强了针对交通的路线计算功能，以便您在数据质量和响应时间之间进行权衡。

路由增强功能

计算路线功能提供了以下路由增强功能：

  • 除了距离和预计到达时间之外，还会显示过路费信息。
  • 2 轮机动车路线。
  • 为您的中途停留航点指定资格条件，以确保安全。
  • 通过为航点设置行驶方向和路侧，提高了预计到达时间 (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 API 与 Directions API 和 Distance 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 请求传递网址参数。

ETA 回复差异

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

ETA 类型 Routes API Directions API
Distance Matrix API
不考虑路况、与时间无关的 ETA。

使用 TRAFFIC_UNAWARE 进行设置。

  • duration 响应属性中包含的预计到达时间 (ETA)。
  • duration 和 staticDuration 响应属性包含相同的值。

对应于请求中未设置 departure_time。

  • duration 响应属性中包含的预计到达时间 (ETA)。
  • 系统不会返回 duration_in_traffic 响应属性。
考虑实时路况信息的预计到达时间。

使用 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL 进行设置。

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

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

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

多段线航点

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

设置了格式的地址（反向地理编码）

Routes API 不会在响应中提供设置了格式的地址。如需获取格式化的地址，请使用专为此用例而构建的 Geocoding API，它可提供更高质量的结果。

可用的出行方式

与 Directions API 一样，如果路线请求未指定出行方式，Routes API 会将“驾车”用作默认模式。不过，如果请求确实为路线指定了出行方式，Routes API 不会返回可用出行方式的数组作为请求的替代选项。如果您的用例依赖于此功能，请提交问题，说明您如何使用此功能，以便我们进行后续跟进。

使用 XML 作为响应格式

Routes API 不提供 XML 作为响应格式。您可以在网上找到许多适合您需求的 JSON 转换为 XML 的转换器。