一切就绪!

着手开发前,请先阅读我们的开发者文档

激活 Google Maps JavaScript API

为帮助您起步,我们将引导您在 Google Developers Console 中先完成几项任务:

  1. 创建或选择项目
  2. 激活 Google Maps JavaScript API 及相关服务
  3. 创建相应密钥
继续

Distance Matrix 服务

概览

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

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

入门指南

在 Google Maps JavaScript API 中使用 Distance Matrix 服务之前,首先要确保在为 Google Maps JavaScript API 设置的同一项目的 Google API Console 中启用 Google Maps Distance Matrix API。

要查看已启用 API 的列表,请执行以下操作:

  1. 转至 Google API Console
  2. 点击 Select a project 按钮,然后选择为 Google Maps JavaScript API 设置的同一项目并点击 Open
  3. Dashboard 上的 API 列表中,寻找 Google Maps Distance Matrix API
  4. 如果在列表中看到该 API,则大功告成。如果列出该 API,请执行以下操作将其启用:
    1. 在页面顶部,选择 ENABLE API 以显示 Library 标签。也可从左侧菜单中选择 Library
    2. 搜索 Google Maps Distance Matrix API,然后从结果列表中选择它。
    3. 选择 ENABLE。流程完成时,Google Maps Distance Matrix API 即会出现在 Dashboard 上的 API 列表中。

使用限额和政策

配额

对于 Distance Matrix 服务,具有以下使用限制:

:发送至 Distance Matrix 服务的每个查询均受允许的元素数量限制,起点数量与终点数量的乘积便是元素数量。

搭配标准计划使用 Directions Matrix 服务

  • 每天 2,500 个免费元素,按客户端与服务器端查询次数之和计算; 启用计费可获得更高每日配额,按 0.50 美元/1000 个额外元素计费,每日上限为 100,000 个元素。
  • 每个请求最多 25 个起点或 25 个终点。
  • 每个请求最多 100 个元素。
  • 每秒最多 100 个元素,按客户端与服务器端查询次数之和计算。

搭配高级计划使用 Directions Matrix 服务

  • 100,000 个元素的每日免费共享配额(每 24 小时);根据每年购买的 Maps API 额度提供的额外请求。
  • 每个请求最多 25 个起点或 25 个终点。
  • 每个请求最多 625 个元素。注:mode=driving 时使用可选参数 departure_time 的请求有每个请求 100 个元素的限额。
  • 每个项目每秒 不受限制 个客户端元素。请注意,服务器端 API 有每秒 1,000 个元素的限额。

无论有多少位用户共享同一项目,均以用户会话为单位施加速率限制。

单位会话速率限制可防止将客户端服务用于批量请求。对于批量请求,请使用 Google Maps Distance Matrix API 网络服务

政策

必须按照所介绍的适用于 Google Maps Distance Matrix API 的政策使用 Directions Matrix 服务。

距离矩阵请求

由于 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: '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 对象或 google.maps.Place 对象。
  • destinations(必填):一个数组,其中包含一个或多个用来计算距离和时间终点的地址字符串、google.maps.LatLng 对象或 google.maps.Place 对象。
  • travelMode可选):计算路线时所用的交通方式。请参阅出行方式部分
  • transitOptions可选):仅适用于 travelModeTRANSIT 的请求的选项。有效值见下文公交选项部分所述
  • drivingOptions可选):用于指定仅适用于 travelModeDRIVING 的请求的值。有效值见下文行车选项部分所述
  • unitSystem可选):显示结果时所用的单位制。接受的值为:
    • google.maps.UnitSystem.METRIC(默认)
    • google.maps.UnitSystem.IMPERIAL
  • avoidHighways可选):如果设置为 true,计算起点与终点之间的路线时将尽可能避免公路
  • avoidTolls可选):如果设置为 true,计算两点之间的路线时将尽可能使用非收费路线

出行模式

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

  • BICYCLING:请求经由自行车道和首选街道的骑行路线(目前只在美国和部分加拿大城市推出)。
  • DRIVING(默认方式):表示使用道路网的标准驾车路线。
  • TRANSIT:请求经由公共交通线路的路线。只有当请求包括 API 密钥时,才能指定此选项。有关此类请求的适用选项,请参阅公交选项部分
  • WALKING:请求经由步道和人行道(如有)的步行路线。

公交选项

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

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

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

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

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

这些字段解释如下:

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

行车选项

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

DrivingOptions 对象包含以下字段:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

这些字段解释如下:

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

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

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

距离矩阵响应

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

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

{
  "originAddresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
  "destinationAddresses": [ "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 对象数组,其中每一行对应一个起点
  • elementsrows 的子项,对应于该行的起点与每个终点的配对。其中包含每个起点/终点对的状态、持续时间、距离和票价信息(如有)
  • 每个 element 均包含以下字段:
    • status:有关可能的状态代码列表,请参阅状态代码
    • duration:此路线所需的行程时间,以 text 表示,单位为秒(value 字段)。文本值根据请求中指定的 unitSystem(如果没有提供首选项,则以公制表示)设置格式
    • duration_in_traffic:考虑当前交通状况条件下此路线所需的行程时间,以 text 表示,单位为秒(value 字段)。文本值根据请求中指定的 unitSystem(如果没有提供首选项,则以公制表示)设置格式duration_in_traffic 仅返回给符合以下要求的 Google Maps APIs Premium Plan 客户:交通数据可用;mode 设置为 drivingdepartureTime 作为 distanceMatrixOptions 字段的一部分包含在请求中。
    • distance:该路线的总距离,以米数 (value) 和 text 形式表示。文本值根据请求中指定的 unitSystem(如果没有提供首选项,则以公制表示)设置格式
    • fare:其中包含此路线的总交通费用(即总票价)。只会为公共交通请求返回此属性,并且只会为提供票价信息的公共交通提供商返回此属性。这些信息包括:
      • currencyISO 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 == '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];
      }
    }
  }
}

发送以下问题的反馈:

此网页
Google Maps JavaScript API
Google Maps JavaScript API
需要帮助?请访问我们的支持页面