开发人员指南

Google Maps Distance Matrix API 是一项为起点和目的地矩阵提供行程距离和时间的服务。

该服务还作为客户端 Google Maps JavaScript API 的一部分提供，或者在服务器端与 Java Client、Python Client、Go Client 以及 Node.js Client for Google Maps Services 配合使用。注：无论服务使用方式如何，均执行相同的每日使用限额。每日元素数量按客户端与服务器端查询次数之和计算。

本文档的适用对象是想要在其中一个 Google Maps API 提供的地图内计算若干点之间行程距离和时间的开发者。它介绍了 API 使用方法，并提供了有关可用参数的参考资料。

简介

Google Maps Distance Matrix API 返回的信息基于 Google Maps API 计算的起点和终点之间的推荐路线，由多个行组成，这些行包含每一对起点和终点的 duration 值和 distance 值。

该服务不返回详细的路线信息。可通过向 Google Maps Directions API 传递所需单个起点和目的地来获得路线信息。

在开始使用 Distance Matrix API 进行开发前，请查看身份验证要求（需要 API 密钥）和 API 使用限额。

距离矩阵请求

Google Maps Distance Matrix API 请求使用以下格式：

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

其中 outputFormat 可以是以下值之一：

• json（推荐），表示以 JavaScript 对象标记 (JSON) 格式输出；或
• xml，表示以 XML 格式输出。

注：网址必须编码正确方有效，并且对于所有网络服务，均有 8192 字符数限制。请在构建网址时注意这一限制。请注意，不同的浏览器、代理和服务器可能同样具有不同的 URL 字符限制。

HTTPS 或 HTTP

安全性很重要，建议尽可能使用 HTTPS，对于请求中包含用户位置等敏感用户数据的应用，更须如此。使用 HTTPS 加密可提高应用的安全性及其抵御窥探或篡改的能力。

如果 HTTPS 不可行，需要通过 HTTP 访问 Google Maps Distance Matrix API，请使用：

http://maps.googleapis.com/maps/api/distancematrix/outputFormat?parameters

请求参数

某些参数是必备参数，其他则是可选参数。依照 URL 的标准，所有参数都使用“与”字符 (&) 分隔。

必填参数

• origins — 用于计算行程距离和时间的起点。可以地址、纬度/经度坐标或地点 ID 形式提供一个或多个以管道字符 (|) 分隔的位置：
  • 如果传递的是地址，该服务将对字符串进行地理编码，并将其转换为纬度/经度坐标以计算距离。该坐标可能不同于 Google Maps Geocoding API 返回的值，例如可能是建筑入口而不是其中心。

    origins=Bobcaygeon+ON|24+Sussex+Drive+Ottawa+ON

  • 如果传递的是纬度/经度坐标，它们将不加更改地直接用于计算距离。确保纬度值与经度值之间不存在空格。

    origins=41.43206,-81.38992|-33.86748,151.20699

  • 如果提供的是地点 ID，必须为其添加 place_id: 前缀。只有当请求包括 API 密钥或 Google Maps APIs Premium Plan 客户端 ID 时，才能指定地点 ID。可以从 Google Maps Geocoding API 和 Google Places API（包括地点自动填充）检索地点 ID。如需查看使用来自“地点自动完成”的地点 ID 的示例，请参阅地点自动完成和路线。如需了解更多有关地点 ID 的内容，请参阅地点 ID 概览。

    origins=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

  • 或者，也可以提供一组使用编码多段线算法的编码坐标。这在起点数量庞大时特别有帮助，因为使用编码多段线可大幅缩短网址。
    • 编码多段线必须添加 enc: 前缀并后跟冒号 (:)。例如：origins=enc:gfo}EtohhU:
    • 还可使用管道符号 (|) 分隔来加入多个编码多段线。例如：origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
