此页面由 Cloud Translation API 翻译。

Routes API 迁移指南

目前，Google Maps Platform 支持 Directions API 和 Distance Matrix API。此版本的新 Routes API 包含针对现有 Directions API 和 Distance Matrix API 的新一代性能优化版本：

计算路线：利用全面的全球路由数据和实时流量计算位置之间的路线。
计算路线矩阵：计算一系列出发地/目的地对的距离和行程时间。

Routes API 包含许多新功能，包括：

TWO_WHEELER 路由
通行费计算
可感知路况的多段线
多段线质量控制
质量延迟控制
结果流式传输（仅使用 gRPC 的计算路由矩阵）
gRPC 支持

如需详细了解 Routes API，请参阅 Routes API。

本指南介绍了如何迁移使用 Directions API 和 Distance Matrix API 的现有应用，以使用新的 Routes API。

新版 Routes API 中的功能变更

概括来讲，Routes API 会对 Directions API 和 Distance Matrix API 进行以下更改：

将 Compute Routes 和 Compute Route Matrix 整合到名为 Routes API 的服务下

您必须先在 API 控制台中启用 Routes API，然后才能使用 Compute Routes 和 Compute Route Matrix。目前，您需要在 API 控制台中将 Directions API 和 Distance Matrix API 作为单独的服务启用。

如需了解详情，请参阅在 Google API 控制台中设置。
New Routes API 使用 HTTP POST 请求

在新的 Routes API 中，您可以通过请求正文或 HTTP POST 请求的形式在标头中传递参数。相比之下，使用 Directions API 和 Distance Matrix API 时，您可以使用 HTTP GET 请求传递网址参数。

如需查看示例，请参阅：
- 计算路线
- 计算路由矩阵
必须遮盖字段

调用新的 Routes API 以计算路线或计算路线矩阵时，您必须指定要在响应中返回哪些字段。没有默认返回的字段列表。如果省略此列表，这些方法会返回错误。

通过创建响应字段掩码来指定字段列表。然后，您可以使用网址参数 $fields 或 fields 或使用 HTTP/gRPC 标头 X-Goog-FieldMask 将响应字段掩码传递给每个方法。

字段遮盖是一种很好的设计做法，可以确保您不会请求不必要的数据，这有助于避免不必要的处理时间和结算费用。

如需了解详情，请参阅选择要返回的字段。
计算路由矩阵的新请求限制

Distance Matrix API 实施了以下请求限制：
- 每个请求最多包含 25 个出发地或 25 个目的地。
- 每个服务器端请求最多包含 100 个元素（出发地数量 × 目的地数量）。
计算路由矩阵会强制执行以下请求限制：
- 元素数量不能超过 625。
- 如果您指定 TRAFFIC_AWARE_OPTIMAL，则元素数量不能超过 100 个。如需详细了解 TRAFFIC_AWARE_OPTIMAL，请参阅配置质量与延迟时间。
- 您可以使用地点 ID 指定 50 个航点（出发地 + 目的地）。

用于配置质量与延迟的新选项

新的 Routes API 支持三种路由偏好设置，可用于明确配置路由质量与响应延迟时间：

TRAFFIC_UNAWARE（默认）- 使用与时间无关的平均流量数据（而不是实时路况数据）来计算路线，从而最大限度缩短响应延迟时间。此设置相当于在 Directions API 和 Distance Matrix API 中不使用路况时。
TRAFFIC_AWARE - 针对性能优化的实时流量质量，用于缩短延迟时间。此设置是 Routes API 的新增设置，在 Directions API 和 Distance Matrix API 中对等。

与 TRAFFIC_AWARE_OPTIMAL 相比，应用某些优化可显著缩短延迟时间。
TRAFFIC_AWARE_OPTIMAL - 高质量、全面的流量数据，无需应用大部分性能优化。此设置产生的延迟时间最长，相当于 Directions API 和 Distance Matrix API 中的 departure_time 设置。

TRAFFIC_AWARE_OPTIMAL 路线偏好设置等同于 maps.google.com 和 Google 地图移动应用使用的模式。

在 Directions API 和 Distance Matrix API 中，我们仅提供等效的 TRAFFIC_AWARE_OPTIMAL 和 TRAFFIC_UNAWARE 选项。这些选项是根据您是否设置了 departure_time 而隐式设置的。

下表比较了当前 Directions API 和 Distance Matrix API 选项以及新的 Routes API 选项：

模式当前 Routes API 备注

没有实时路况未设置 departure_time 属性 TRAFFIC_UNAWARE 三种模式的最快延迟时间。

已应用实时路况信息

无对应报告

模式	当前	Routes API	备注
没有实时路况	未设置 `departure_time` 属性	`TRAFFIC_UNAWARE`	三种模式的最快延迟时间。
已应用实时路况信息	无对应报告	`TRAFFIC_AWARE`	Routes API 新增了模式。它可提供比 `TRAFFIC_UNAWARE` 略长的延迟时间，但 ETA 质量较低。其延迟时间比 `TRAFFIC_AWARE_OPTIMAL` 低很多。
已应用优质、全面的实时流量数据	已设置 `departure_time` 个属性	`TRAFFIC_AWARE_OPTIMAL`	这相当于 maps.google.com 和 Google 地图移动应用使用的模式。对于计算路由矩阵，请求中的元素数量（源数 × 目标数）不能超过 100。

