Distance Matrix API 请求和响应

简介

Distance Matrix API 的请求采用以下形式：

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

其中，outputFormat 可以是以下任一值：

• json（推荐）表示以 JavaScript 对象表示法 (JSON) 格式输出。
• xml 表示以 XML 格式输出。

某些参数是必需参数，其他则是可选参数。依照网址的标准，所有参数都使用“与”符号 (&) 分隔。所有预留字符（例如加号“+”）都必须进行网址编码。下面列出了参数及其可能的值。

必需参数

• 目的地

  一个或多个用作计算行程距离和时间的终点的位置。目的地参数的选项与来源参数的选项相同。

• 来源

  用于计算行程距离和时间的出发地。您可以提供一个或多个位置，并使用竖线字符 (|) 分隔，位置的形式可以是地点 ID、地址或纬度/经度坐标：

  • 地点 ID：如果您提供地点 ID，则必须在前面加上 place_id: 前缀。
  • 地址：如果您传递地址，该服务会对字符串进行地理编码，并将其转换为纬度/经度坐标以计算距离。此坐标可能与 Geocoding API 返回的坐标不同，例如，此坐标可能是建筑物的入口而不是中心。
    注意：与使用地址或纬度/经度坐标相比，使用地点 ID 是首选方式。使用坐标始终会导致点被贴靠到距离这些坐标最近的道路上，而这可能不是房产的入口点，甚至不是一条能够快速或安全地到达目的地的道路。使用地址会提供到建筑物中心的距离，而不是到建筑物入口的距离。
  • 坐标：如果您传递纬度/经度坐标，它们将对准最近的道路。建议传递地点 ID。如果您确实要传递坐标，请确保纬度和经度值之间没有空格。
  • Plus Code 的格式必须为全局代码或混合代码。按如下格式设置 Plus Codes（加号经网址转义为 %2B，空格经网址转义为 %20）：
    • 全局代码是包含 4 个字符的区号和至少包含 6 个字符的区域代码（849VCWC8+R9 编码为 849VCWC8%2BR9）。
    • 混合代码是至少包含 6 个字符的区域代码，具有明确的位置信息（CWC8+R9 Mountain View, CA, USA 编码为 CWC8%2BR9%20Mountain%20View%20CA%20USA）。
  • 编码多段线：或者，您也可以使用编码多段线算法提供一组编码的坐标。如果您有大量原点，此方法尤其有用，因为使用编码的多段线时，网址会明显缩短。
    • 编码的折线必须以 enc: 为前缀，后跟英文冒号 :。例如： origins=enc:gfo}EtohhU:
    • 您还可以添加多个编码折线，并使用竖线字符 | 将它们分隔开。例如：

      origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
      

可选参数

• arrival_time

  指定公共交通路线的首选到达时间，以自世界协调时间 (UTC) 1970 年 1 月 1 日午夜起计算的秒数表示。您可以指定 departure_time 或 arrival_time，但不能同时指定这两者。 请注意，arrival_time 必须指定为整数。

• 避免

  系统可能会计算符合某些限制条件的距离。 限制通过使用 avoid 参数来指示，该参数的实参用于指示要避免的限制。支持以下限制：

  • tolls 表示计算出的路线应避开收费路段/桥梁。
  • highways 表示计算出的路线应避开高速公路。
  • ferries 表示计算出的路线应避开轮渡。
  • indoor 表示计算出的路线应避免在步行和公共交通路线中包含室内步数。

  您可以将收费站、高速公路和轮渡的任意组合作为限制条件传递给 avoid 参数，从而请求避开这些路段的路线。例如 avoid=tolls|highways|ferries。

  注意：添加限制并不会排除包含受限功能的路线，而是会使结果偏向更理想的路线。

• departure_time

  指定首选出发时间。您可以将时间指定为自世界协调时间 (UTC) 1970 年 1 月 1 日午夜以来的秒数（整数）。如果指定的 departure_time 晚于 9999-12-31T23:59:59.999999999Z，API 会将 departure_time 回退到 9999-12-31T23:59:59.999999999Z。或者，您也可以指定值“now”，这样会将出发时间设置为当前时间（精确到最近的秒）。在以下两种情况下，可以指定出发时间：

  • 对于出行方式为公交的请求：您可以选择指定 departure_time 或 arrival_time。 如果未指定任何时间，则 departure_time 默认为当前时间（即出发时间默认为当前时间）。
  • 对于出行方式为驾车的请求：您可以指定 departure_time 以接收考虑了路况信息的路线和行程时长（响应字段：duration_in_traffic）。departure_time 必须设置为当前时间或未来的某个时间。但不能是过去的时间。
  注意：如果未指定出发时间，则系统会根据道路网和与时间无关的平均路况信息来选择路线和时长。受道路网变化、平均路况信息更新以及服务的分布式性质的影响，给定请求的结果可能会随时间的推移而发生变化。此外，在时间或频率不受限制的情况下，即使两条路线几乎相同，结果还是有可能不同。
  注意：如果距离矩阵请求在 mode=driving 时指定了 departure_time，则每个请求最多只能包含 100 个元素。起点数量乘以目的地数量即为元素数量。

