Distance Matrix 服务

概览

Google 的 Distance Matrix 服务可使用给定出行方式计算多个起点与终点之间的行程距离和行程持续时间。

该服务不返回详细的路线信息。通过将所需单个起点和终点传递给路线服务，可以获取路线信息，包括以折线形式和文本形式表示的路线。

使用限制和要求

配额

对于 Distance Matrix 服务，具有以下使用限制：

• 每个请求最多 25 个起点或 25 个终点
• 每个请求最多 100 个元素（起点乘以终点）

请求率也有相应的限制。如果在某个特定期间请求的元素过多，将返回 OVER_QUERY_LIMIT 响应代码。

Google 地图的显示

使用 Distance Matrix 服务必然要涉及到在 Google 地图上显示信息；例如，在请求并在地图上显示这些终点之前，要从其他行车时间确定某特别行车时间内的起点-终点对。禁止在不显示 Google 地图的应用中使用该服务。

距离矩阵请求

由于 Google Maps API 需要调用外部服务器，因此访问 Distance Matrix 服务是异步进行的。为此，您需要传递一个在请求完成后立即执行的回调方法，以处理结果。

您可以通过 google.maps.DistanceMatrixService 对象在您的代码内访问 Distance Matrix 服务。DistanceMatrixService.getDistanceMatrix() 方法向Distance Matrix 服务发起请求，并向其传递一个 DistanceMatrixRequest 对象字面量，后者包含起点、终点和出行方式，以及一个用于在收到响应后执行的回调方法。

var origin1 = new google.maps.LatLng(55.930385, -3.118425);
var origin2 = "Greenwich, England";
var destinationA = "Stockholm, Sweden";
var destinationB = new google.maps.LatLng(50.087692, 14.421150);

var service = new google.maps.DistanceMatrixService();
service.getDistanceMatrix(
  {
    origins: [origin1, origin2],
    destinations: [destinationA, destinationB],
    travelMode: google.maps.TravelMode.DRIVING,
    transitOptions: TransitOptions,
    drivingOptions: DrivingOptions,
    unitSystem: UnitSystem,
    avoidHighways: Boolean,
    avoidTolls: Boolean,
  }, callback);

function callback(response, status) {
  // See Parsing the Results for
  // the basics of a callback function.
}

查看示例 (distance-matrix.html)

DistanceMatrixRequest 包含以下字段：

• origins（必填）：一个数组，其中包含一个或多个计算距离和时间时所用起点的地址字符串和/或 google.maps.LatLng 对象
• destinations（必填）：一个数组，其中包含一个或多个计算距离和时间时所用终点的地址字符串和/或 google.maps.LatLng 对象
• travelMode（可选）：计算路线时所用的交通方式。请参阅出行方式部分
• transitOptions（可选）：仅适用于其中 travelMode 为 google.maps.TravelMode.TRANSIT 的请求的选项。有效值见下文公交选项部分所述
• drivingOptions（可选）：用于指定仅适用于其中 travelMode 为 google.maps.TravelMode.DRIVING 的请求的值。有效值见下文行车选项部分所述
• unitSystem（可选）：显示结果时所用的单位制。接受的值为：
  • google.maps.UnitSystem.METRIC（默认）
  • google.maps.UnitSystem.IMPERIAL
• avoidHighways（可选）：如果设置为 true，计算起点与终点之间的路线时将尽可能避免公路
• avoidTolls（可选）：如果设置为 true，计算两点之间的路线时将尽可能使用非收费路线

出行模式

计算时间和距离时，您可以指定使用哪种交通方式。目前支持以下出行方式：

• google.maps.TravelMode.BICYCLING：用于请求经过骑行道和优先街道的骑行路线（当前仅适用于美国以及加拿大某些城市）
• google.maps.TravelMode.DRIVING（默认）：表示使用道路网络的标准行车路线
• google.maps.TravelMode.TRANSIT：用于请求经过公交路线的路线只有当请求包括 API 密钥时，才能指定此选项。有关此类请求的适用选项，请参阅公交选项部分
• google.maps.TravelMode.WALKING：用于请求经过步行街和人行道的步行路线（如有）

公交选项

公交服务目前属于“实验性”服务。在此阶段中，我们会实现速率限制以防止 API 滥用。我们最终会基于 API 的公平使用对每次加载地图的总查询次数设定上限。

适用于 Distance Matrix 请求的选项会根据出行方式的不同而有所区别。在公交请求中，avoidHighways 和 avoidTolls 选项将被忽略。您可以通过 TransitOptions 对象字面量指定公交专属路线选项。

