Google Maps Distance Matrix API

简介

Google Maps Distance Matrix API 是一项为起点和目的地矩阵提供行程距离和时间的服务。返回的信息基于 Google Maps API 计算的起点和终点之间的推荐路线，由多个行组成，这些行包含每一对起点和终点的 duration 值和 distance 值。

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

获取密钥 使用限制

受众

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

距离矩阵请求

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

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

对于请求中包含用户位置等敏感用户数据的应用，建议使用 HTTPS。

output 可以采用以下格式之一：

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

Google Maps Distance Matrix API URL 在接受 URL 编码后被限制在大约 2000 个字符。由于一些 Google Maps Distance Matrix API 服务 URL 可能涉及许多位置，请在构建 URL 时注意这一限制。请注意，不同的浏览器、代理和服务器可能同样具有不同的 URL 字符限制。

请求参数

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

必填参数

• origins – 一个或多个使用管道符号 (|) 分隔、作为距离和时间计算起点的地址和/或纬度/经度文本值。如果您传递字符串形式的地址，该服务将对字符串进行地理编码，并将其转换为纬度/经度坐标以计算距离。如果您传递坐标，请确保纬度值与经度值之间不存在空格。

  origins=Bobcaygeon+ON|41.43206,-81.38992

• destinations – 一个或多个使用管道符号 (|) 分隔、作为距离和时间计算终点的地址和/或纬度/经度文本值。如果您传递字符串形式的地址，该服务将对字符串进行地理编码，并将其转换为纬度/经度坐标以计算距离。如果您传递坐标，请确保纬度值与经度值之间不存在空格。

  destinations=Darling+Harbour+NSW+Australia|24+Sussex+Drive+Ottawa+ON|Capitola+CA

• key – 您的应用的 API 密钥。此密钥可以标识您的应用，以便进行配额管理。了解如何获取密钥。

Google Maps API for Work 用户必须在其距离矩阵请求中包含有效的 client 和 signature 参数。如需了解详细信息，请参阅 Google Maps API for Work Web Services 一章。

可选参数

• mode（默认为 driving）– 指定在计算距离时使用的交通模式。本文档的出行模式部分规定了有效值和其他请求详情。
• language – 返回结果时使用的语言。请参阅支持的区域语言列表。请注意，我们会经常更新支持的语言，因此，此列表可能并不全面。
• 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 API for Work 客户 ID 和签名时，此选项才可用。departure_time 必须设置为当前时间或未来的某个时间，而不能是过去的时间。
• traffic_model（默认为 best_guess）– 指定在计算交通时间时使用的假设。此设置影响响应中 duration_in_traffic 字段中返回的值，该字段包含根据历史平均值预测的交通时间。只能为出行模式为 driving、并且包括 departure_time 的请求指定 traffic_model 参数，并且只能在请求包括 API 密钥或 Google Maps API for Work 客户 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 表示计算的路线应首选换乘次数有限的路线

* 注：包括 departure_time 参数的请求的元素数量被限定为 100。

出行模式

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

• driving（默认值）表示使用道路网计算距离。
• walking 请求计算经由步道和人行道（如有）的步行距离。
• bicycling 请求计算经由自行车道和首选街道（如有）的骑行距离。
• transit 请求计算经由公共交通路线（如有）的距离。只有在请求包括 API 密钥或 Google Maps API for Work 客户 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 响应示例。

{
  "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"
      }
    } ]
  } ]
}

<?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>

距离矩阵响应元素

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

• 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 API for Work 客户 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 参数包括在内，以指示您的应用是否使用传感器来确定用户的位置。但该参数现在不再是必填项。