• language

  返回结果所用的语言。

  • 请参阅支持的语言列表。Google 会经常更新支持的语言，因此该列表可能并非详尽无遗。
  • 如果未提供 language，API 会尝试使用 Accept-Language 标头中指定的首选语言。
  • 该 API 会尽力提供用户和当地人都能看懂的街道地址。为了实现这一目标，它会返回本地语言的街道地址，并在必要时根据首选语言将地址音译为用户可读的文字。所有其他地址均以首选语言返回。地址组成部分全部以同一种语言返回，该语言是从第一个组成部分中选择的。
  • 如果首选语言中没有相应名称，API 会使用最接近的匹配项。
  • 首选语言对 API 选择返回的结果集以及返回顺序有一定影响。地理编码器会根据语言以不同的方式解读缩写，例如街道类型的缩写，或者在一种语言中有效但在另一种语言中无效的同义词。例如，utca 和 tér 是匈牙利语中“街道”的同义词。

• 模式

  在计算距离和路线时，您可以指定要使用的交通方式。默认情况下，系统会使用 DRIVING 模式。 默认情况下，系统会计算驾车路线。支持以下出行方式：

  • driving（默认）表示使用道路网的标准行车路线或距离。
  • walking - 用于请求经由步道和人行道（如有）的步行路线或距离。
  • bicycling 请求使用自行车道和首选街道（如有）的骑车路线或距离。
  • transit 请求使用公共交通路线（如有）的路线或距离。如果您将模式设置为公交，则可以选择性地指定 departure_time 或 arrival_time。如果未指定任何时间，则 departure_time 默认为当前时间（即出发时间默认为当前时间）。您还可以选择性地添加 transit_mode 和/或 transit_routing_preference。
  注意：步行和骑行路线有时可能不包含畅通无阻的步道或自行车道，因此这些路线将在返回的结果中返回警告，您必须向用户显示这些警告。
  注意：公交行程最多可查看过去 7 天或未来 100 天的行程，具体取决于数据提供商提供的公交信息是否可用。公交时刻表经常变化，可用的公交行程可能会随时间变化，并且无法保证提前很长时间预测的结果始终一致。

• 区域

  地区代码，以 ccTLD（“顶级域名”）双字符值的形式指定。多数 ccTLD 代码都与 ISO 3166-1 代码相同，但也有一些需要注意的例外情况。例如，英国的 ccTLD 为“uk”(.co.uk)，而其 ISO 3166-1 代码为“gb”（代表“大不列颠及北爱尔兰联合王国”）。

• traffic_model

  指定计算交通中的时间时要使用的假设。此设置会影响响应中返回到 duration_in_traffic 字段的值，该值包含根据历史平均数据预测的交通时间。traffic_model 参数只能针对包含 departure_time 的行车路线请求指定。此参数的可用值包括：

  • best_guess（默认）- 表示返回的 duration_in_traffic 应该是最准确的行程时间估算值（根据已知的历史路况信息和实时路况信息得出）。 departure_time 越接近当前时间，实时路况信息就越重要。
  • pessimistic 表示返回的 duration_in_traffic 在大多数日子里应该长于实际行程时间，但偶尔路况特别糟糕的时候，实际行程时间可能会超过该值。
  • optimistic 表示返回的 duration_in_traffic 在大多数日子里应该短于实际行程时间，但偶尔路况特别理想的时候，实际行程时间可能会小于该值。

  对于绝大多数使用情形，best_guess 的默认值都能提供最有用的预测结果。由于 best_guess 预测模型集成实时路况信息的方式，best_guess 行程时间预测可能短于 optimistic，也可能长于 pessimistic。

• transit_mode

  指定一种或多种首选公共交通方式。此参数只能为公共交通路线指定。该参数支持以下实参：

  • bus 表示计算出的路线应首选公交出行。
  • subway 表示计算出的路线应首选地铁出行。
  • train 表示计算出的路线应首选火车出行。
  • tram 表示计算出的路线应首选有轨电车和轻轨出行。
  • rail 表示计算出的路线应首选火车、有轨电车、轻轨和地铁出行。这等同于 transit_mode=train|tram|subway。