• destinations — 一个或多个用作终点来计算行程距离和时间的位置。destinations 参数的选项与上述 origins 参数相同。
• key – 您的应用的 API 密钥。此密钥可以标识您的应用，以便进行配额管理。了解如何获取密钥。

  注：Google Maps APIs Premium Plan 客户可以在 Distance Matrix 请求中使用 API 密钥或有效的客户端 ID 和数字签名。获取有关 Premium Plan 客户身份验证参数的更多信息。

下例使用纬度/经度坐标来指定终点坐标：

https://maps.googleapis.com/maps/api/distancematrix/json?units=imperial&origins=40.6655101,-73.89188969999998&destinations=40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626%7C40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626&key=YOUR_API_KEY

下例展示的是使用编码多段线的同一请求：

https://maps.googleapis.com/maps/api/distancematrix/json?units=imperial&origins=40.6655101,-73.89188969999998&destinations=enc:_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV:&key=YOUR_API_KEY

可选参数

• mode（默认为 driving）– 指定在计算距离时使用的交通模式。本文档的出行模式部分规定了有效值和其他请求详情。
• language – 返回结果时使用的语言。
  • 请参阅支持的语言列表。Google 会经常更新支持的语言，所以此列表可能并不详尽。
  • 如果未提供 language，API 会按照 Accept-Language 标头中的指定尝试使用首选语言，或发出请求的网域的当地语言。
  • API 会尽力提供用户和当地人都能看懂的街道地址。为实现这一目标，它会以当地语言返回街道地址，然后在必要时按照首选语言将其直译为用户能看懂的文字。所有其他地址均以首选语言返回。地址部分均以同一语言返回，该语言是从第一部分选择的语言。
  • 如果名称在首选语言中没有对应项，API 会使用最接近的匹配项。
  • 首选语言对 API 选择返回的结果集以及结果的返回顺序影响较小。地理编码器对缩写词的解读因语言而异，例如街道类型的缩写词，或者在一种语言中有效但在其他语言中无效的同义词。例如，在匈牙利语中，utca 和 tér 是街道的同义词。
• avoid – 引入对路线的限制。本文档的限制部分规定了有效值。只能指定一个限制。
• units – 指定以文本形式表示距离时使用的单位制。如需了解详细信息，请参阅本文档的单位制部分。
• arrival_time – 指定所需的公共交通请求到达时间，以协调世界时 1970 年 1 月 1 日午夜以来的秒数表示。可以指定 departure_time 或 arrival_time 之一，但不能同时指定这两者。请注意，arrival_time 必须指定为整数。
• departure_time – 所需的出发时间。可以将该时间指定为一个整数，以协调世界时 1970 年 1 月 1 日午夜以来的秒数表示。此外，还可以指定 now 值，该值将出发时间设置为当前时间（修正为最接近的秒）。可在两种情况下指定出发时间：
  • 对于出行模式为公共交通的请求：作为可选步骤，您可以指定 departure_time 或 arrival_time 之一。如果两个时间均未指定，则 departure_time 默认使用 now 值（即，出发时间默认为当前时间）。
  • 对于出行模式为驾车的请求：您可以指定 departure_time 以获得考虑了交通状况因素的路线和驾行持续时间（响应字段：duration_in_traffic）。只有在请求包含有效的 API 密钥，或者有效的 Google Maps APIs Premium Plan 客户 ID 和签名时，此选项才可用。departure_time 必须设置为当前时间或未来的某个时间，而不能是过去的时间。

    注：mode=driving 时指定 departure_time 的 Distance Matrix 请求有每个请求 100 个元素的限额。“起点”数量与“终点”数量的乘积便是元素数量。

