为什么要迁移到 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 个元素（出发地数量 × 目的地数量）。

更快地响应请求

计算路由矩阵功能提供以下延迟方面的改进：

  • 在计算整个矩阵之前接收响应的流式元素。
  • 使用字段掩码自定义响应详细信息，仅请求您需要的数据，这种做法也有助于降低费用。
  • 增强了流量路线计算，让您可以在数据质量和响应时间之间进行权衡。

路由增强功能

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

  • 除距离和预计到达时间之外，还包含收费信息。
  • 双轮车辆路线。
  • 甄别中途停留航点，以确保安全。
  • 通过为航点设置行进方向和路边，提高了预计到达时间的精确度。

仅请求您需要的数据

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

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 请求传递网址参数。

预计到达时间的回答差异

Routes API 会返回 ETA，并使用 duration 响应属性（与 Directions API 和 Distance Matrix API 服务不同），如下表所示。

预计到达时间类型 Routes API Directions API
Distance Matrix API
不了解路况、与时间无关的预计到达时间。

使用 TRAFFIC_UNAWARE 进行设置。

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

对应于请求中未设置 departure_time。

  • duration 响应属性中包含的预计到达时间。
  • 不会返回 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，该 API 可提供更优质的结果。

可用的出行方式

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

使用 XML 作为响应格式

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