Distance Matrix API 快速参考

Distance Matrix API(旧版)是一项网络服务,可根据每对出发地和目的地之间的推荐路线,返回出发地和目的地矩阵的行程距离和时间。您可以设置出行方式(驾车、步行、骑车、公共交通)、公共交通工具、单位以及基于路况的时长的出发时间。它会返回 JSON 或 XML。

Distance Matrix API:关键信息

  • 产品:Distance Matrix API
  • 别名:Distance Matrix API(旧版)、Distance Matrix(旧版)
  • 类别:路线
  • 平台:Web 服务 (REST)
  • 运行位置:服务器(后端代码)
  • 发布阶段:GA
  • 生命周期:旧版
  • 替代产品:Routes API
  • 概览:Distance Matrix API 概览

Distance Matrix API:何时使用

在以下情况下使用 Distance Matrix API:

  • 您维护着一个已启用 Distance Matrix API(旧版)并调用 /maps/api/distancematrix 的现有项目。
  • 您需要从服务器获取多个出发地和多个目的地之间的行程距离和时间。
  • 您需要使用 departure_time 和可选的 traffic_model 来获取驾车时的路况时长。

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

  • 您要启动一个新的 Google Cloud 项目。自 2026 年 10 月起,新项目将无法启用 Distance Matrix API(旧版)。请改用 Routes API。
  • 您需要新功能或包含最多 625 个元素且具有流式响应 (computeRouteMatrix) 的路线矩阵。请改用 Routes API。
  • 您需要一条包含各点之间的步骤和多段线的完整路线,而不仅仅是距离和时长值。请改用 Routes API。

Distance Matrix API:设置

Distance Matrix API:常见错误

  • 问题:每个服务器端请求最多只能包含 100 个元素(出发地 × 目的地),且最多只能包含 25 个出发地或 25 个目的地。更大的请求会返回 MAX_ELEMENTS_EXCEEDED 或 MAX_DIMENSIONS_EXCEEDED。解决方法:将矩阵拆分为多个请求,每个请求包含不超过 100 个元素和 25 个出发地或目的地。请参阅 /maps/documentation/distance-matrix/usage-and-billing#usage-limits。
  • 问题:如果您未指定 departure_time,系统会根据与时间无关的平均路况信息来选择路线和时长,并且不会返回 duration_in_traffic。结果可能会随时间而变化。解决方法:将 departure_time 设置为 now 或使用 mode=driving 设置为未来的时间,以获取考虑路况的时长。请注意,路况请求会以较高费率结算。请参阅 /maps/documentation/distance-matrix/distance-matrix。
  • 问题:units 参数仅会更改距离字段中的文本。距离值始终以米为单位。修正:将 distance.value 读作“米”,或使用 distance.text 进行显示。请参阅 /maps/documentation/distance-matrix/distance-matrix。
  • 问题:从尚未启用 Distance Matrix API(旧版)的项目中调用该 API 会在 status 中返回 REQUEST_DENIED,并返回一个链接到 LegacyApiNotActivatedMapError 的 error_message。AI 助理通常默认生成旧版 API 代码。修复方法:迁移到 Routes API computeRouteMatrix(使用 X-Goog-FieldMask 标头)。通过表单激活旧版 API 只能作为短期措施。请参阅 /maps/legacy#LegacyApiNotActivatedMapError。