从 Directions API（旧版）或 Distance Matrix API（旧版）迁移

欧洲经济区 (EEA) 开发者

本指南介绍如何将使用 Directions API 或 Distance Matrix API 的应用迁移到使用 Routes API。如需详细了解 Routes API，请参阅 产品概览。

迁移的结算最佳实践

如果您的 API 用量足够高，可以进入第二层级价格，则适用此指南。迁移到较新版本的 API 时，您还需要为不同的 SKU 付费。为避免在过渡月份增加费用，我们建议您尽可能在月初将生产环境中的 API 切换到新 API。这样可确保您在迁移月份达到最具成本效益的每月价格层级。如需了解价格层级， 请参阅价格页面 和价格常见问题解答。

更新 REST API 端点

更新代码以使用新的 Routes API 端点

从 Directions API

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

从 Distance Matrix API

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

转换网址参数以使用 HTTPS 请求正文

使用 Directions API 和 Distance Matrix API 时，您需要将配置属性作为网址参数传递给 HTTP GET 请求。例如，对于 Directions API：

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

使用 Routes API 时，您需要在请求正文或标头中传递参数，作为 HTTP POST 请求的一部分。如需查看示例，请参阅：

将多段线编码的航点转换为位置航点

在 Directions API（旧版）中，您可以将航点指定为编码的多段线，以便在 16384 个字符的网址限制内容纳大量 航点。Routes API 中不需要此功能，因为航点可以作为经纬度坐标在 REST 或 gRPC 请求正文中传输。如需查看示例， 请参阅 HTTP 示例 在 计算路线矩阵 文档中，或 定义中间航点 在 指定中间航点 文档中。

转换参数

下表列出了 Directions API 和 Distance Matrix API 中已重命名或修改的参数，或者正式版中不支持的参数。如果您使用了这些参数中的任何一个，请更新您的代码。

请求参数转换

路线或距离矩阵参数 Routes API 参数 备注
alternatives computeAlternativeRoutes
arrival_time arrivalTime 仅在 TRANSIT 模式下可用，且不能与 同时使用 departureTime。
avoid routeModifiers
departure_time departureTime 不能与 arrivalTime 同时使用。
language languageCode 仅支持计算路线。
mode travelMode

使用 RouteTravelMode 值 （DRIVE、 TWO_WHEELER、 WALK、 TRANSIT、 TRUCK、 或 BICYCLE ，适用于 computeRoutes）在 computeRoutes 或 computeRouteMatrix HTTP POST JSON 请求正文中传递，而不是使用 GET 网址查询参数。增加了对 TWO_WHEELER、 TRANSIT 和 TRUCK 的支持。
region regionCode
traffic_model trafficModel 了解详情
transit_mode "travelMode": "TRANSIT" 在 Directions API（旧版）中，在公交路线中，具有相同出行方式（例如步行或公交）的行程的每个 路段都被视为一个步骤，而该出行方式的各个路线则位于子步骤中。相比之下，在 Routes API 中，所有类型的出行方式的步骤都是一致的导航说明 。因此，每条导航说明都是一个步骤。 对于一种出行方式中的多个步骤，Routes API 提供了 元数据，其中包含该出行方式的步骤摘要，位于 `stepsOverview` 中。如需请求此元数据，请使用 `routes.legs.stepsOverview` 字段掩码。 了解详情。
transit_routing_preference transitRoutingPreference 了解详情
units units 了解详情
waypoints intermediates 移除了对 编码多段线 的支持。
航点的 optimize=true "optimizeWaypointOrder": "true" 了解详情

响应参数转换

路线或距离矩阵参数 Routes API 参数 备注
copyrights

未包含在响应中。向用户显示结果时，您必须添加以下 声明：

Powered by Google, ©YEAR Google

例如：

Powered by Google, ©2022 Google
distance distanceMeters 距离仅以米为单位。
duration_in_traffic duration 已在 Routes API 中移除，请改用 duration。
status 无法使用。请使用 HTTP 响应代码来处理 API 报告的错误。如需了解详情，请参阅处理请求错误 。
geocoded_waypoints geocoding_results 仅支持计算路线。仅包含指定为地址的航点的地理编码响应信息。
bounds viewport
legs.end_address 无法使用。

请使用地点 ID而不是坐标来实现高精度路线规划。地点 ID 包含将路线对齐到正确接入点的数据。

  • 如果您从地址开始：请使用地点自动补全或Geocoding API将其解析为地点 ID。
  • 如果您从坐标开始：请考虑使用搜索目的地来提供更有意义的位置。仅从坐标获取地址可能很复杂，并导致对齐不正确。Routes API 不会将坐标反向地理编码为地址。
legs.start_address 无法使用。
overview_polyline 多段线
summary description
waypoint_order optimizedIntermediateWaypointIndex