• traffic_model（默认为 best_guess）– 指定在计算交通时间时使用的假设。此设置影响响应中 duration_in_traffic 字段中返回的值，该字段包含根据历史平均值预测的交通时间。只能为出行模式为 driving 并且包括 departure_time 的请求指定 traffic_model 参数，并且只能在请求包括 API 密钥或 Google Maps APIs Premium Plan 客户端 ID 时进行指定。该参数的可用值如下：
  • best_guess（默认值）表示返回的 duration_in_traffic 应为在同时考虑已知历史交通状况和实时交通状况的情况下对出行时间做出的最佳估计。departure_time 与当前时间越接近，实时交通状况就越重要。
  • pessimistic 表示返回的 duration_in_traffic 应在大多数日期长于实际出行时间，但在交通状况特别糟糕的日期，可能偶尔会发生超过该值的情况。
  • optimistic 表示返回的 duration_in_traffic 应在大多数日期短于实际出行时间，但在交通状况特别理想的日期，可能偶尔会发生小于该值的情况。
• transit_mode – 指定一个或多个首选公共交通模式。只能为 mode 是 transit 的请求指定该参数。该参数支持下列自变量：
  • bus 表示计算的路线应首选公共汽车出行。
  • subway 表示计算的路线应首选地铁出行。
  • train 表示计算的路线应首选火车出行。
  • tram 表示计算的路线应首选有轨电车和轻轨出行。
  • rail 表示计算的路线应首选火车、有轨电车、轻轨和地铁出行。它相当于 transit_mode=train|tram|subway。
• transit_routing_preference – 指定公共交通请求首选项。可以利用该参数影响返回的选项，而不是接受 API 选择的默认最佳路线。只能为 mode 是 transit 的请求指定该参数。该参数支持下列自变量：
  • less_walking 表示计算的路线应首选步行距离有限的路线
  • fewer_transfers 表示计算的路线应首选换乘次数有限的路线

出行模式

计算距离时，您可以指定要使用的交通 mode。默认情况下计算的是驾车模式的距离。支持下列出行模式：

• driving（默认值）表示使用道路网计算距离。
• walking 请求计算经由步道和人行道（如有）的步行距离。
• bicycling 请求计算经由自行车道和首选街道（如有）的骑行距离。
• transit 请求计算经由公共交通路线（如有）的距离。只有当请求包括 API 密钥或 Google Maps APIs Premium Plan 客户端 ID 时，才能指定该值。如果将该模式设置为 transit，作为可选步骤，可以指定 departure_time 或 arrival_time。如果两个时间均未指定，则 departure_time 默认使用 now 值（即，出发时间默认为当前时间）。作为可选步骤，您还可提供 transit_mode 和/或 transit_routing_preference。

* 注：有时，步行路线和骑行路线可能均不包括明确的步道或自行车道，因此这些响应将在您必须向用户显示的返回结果中返回 warnings。

限制

计算的距离可以遵从特定限制。利用 avoid 参数来表示限制，该参数的自变量表示需要避开的限制。支持下列限制：

• avoid=tolls
• avoid=highways
• avoid=ferries
• avoid=indoor

*注：添加限制不会将包括受限特征的路线排除在外，其作用仅仅是通过影响结果来获得更有利的路线。

单位制

距离矩阵结果在 distance 字段内包含有 text，用于指示所计算路线的距离。可指定要使用的单位制：

• units=metric（默认值）返回以公里和米为单位的距离
• units=imperial 返回以英里和英尺为单位的距离

*注：此单位制设置只影响显示在 distance 字段内的 text。distance 字段还包含始终以米表示的 values。

距离矩阵响应

对 Google Maps Distance Matrix API 查询的响应以 URL 请求路径中 output 标志指示的格式返回。

以下显示了两个示例 HTTP 请求，请求计算从加拿大不列颠哥伦比亚省温哥华和美国华盛顿州西雅图至美国加利福尼亚州旧金山和加拿大不列颠哥伦比亚省维多利亚的距离和持续时间。

此请求演示了如何使用 JSON output 标志：

https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver+BC|Seattle&destinations=San+Francisco|Victoria+BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY

此请求演示了如何使用 XML output 标志：