TRAFFIC_AWARE

Routes API 新增了模式。它可提供比 TRAFFIC_UNAWARE 略长的延迟时间，但 ETA 质量较低。

其延迟时间比 TRAFFIC_AWARE_OPTIMAL 低很多。

已应用优质、全面的实时流量数据

已设置 departure_time 个属性

TRAFFIC_AWARE_OPTIMAL

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

对于计算路由矩阵，请求中的元素数量（源数 × 目标数）不能超过 100。

Routes API 还会修改 duration 响应属性的设置方式，并修改当前响应中返回的属性，如下表所示：

预计到达时间当前 Routes API

不知道时间的预计到达时间。

预计到达时间	当前	Routes API
不知道时间的预计到达时间。	对应于请求中未设置的 `departure_time`。 `duration` 响应属性中包含的 ETA。系统不会返回 `duration_in_traffic` 响应属性。	对应于 `TRAFFIC_UNAWARE`。 `duration` 响应属性中包含的 ETA。 `duration` 和 `staticDuration` 响应属性包含相同的值。
加大型文字广告会考虑实时流量。	对应于请求中的 `departure_time` 设置。将实时流量考虑在内的 ETA 包含在 `duration_in_traffic` 响应属性中。	对应于 `TRAFFIC_AWARE` 或 `TRAFFIC_AWARE_OPTIMAL`。将实时流量考虑在内的 ETA 包含在 `duration` 响应属性中。 `staticDuration` 响应属性包含该路线的行程时长，而不考虑路况条件。不再返回 `duration_in_traffic` 属性。

对应于请求中未设置的 departure_time。

duration 响应属性中包含的 ETA。
系统不会返回 duration_in_traffic 响应属性。

对应于 TRAFFIC_UNAWARE。

duration 响应属性中包含的 ETA。
duration 和 staticDuration 响应属性包含相同的值。

加大型文字广告会考虑实时流量。

对应于请求中的 departure_time 设置。

将实时流量考虑在内的 ETA 包含在 duration_in_traffic 响应属性中。

对应于 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL。

将实时流量考虑在内的 ETA 包含在 duration 响应属性中。
staticDuration 响应属性包含该路线的行程时长，而不考虑路况条件。
不再返回 duration_in_traffic 属性。

如需了解详情，请参阅配置质量与延迟。

Routes API 不支持的现有功能

Routes API 不支持以下功能：

XML 作为响应格式。仅支持 JSON 和 gRPC。
反向地理编码

现在，您可以使用 Reverse Geocoding API 来实现此功能，该 API 是针对该用例构建的，旨在提供更高质量的结果。

迁移到 Routes API

我们对 Routes API 做出了一些更改。大多数变更都向后兼容当前的 API，但在下文列出了几项破坏性更改，需要您在应用迁移到 Routes API 时予以关注。

更新 REST API 端点

如果您使用的是 Directions API，请更新您的代码以使用新的 Routes API 端点：

Directions API	`https://maps.googleapis.com/maps/api/directions/outputFormat?parameters`
Routes API	`https://routes.googleapis.com/directions/v2:computeRoutes`

如果您使用的是 Distance Matrix API，请更新您的代码以使用新的 Routes API 端点：

Distance Matrix API	`https://maps.googleapis.com/maps/api/distancematrix/outputFormat?parameters`
Routes API	`https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix`

将网址参数转换为使用 HTTP 请求正文

借助 Directions API 和 Distance Matrix API，您可以将配置属性作为网址参数传递给 HTTP GET 请求。例如，对于 Directions API：

https://maps.googleapis.com/maps/api/directions/outputFormat?parameters

借助 Routes API，您可以通过 HTTP POST 请求在请求正文或标头中传递参数。如需查看示例，请参阅：

将当前参数转换为 Routes API 参数

下表列出了当前 Directions API 和 Distance Matrix API 中已重命名或修改的参数，或预览版不支持的参数。如果您使用的是其中任何参数，请更新您的代码。

当前参数	Routes API 参数	备注
`destination`	`destination`	预览版中的地址和 Plus 代码不可用。
`origin`	`origin`	预览版中的地址和 Plus 代码不可用。
`alternatives`	`computeAlternativeRoutes`
`arrival_time`		无法预览，因为预览模式下无法使用“`TRANSIT`”模式。
`avoid`	`routeModifiers`
`copyrights`		不适用于预览版。
`departure_time`	`departureTime`
`distance`	`distanceMeters`	距离仅可用米为单位。
`duration_in_traffic`		已在 Routes API 中移除，请使用 `duration`。如需了解详情，请参阅上文的新 Routes API 的功能变化。
`language`	`languageCode`
`mode`	`travelMode`	添加了对 `TWO_WHEELER` 的支持。预览版不支持 `TRANSIT` 模式。
`region`		在预览版中不可用，因为地址不受支持。
`status`		不适用于预览版。针对该 API 报告的错误使用 HTTP 响应代码。如需了解详情，请参阅处理请求错误。
`traffic_model`		不适用于预览版。
`transit_mode`		无法预览，因为预览模式下无法使用“`TRANSIT`”模式。
`transit_routing_preference`		无法预览，因为预览模式下无法使用“`TRANSIT`”模式。
`units`		不适用于预览版中的距离矩阵。
`waypoints`	`intermediates`	预览版和地址和多段线不可用。
`optimize=true`：航点		不适用于预览版。