公交请求具有时效性。只有对于未来的时间才会返回计算值。

TransitOptions 对象字面量包含以下字段：

{
  arrivalTime: Date,
  departureTime: Date,
  modes: [transitMode1, transitMode2]
  routingPreference: TransitRoutePreference
}

这些字段解释如下：

• arrivalTime（可选）：用于以 Date 对象的形式指定期望到达时间。如果指定了到达时间，就会忽略出发时间
• departureTime（可选）：用于以 Date 对象的形式指定期望出发时间。如果指定了 arrivalTime，则 departureTime 将被忽略。如果未对 departureTime 或 arrivalTime指定任何值，则默认采用当前时间
• modes（可选）：一个包含一个或多个 TransitMode 对象字面量的数组。只有在请求中包含 API 密钥时才会包括该字段。每个 TransitMode 均指定一个首选的公交方式。允许使用以下值：
  • google.maps.TransitMode.BUS：表示计算的路线应首选公共汽车交通方式
  • google.maps.TransitMode.RAIL：表示计算的路线应首选火车、电车、轻轨和地铁交通方式
  • google.maps.TransitMode.SUBWAY：表示计算的路线应首选地铁交通方式
  • google.maps.TransitMode.TRAIN：表示计算的路线应首选火车交通方式
  • google.maps.TransitMode.TRAM：表示计算的路线应首选电车和轻轨交通方式
• routingPreference（可选）：用于指定公交路线首选项。通过使用此选项，您可以偏向返回的选项，而不是接受 API 选择的默认最佳路线。此字段只能在请求中包含 API 密钥时指定。允许使用以下值：
  • google.maps.TransitRoutePreference.FEWER_TRANSFERS：表示计算的路线应首选有限的转车次数
  • google.maps.TransitRoutePreference.LESS_WALKING：表示计算的路线应首选有限的步行距离

行车选项

您可以通过 DrivingOptions 对象指定行车路线的行程选项。如果您想在 DistanceMatrixRequest 中包含 drivingOptions 字段，则必须在加载 API 时提供一个 Google Maps API for Work 客户 ID。

DrivingOptions 对象包含以下字段：

{
  departureTime: Date,
  trafficModel: TrafficModel
}

这些字段解释如下：

• departureTime（drivingOptions 对象字面量必须具有此项才有效）：用于以 Date 对象指定期望出发时间。其值必须设置为当前时间或未来某个时间，而不能是过去的时间。（API 会将所有日期都转换为 UTC，以确保无论时区如何，均提供一致处理。）对于 Google Maps API for Work 客户，如果您在请求中包含 departureTime，则 API 会根据该时间内的预期交通状况，返回最佳路线，并且在响应中包含预计交通时间 (duration_in_traffic)。如果您没有指定出发时间（即：请求中没有包含 drivingOptions），则返回的路线通常是不考虑交通状况条件下的较佳路线。
• trafficModel（可选）：用于指定计算交通时间时所用的假设条件。此设置影响响应中 duration_in_traffic 字段中返回的值，该字段包含根据历史平均值预测的交通时间。默认设置为 best_guess。允许使用以下值：
  • google.maps.TrafficModel.BEST_GUESS（默认）或字符串值 best_guess：表示返回的 duration_in_traffic 应是根据已经知道的历史交通状况和实时交通状况条件下预估的最合理交通时间。departureTime 越接近当前时间，实时交通状况就越重要
  • google.maps.TrafficModel.PESSIMISTIC 或字符串值 pessimistic：表示返回的 duration_in_traffic 应长于大多数日子里的实际行程时间，尽管交通状况特别糟糕的少数日子里的行程时间可能超过此值
  • google.maps.TrafficModel.OPTIMISTIC 或字符串值 optimistic：表示返回的 duration_in_traffic 应短于大多数日子里的实际行程时间，尽管交通状况特别好的少数日子里的行程时间可能小于此值

以下是用于请求行车路线的 DistanceMatrixRequest 示例，其中包括出发时间和交通方式：

{
  origins: [{lat: 55.93, lng: -3.118}, "Greenwich, England"],
  destinations: ["Stockholm, Sweden", {lat: 50.087, lng: 14.421}],
  travelMode: google.maps.TravelMode.DRIVING,
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: "optimistic"
  }
}

距离矩阵响应

如果对 Distance Matrix 服务的调用成功，将返回一个 DistanceMatrixResponse 对象和一个 DistanceMatrixStatus 对象。这些对象会被传递至您在请求中指定的回调函数。

DistanceMatrixResponse 对象包含计算路线时所用的每个起点/终点对的距离和持续时间信息。