https://maps.googleapis.com/maps/api/distancematrix/xml?origins=Vancouver+BC|Seattle&destinations=San+Francisco|Vancouver+BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY

此请求将返回四个元素 - 两个起点乘以两个目的地：

温哥华至旧金山	温哥华至维多利亚
西雅图至旧金山	西雅图至维多利亚

结果以行的形式返回，每一行都包含一个与各目的地配对的起点。

试一试！点击此处，在您的浏览器中发送示例请求。（如果提示您选择用于打开该文件的应用，可以选择您的浏览器或您最喜欢的文本编辑器。）

点击下面的选项卡，查看 JSON 和 XML 响应示例。

JSON

{
  "status": "OK",
  "origin_addresses": [ "Vancouver, BC, Canada", "Seattle, État de Washington, États-Unis" ],
  "destination_addresses": [ "San Francisco, Californie, États-Unis", "Victoria, BC, Canada" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 340110,
        "text": "3 jours 22 heures"
      },
      "distance": {
        "value": 1734542,
        "text": "1 735 km"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 24487,
        "text": "6 heures 48 minutes"
      },
      "distance": {
        "value": 129324,
        "text": "129 km"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 288834,
        "text": "3 jours 8 heures"
      },
      "distance": {
        "value": 1489604,
        "text": "1 490 km"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 14388,
        "text": "4 heures 0 minutes"
      },
      "distance": {
        "value": 135822,
        "text": "136 km"
      }
    } ]
  } ]
}

请注意，如果您想从结果中提取值，通常需要对这些结果进行解析。JSON 的解析相对容易。请参阅解析 JSON，了解一些建议的设计模式。

XML

<?xml version="1.0" encoding="UTF-8"?>
<DistanceMatrixResponse>
 <status>OK</status>
 <origin_address>Vancouver, BC, Canada</origin_address>
 <origin_address>Seattle, État de Washington, États-Unis</origin_address>
 <destination_address>San Francisco, Californie, États-Unis</destination_address>
 <destination_address>Victoria, BC, Canada</destination_address>
 <row>
  <element>
   <status>OK</status>
   <duration>
    <value>340110</value>
    <text>3 jours 22 heures</text>
   </duration>
   <distance>
    <value>1734542</value>
    <text>1 735 km</text>
   </distance>
  </element>
  <element>
   <status>OK</status>
   <duration>
    <value>24487</value>
    <text>6 heures 48 minutes</text>
   </duration>
   <distance>
    <value>129324</value>
    <text>129 km</text>
   </distance>
  </element>
 </row>
 <row>
  <element>
   <status>OK</status>
   <duration>
    <value>288834</value>
    <text>3 jours 8 heures</text>
   </duration>
   <distance>
    <value>1489604</value>
    <text>1 490 km</text>
   </distance>
  </element>
  <element>
   <status>OK</status>
   <duration>
    <value>14388</value>
    <text>4 heures 0 minutes</text>
   </duration>
   <distance>
    <value>135822</value>
    <text>136 km</text>
   </distance>
  </element>
 </row>
</DistanceMatrixResponse>

除非出于某种原因，您的服务要求使用 xml，否则我们建议您使用 json 作为首选输出标志。处理 XML 树时应小心谨慎，以便引用正确的节点和元素。如需了解输出处理的推荐设计模式，请参阅使用 XPath 解析 XML。

本文档的其余部分将使用 JSON 语法。

距离矩阵响应元素

距离矩阵响应包含下列根元素：

• status 包含请求的元数据。请参阅下面的状态代码。
• origin_addresses 包含 API 根据您的原始请求返回的地址数组。这些地址由地理编码器设置格式，并按照随请求传递的 language 参数接受本地化处理。
• destination_addresses 包含 API 根据您的原始请求返回的地址数组。与 origin_addresses 一样，这些地址也会在适当情况下接受本地化处理。
• rows 包含 elements 数组，其中的每个元素又包含 status 元素、duration 元素和 distance 元素。