• transit_routing_preference

  指定公交路线的偏好设置。利用此参数，您可以自定义调整所返回的选项，而不是接受 API 选择的默认最佳路线。此参数只能为公交路线指定。该参数支持以下实参：

  • less_walking 表示计算出的路线应首选步行距离较短的路线。
  • fewer_transfers 表示计算出的路线应首选换乘次数较少的路线。

• 个单元

  指定显示结果时要使用的单位制。

  注意：此单位制设置仅影响距离字段中显示的文本。距离字段还包含始终以米为单位的值。

请求示例

此示例使用纬度/经度坐标来指定目的地坐标：

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

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626&key=YOUR_API_KEY'

此示例使用 Plus Code 指定目的地坐标：

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco
  &origins=849VCWC8%2BR9
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=849VCWC8%2BR9&destinations=San%20Francisco&key=YOUR_API_KEY'

此示例展示了使用编码折线的相同请求：

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A&key=YOUR_API_KEY'

路况信息

在满足所有以下条件（在距离矩阵响应中收到 duration_in_traffic 字段的必要条件）时会使用路况信息：

• travel mode 参数为 driving 或未指定（driving 为默认出行方式）。
• 请求包含有效的 departure_time 参数。departure_time 可设置为当前时间或未来的某个时间，而不能是过去的时间。

（可选）您可以在请求中添加 traffic_model 参数，以指定在计算交通时间时要使用的假设。

以下网址会发起距离矩阵请求，以获取马萨诸塞州波士顿或马萨诸塞州查尔斯镇与马萨诸塞州莱克星顿和马萨诸塞州康科德之间的驾车距离。该请求包含出发时间，满足在距离矩阵响应中返回 duration_in_traffic 字段的所有要求。

https://maps.googleapis.com/maps/api/distancematrix/json
  ?departure_time=now
  &destinations=Lexington%2CMA%7CConcord%2CMA
  &origins=Boston%2CMA%7CCharlestown%2CMA
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Boston%2CMA%7CCharlestown%2CMA&destinations=Lexington%2CMA%7CConcord%2CMA&departure_time=now&key=YOUR_API_KEY'