{
  "origin_addresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
  "destination_addresses": [ "Stockholm County, Sweden", "Dlouhá 609/2, 110 00 Praha-Staré Město, Česká republika" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 70778,
        "text": "19 hours 40 mins"
      },
      "distance": {
        "value": 1887508,
        "text": "1173 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 44476,
        "text": "12 hours 21 mins"
      },
      "distance": {
        "value": 1262780,
        "text": "785 mi"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 96000,
        "text": "1 day 3 hours"
      },
      "distance": {
        "value": 2566737,
        "text": "1595 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 69698,
        "text": "19 hours 22 mins"
      },
      "distance": {
        "value": 1942009,
        "text": "1207 mi"
      }
    } ]
  } ]
}

Distance Matrix 结果

响应中受支持的字段解释如下：

• originAddresses：一个数组，其中包含在 Distance Matrix 请求的 origins 字段中传递的位置。这些地址将按照地理编码器所设置的格式返回
• destinationAddresses：一个数组，其中包含在 destinations 字段中传递的位置，其格式为地理编码器所返回的格式
• rows：一个 DistanceMatrixResponseRow 对象数组，其中每一行对应一个起点
• elements：rows 的子项，对应于该行的起点与每个终点的配对。其中包含每个起点/终点对的状态、持续时间、距离和票价信息（如有）
• 每个 element 均包含以下字段：
  • status：有关可能的状态代码列表，请参阅状态代码
  • duration：此路线所需的行程时间，以 text 表示，单位为秒（value 字段）。文本值根据请求中指定的 unitSystem（如果没有提供首选项，则以公制表示）设置格式
  • duration_in_traffic：考虑当前交通状况条件下此路线所需的行程时间，以 text 表示，单位为秒（value 字段）。文本值根据请求中指定的 unitSystem（如果没有提供首选项，则以公制表示）设置格式duration_in_traffic 仅返回给符合以下要求的 Google Maps API for Work 客户：交通数据可用；mode 设置为 driving；departureTime 作为 distanceMatrixOptions 字段的一部分包含在请求中。
  • distance：该路线的总距离，以米数 (value) 和 text 形式表示。文本值根据请求中指定的 unitSystem（如果没有提供首选项，则以公制表示）设置格式
  • fare：其中包含此路线的总交通费用（即总票价）。只会为公共交通请求返回此属性，并且只会为提供票价信息的公共交通提供商返回此属性。这些信息包括：
    • currency：ISO 4217 币种代码，表示票价所采用的币种
    • value：总票价（以上面指定的币种为单位）

状态代码

Distance Matrix 响应包含整个响应的状态代码以及其中每个元素对应的状态。

响应状态代码

适用于 DistanceMatrixResponse 的状态代码通过 DistanceMatrixStatus 对象传递，其中包括：

• OK：请求有效。即使在所有起点和终点之间都没有找到任何路线，也可能返回此状态。有关元素级别的状态信息，请参阅元素状态代码
• INVALID_REQUEST：所提供的请求无效。这通常是因缺少必填字段所致。请参阅上文的支持的字段列表
• MAX_ELEMENTS_EXCEEDED：起点和终点数量的乘积超过每次查询限值
• MAX_DIMENSIONS_EXCEEDED：您的请求包含 25 个以上起点，或 25 个以上终点
• OVER_QUERY_LIMIT：您的应用在允许的时间内请求的元素过多。如果您在适当时间过后重试，请求应该会成功
• REQUEST_DENIED：服务拒绝您的网页使用 Distance Matrix 服务
• UNKNOWN_ERROR：Distance Matrix 请求因服务器出错而无法得到处理。如果您重试一次，请求可能会成功

元素状态代码

以下状态代码适用于特定 DistanceMatrixElement 对象：

• NOT_FOUND：此配对的起点和/或终点无法进行地理编码
• OK：响应包含有效结果
• ZERO_RESULTS：在起点和终点之间找不到路线

解析结果

DistanceMatrixResponse 对象中均有一个 row 与请求中所传递的每个起点相对应。每个行均有一个 element 字段与该起点及所提供终点的每个配对相对应。

function callback(response, status) {
  if (status == google.maps.DistanceMatrixStatus.OK) {
    var origins = response.originAddresses;
    var destinations = response.destinationAddresses;

    for (var i = 0; i < origins.length; i++) {
      var results = response.rows[i].elements;
      for (var j = 0; j < results.length; j++) {
        var element = results[j];
        var distance = element.distance.text;
        var duration = element.duration.text;
        var from = origins[i];
        var to = destinations[j];
      }
    }
  }
}