状态代码

响应对象中的 status 字段包含请求的状态，并且可能包含有用的调试信息。Distance Matrix API 会返回一个顶级状态字段，包含有关一般意义上请求的信息；还会返回与每个元素字段对应的状态字段，包含有关特定起点-目的地配对的信息。

顶级状态代码

• OK 表示响应包含有效的 result。
• INVALID_REQUEST 表示提供的请求无效。
• MAX_ELEMENTS_EXCEEDED 表示起点与目的地的乘积超过了每次查询限制。
• OVER_QUERY_LIMIT 表示服务在允许的时段内从您的应用收到的请求数量过多。
• REQUEST_DENIED 表示服务拒绝您的应用使用 Distance Matrix 服务。
• UNKNOWN_ERROR 表示由于服务器发生错误而无法处理 Distance Matrix 请求。如果您重试一次，请求可能会成功

元素级状态代码

• OK 表示响应包含有效的 result。
• NOT_FOUND 表示无法对该配对的起点和/或目的地进行地理编码。
• ZERO_RESULTS 表示在起点与目的地之间未找到路线。

错误消息

如果顶级状态代码不是 OK，在 Distance Matrix 响应对象中可能会包含附加的 error_message 字段。此字段更详细地说明了给定状态代码背后的原因。

注：此字段不保证始终出现，并且其内容可能会更改。

行

当 Google Maps Distance Matrix API 返回结果时，会将这些结果放在一个 JSON rows 数组中。即使没有返回任何结果（例如，如果起点和/或目的地不存在），它仍然会返回一个空的数组。XML 响应包含零个或更多个 <row> 元素。

行根据请求的 origin 参数中的值进行排序。每一行都对应一个起点，并且该行中的每一个 element 都对应起点与 destination 值的配对。

每个 row 数组都包含一个或多个 element 条目，而其中的每个条目又包含某个起点-目的地配对的信息。

元素

element 条目中返回有关每个起点-目的地配对的信息。element 包含下列字段：

• status：有关可能的状态代码列表，请参阅状态代码
• duration：此路线所需的行程时间，以 text 表示，单位为秒（value 字段）。文本表示将按照查询的 language 参数接受本地化处理。

• duration_in_traffic：走完该路线所需的时间，根据当前和历史交通状况计算。请参阅 traffic_model 请求参数，了解您可以利用哪些选项来请求以乐观估计、悲观估计或最佳猜测估计作为返回值。持续时间以秒数（value 字段）和 text 形式表示。文本表示将按照查询的 language 参数接受本地化处理。只有在满足所有下列条件时，才会返回交通持续时间：

  • 请求包括 departure_time 参数
  • 请求包含有效的 API 密钥，或者有效的 Google Maps APIs Premium Plan 客户 ID 和签名
  • 可以获得所请求路线的交通状况
  • mode 参数设置为 driving
• distance：该路线的总距离，以米数 (value) 和 text 形式表示。文本值使用的单位制通过原始请求的 unit 参数或起点的地区指定。
• fare：若存在，则包含该路线的总票价（即总票费）。只会为公共交通请求返回此属性，并且只会为提供票价信息的公共交通提供商返回此属性。这些信息包括：
  • currency：ISO 4217 币种代码，表示票价所采用的币种
  • value：总票价（以上面指定的币种为单位）
  • text：总票价金额，设置为所请求语言的格式

以下是一个包含票价信息的 element 示例：

{
  "status": "OK",
  "duration": {
    "value": 340110,
    "text": "3 jours 22 heures"
  },
  "distance": {
    "value": 1734542,
    "text": "1 735 km"
  }
  "fare" : {
    "currency" : "USD",
    "value" : 6,
    "text" : "$6.00"
  },
}

sensor 参数

Google Maps API 之前要求您将 sensor 参数包括在内，以指示您的应用是否使用传感器来确定用户的位置。但该参数现在不再是必填项。