Directions API 快速参考

Directions API(旧版)是一项网络服务,可计算不同位置之间的驾车、步行、骑车和公交路线,包括包含航点的多段路线,并以 JSON 或 XML 格式返回路线、路段和步骤。它处于“旧版”状态:自 2026 年 10 月起,无法为新的 Google Cloud 项目启用;请迁移到 Routes API。

Directions API:关键信息

  • 产品:Directions API
  • 别名:Directions API(旧版)
  • 类别:路线
  • 平台:Web 服务 (REST)
  • 运行位置:服务器(后端代码)
  • 发布阶段:GA
  • 生命周期:旧版
  • 替代产品:Routes API
  • 概览:Directions API 概览
  • 适用区域:全球。覆盖范围因地区和出行方式而异(公交路线取决于公交服务提供商提供的数据)。(覆盖范围详情)

Directions API:何时使用

在以下情况下使用 Directions API:

  • 您维护着一个已启用 Directions API(旧版)并调用 maps/api/directions 的现有 Google Cloud 项目。
  • 您需要在现有项目中获取驾车、步行、骑行或公交(仅限非公交模式的航点)的服务器端路线,格式为 JSON 或 XML。

在以下情况下,请勿使用 Directions API:

  • 您正在启动一个新的 Google Cloud 项目;自 2026 年 10 月起,新项目将无法启用 Directions API(旧版)。请改用 Routes API。
  • 您需要新的路由功能和更高的性能。请改用 Routes API。
  • 您需要在一个请求中获取多个出发地和目的地之间的行程时间和距离。请改用 Routes API。

Directions API:设置

Directions API:常见错误

  • 问题:如果项目未启用旧版 API,则向 Directions API(旧版)发出的请求会失败,并显示 LegacyApiNotActivatedMapError。解决方法:如果您是应用的所有者,请迁移到 Routes API。在迁移或等待应用更新期间,作为短期解决方案,您可以填写旧版 API 启用表单来启用旧版 API。请参阅 /maps/legacy。
  • 问题:在航点上使用 via: 前缀会使其成为严格的经过点,这可能会导致严重绕行或 ZERO_RESULTS 状态。修正:除非需要严格的经停点,否则请使用经停航点(不带 via: 前缀)。请参阅 /maps/documentation/directions/get-directions。
  • 问题:如果请求包含 11 到 25 个航点、optimize:true、考虑路况的行程时长 (duration_in_traffic) 或 side_of_road 或 heading 位置修饰符,则会按价格较高的高级路线 (Pro) SKU 计费。解决方法:仅在需要时使用这些功能;将航点数量保持在 10 个或更少,并省略 optimize:true、departure_time(驾车)、side_of_road 和 heading,以继续使用 Essentials SKU。请参阅 /maps/billing-and-pricing/sku-details/legacy#directions-advanced-pro-sku。
  • 问题:对于驾车路线,departure_time 不能是过去的时间(请求会失败并返回 INVALID_REQUEST)。如果没有 departure_time,路线和时长会使用与时间无关的平均路况,并且不会返回 duration_in_traffic。解决方法:将 departure_time 设置为 now 或未来的某个时间,并使用 mode=driving 获取 duration_in_traffic。返回 duration_in_traffic 的请求按“高级路线 (Pro)”SKU 结算。请参阅 /maps/documentation/directions/get-directions。