通知：Google Maps Platform 即将推出全新基本地图样式。此次地图样式更新包括全新默认调色板、经过现代化改进的图钉，以及地图体验和易用性方面的改进。所有地图样式将于 2025 年 3 月自动更新。如需详细了解适用范围以及如何提前选择启用，请参阅全新 Google Maps Platform 地图样式。

此页面由 Cloud Translation API 翻译。

Distance Matrix

DistanceMatrixService 类

google.maps.DistanceMatrixService 类

一种服务，用于计算多个起点和终点间的距离。

通过调用 const {DistanceMatrixService} = await google.maps.importLibrary("routes") 进行访问。请参阅 Maps JavaScript API 中的库。

构造函数
`DistanceMatrixService`	`DistanceMatrixService()` 参数：无创建一个新的 `DistanceMatrixService` 实例，用于将距离矩阵查询发送到 Google 服务器。

方法
`getDistanceMatrix`	`getDistanceMatrix(request[, callback])` 参数： `request`：`DistanceMatrixRequest` `callback`：`function(DistanceMatrixResponse optional, DistanceMatrixStatus): void optional` 返回值： `Promise<DistanceMatrixResponse>` 用于发出距离矩阵请求。

DistanceMatrixRequest 接口

google.maps.DistanceMatrixRequest 接口

由 DistanceMatrixService 发送的距离矩阵查询，其中包含出发地和目的地位置的数组，以及用于计算指标的各种选项。

属性
`destinations`	类型： `Array<string\|LatLng\|LatLngLiteral\|Place>` 一个数组，其中包含目的地地址字符串、`LatLng` 或 `Place` 对象，用于计算距离和时间。必填。
`origins`	类型： `Array<string\|LatLng\|LatLngLiteral\|Place>` 一个数组，其中包含出发地地址字符串、`LatLng` 或 `Place` 对象，用于计算距离和时间。必填。
`travelMode`	类型： `TravelMode` 请求的路线类型。必填。
`avoidFerries optional`	类型： `boolean optional` 如果为 `true`，则指示距离矩阵服务尽可能避开渡轮。可选。
`avoidHighways optional`	类型： `boolean optional` 如果为 `true`，则指示距离矩阵服务尽可能避开高速公路。可选。
`avoidTolls optional`	类型： `boolean optional` 如果为 `true`，则指示距离矩阵服务尽可能避开收费道路。可选。
`drivingOptions optional`	类型： `DrivingOptions optional` 仅适用于 `travelMode` 为 `DRIVING` 的请求的设置。此对象对其他出行方式没有影响。
`language optional`	类型： `string optional` 应返回结果的语言的语言标识符（如果可能）。请参阅支持的语言列表。
`region optional`	类型： `string optional` 用作地址解析请求偏向的区域代码。地区代码接受 ccTLD（“顶级域名”）双字符值。多数 ccTLD 代码都与 ISO 3166-1 代码相同，但也有一些需要注意的例外情况。例如，英国的 ccTLD 为“uk”（`.co.uk`），但其 ISO 3166-1 代码为“gb”（从技术层面来说，适用于“大不列颠及北爱尔兰联合王国”实体）。
`transitOptions optional`	类型： `TransitOptions optional` 仅适用于 `travelMode` 为 TRANSIT 的请求的设置。此对象对其他出行方式没有影响。
`unitSystem optional`	类型： `UnitSystem optional` 显示距离时要使用的首选单位制。可选；默认使用公制。

DistanceMatrixResponse 接口

google.maps.DistanceMatrixResponse 接口

对 DistanceMatrixService 请求的响应，其中包含格式化的起始地址和目的地地址，以及一系列 DistanceMatrixResponseRow（每个相应起始地址对应一个）。

属性
`destinationAddresses`	类型： `Array<string>` 经过格式化的终点地址。
`originAddresses`	类型： `Array<string>` 经过格式化的起点地址。
`rows`	类型： `Array<DistanceMatrixResponseRow>` 矩阵的各行，对应起点地址。

DistanceMatrixResponseRow 接口

google.maps.DistanceMatrixResponseRow 接口

对 DistanceMatrixService 请求的响应中的一行，由一系列 DistanceMatrixResponseElement 组成，每个相应目的地地址对应一个 DistanceMatrixResponseElement。

属性
`elements`	类型： `Array<DistanceMatrixResponseElement>` 该行的各元素，对应终点地址。

DistanceMatrixResponseElement 接口

google.maps.DistanceMatrixResponseElement 接口

对 DistanceMatrixService 请求的响应的单个元素，其中包含从一个出发地到一个目的地的时长和距离。

属性
`distance`	类型： `Distance` 该起点-终点对的距离。此属性可能未定义，因为距离可能未知。
`duration`	类型： `Duration` 该起点-终点对的时长。此属性可能未定义，因为持续时间可能未知。
`duration_in_traffic`	类型： `Duration` 此起点-目的地配对的时长，考虑了 `trafficModel` 属性所指示的交通状况。此属性可能是 `undefined`，因为时长可能未知。仅当在发出请求时定义了 `drivingOptions` 时，高级支持服务方案客户才能使用此功能。
`fare`	类型： `TransitFare` 此始发地和目的地的总费用。仅适用于公交请求。
`status`	类型： `DistanceMatrixElementStatus` 该特定起点-终点对的状态。

DistanceMatrixStatus 常量

google.maps.DistanceMatrixStatus 常量

DistanceMatrixService 在完成距离矩阵请求后通常返回的有关请求的顶级状态。您可以按值指定这些参数，也可以使用常量的名称指定这些参数。例如 'OK' 或 google.maps.DistanceMatrixStatus.OK。

通过调用 const {DistanceMatrixStatus} = await google.maps.importLibrary("routes") 进行访问。请参阅 Maps JavaScript API 中的库。

常量
`INVALID_REQUEST`	提供的请求无效。
`MAX_DIMENSIONS_EXCEEDED`	该请求包含的起点或终点的数量超过了 25 个。
`MAX_ELEMENTS_EXCEEDED`	这些起点和终点所产生的结果数量超出了每条查询的限制。
`OK`	该响应包含有效的结果。
`OVER_QUERY_LIMIT`	在允许的时间段内请求的元素数量过多。如果您在过段时间后重试，请求应该会成功。
`REQUEST_DENIED`	该服务拒绝您的网页使用距离矩阵服务。
`UNKNOWN_ERROR`	由于服务器错误，系统无法处理距离矩阵请求。如果您再试一次，该请求可能会成功。

DistanceMatrixElementStatus 常量

google.maps.DistanceMatrixElementStatus 常量

DistanceMatrixService 在完成距离矩阵请求后返回的有关特定出发地-目的地配对的元素级状态。这些值以字符串的形式指定，例如 'OK'。

通过调用 const {DistanceMatrixElementStatus} = await google.maps.importLibrary("routes") 进行访问。请参阅 Maps JavaScript API 中的库。

常量
`NOT_FOUND`	无法对该配对的起点和/或终点进行地址解析。
`OK`	该响应包含有效的结果。
`ZERO_RESULTS`	在起点和终点之间找不到任何路线。