{
  "destination_addresses": ["Lexington, MA, USA", "Concord, MA, USA"],
  "origin_addresses": ["Boston, MA, USA", "Charlestown, Boston, MA, USA"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "33.3 km", "value": 33253 },
              "duration": { "text": "27 mins", "value": 1620 },
              "duration_in_traffic": { "text": "34 mins", "value": 2019 },
              "status": "OK",
            },
            {
              "distance": { "text": "41.5 km", "value": 41491 },
              "duration": { "text": "33 mins", "value": 1981 },
              "duration_in_traffic": { "text": "39 mins", "value": 2342 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "31.1 km", "value": 31100 },
              "duration": { "text": "26 mins", "value": 1543 },
              "duration_in_traffic": { "text": "29 mins", "value": 1754 },
              "status": "OK",
            },
            {
              "distance": { "text": "39.3 km", "value": 39338 },
              "duration": { "text": "32 mins", "value": 1904 },
              "duration_in_traffic": { "text": "35 mins", "value": 2077 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

 OK
 Boston, MA, USA
 Charlestown, Boston, MA, USA
 Lexington, MA, USA
 Concord, MA, USA
 
  
   OK
   
    1620
    27 mins
   
   
    33253
    33.3 km
   
   
    2018
    34 mins
   
  
  
   OK
   
    1981
    33 mins
   
   
    41491
    41.5 km
   
   
    2342
    39 mins
   
  
 
 
  
   OK
   
    1543
    26 mins
   
   
    31100
    31.1 km
   
   
    1759
    29 mins
   
  
  
   OK
   
    1904
    32 mins
   
   
    39338
    39.3 km
   
   
    2077
    35 mins
   
  
 

地理位置出价调节系数

您可以使用位置修饰符来指引司机应如何抵达特定位置，方法是使用 side_of_road 修饰符指定要使用道路的哪一侧，或指定朝向以指明正确的行驶方向。

指定计算出的路线必须经过道路的特定一侧

指定位置时，您可以使用 side_of_road: 前缀请求计算出的路线经过相应途径点偏向的道路一侧。例如，此请求将返回长路线的距离，以便车辆最终停在航点偏向的那一侧路边：

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3A37.7663444%2C-122.4412006
  &origins=37.7680296%2C-122.4375126
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=37.7680296%2C-122.4375126&destinations=side_of_road%3A37.7663444%2C-122.4412006&key=YOUR_API_KEY'

将 side_of_road: 与编码的多段线搭配使用时，调节系数会应用于多段线上的每个位置。例如，此请求中的两个目的地都使用了以下参数：

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A
  &origins=San%20Francisco%20City%20hall
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=San%20Francisco%20City%20hall&destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A&key=YOUR_API_KEY'

side_of_road: 修饰符只能在以下限制条件下使用：

• travel mode 参数为 driving 或未指定（driving 为默认出行方式）。

指定计算出的路线应具有特定的航向

指定位置时，您可以请求计算出的路线以特定朝向经过该位置。此标题使用前缀 heading=X: 指定，其中 X 是介于 0（含）到 360（不含）之间的整数度数值。航向为 0 表示正北，90 表示正东，以此类推（顺时针方向）。例如，在此请求中，计算出的路线从出发地向东行驶，然后掉头：

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=37.773245%2C-122.469502
  &origins=heading%3D90%3A37.773279%2C-122.468780
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=heading%3D90%3A37.773279%2C-122.468780&destinations=37.773245%2C-122.469502&key=YOUR_API_KEY'

heading=X: 修饰符只能在以下限制条件下使用：

• travel mode 参数为 driving、bicycling 或未指定（driving 为默认出行方式）。
• 未为同一位置指定 side_of_road 修饰符。
• 位置由纬度/经度值指定。您不得将 heading 与地址、地点 ID 或编码的折线一起使用。

距离矩阵请求和响应

以下示例 HTTP 请求请求了从加拿大不列颠哥伦比亚省温哥华和美国华盛顿州西雅图到美国加利福尼亚州旧金山以及加拿大不列颠哥伦比亚省维多利亚的距离和时长。

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco%7CVictoria%20BC
  &language=fr-FR
  &mode=bicycling
  &origins=Vancouver%20BC%7CSeattle
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver%20BC%7CSeattle&destinations=San%20Francisco%7CVictoria%20BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY'

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

结果以行的形式返回，每行包含一个出发地与每个目的地的配对。

{
  "destination_addresses":
    ["San Francisco, Californie, États-Unis", "Victoria, BC, Canada"],
  "origin_addresses":
    ["Vancouver, BC, Canada", "Seattle, Washington, États-Unis"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "1 712 km", "value": 1711765 },
              "duration": { "text": "3 jours 16 heures", "value": 318119 },
              "status": "OK",
            },
            {
              "distance": { "text": "140 km", "value": 139695 },
              "duration": { "text": "6 heures 49 minutes", "value": 24567 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "1 452 km", "value": 1451704 },
              "duration": { "text": "3 jours 2 heures", "value": 266680 },
              "status": "OK",
            },
            {
              "distance": { "text": "146 km", "value": 146500 },
              "duration": { "text": "2 heures 53 minutes", "value": 10374 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

 OK
 Vancouver, BC, Canada
 Seattle, Washington, États-Unis
 San Francisco, Californie, États-Unis
 Victoria, BC, Canada
 
  
   OK
   
    318119
    3 jours 16 heures
   
   
    1711765
    1 712 km
   
  
  
   OK
   
    24567
    6 heures 49 minutes
   
   
    139695
    140 km
   
  
 
 
  
   OK
   
    266680
    3 jours 2 heures
   
   
    1451704
    1 452 km
   
  
  
   OK
   
    10374
    2 heures 53 minutes
   
   
    146500
    146 km
   
  
 

DistanceMatrixResponse

DistanceMatrixStatus

服务返回的状态代码。

• OK 表示响应中包含有效结果。
• INVALID_REQUEST 表示提供的请求无效。
• MAX_ELEMENTS_EXCEEDED 表示出发地和目的地的乘积超出了每次查询的限制。
• MAX_DIMENSIONS_EXCEEDED 表示起点或终点数量超过了每次查询的限制。
• OVER_DAILY_LIMIT 表示以下任一情况：
  • API 密钥缺失或无效。
  • 您的账号尚未启用结算功能。
  • 超出了您设定的用量上限。
  • 提供的付款方式不再有效（例如，信用卡已过期）。
• OVER_QUERY_LIMIT 表示服务在允许的时间段内从您的应用收到的请求过多。
• REQUEST_DENIED 表示服务拒绝您的应用使用距离矩阵服务。
• UNKNOWN_ERROR 表示距离矩阵请求因服务器错误而无法得到处理。如果您重试一次，请求可能会成功。

DistanceMatrixRow

DistanceMatrixElement

Fare

相应路线的总票价。

{
  "currency" : "USD",
  "value" : 6,
  "text" : "$6.00"
}

DistanceMatrixElementStatus

• OK 表示响应中包含有效结果。
• NOT_FOUND 表示无法对该配对的出发地和/或目的地进行地理编码。
• ZERO_RESULTS 表示在出发地和目的地之间找不到路线。
• MAX_ROUTE_LENGTH_EXCEEDED 表示所请求的路线过长，无法进行处理。

TextValueObject

一个对象，包含数值及其格式化文本表示形式。