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-backend.googleapis.com - 身份验证:API 密钥
- 开始使用:设置 Directions API
- 参考文档:Directions API 参考文档
- 价格:Directions API 用量和结算
- 政策:Directions 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。