Routes API 目前处于预览版阶段(正式发布前)。正式发布前产品和功能的支持可能有限,并且对正式发布前产品和功能的变更可能与其他正式发布前版本不兼容。正式发布预备产品受 Google Maps Platform 服务专用条款的约束。如需了解详情,请参阅发布阶段说明

Routes API 迁移指南

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

目前,Google Maps Platform 支持 Directions APIDistance 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 以计算路线或计算路线矩阵时,您必须指定要在响应中返回哪些字段。没有默认返回的字段列表。如果省略此列表,这些方法会返回错误。

    通过创建响应字段掩码来指定字段列表。然后,您可以使用网址参数 $fieldsfields 或使用 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_OPTIMALTRAFFIC_UNAWARE 选项。这些选项是根据您是否设置了 departure_time 而隐式设置的。

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

    模式 当前 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。

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

    预计到达时间 当前 Routes API
    不知道时间的预计到达时间。

    对应于请求中未设置的 departure_time

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

    对应于 TRAFFIC_UNAWARE

    • duration 响应属性中包含的 ETA。
    • durationstaticDuration 响应属性包含相同的值。
    加大型文字广告会考虑实时流量。

    对应于请求中的 departure_time 设置。

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

    对应于 TRAFFIC_AWARETRAFFIC_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:航点 不适用于预览版。