路线服务

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

概览

您可以使用 DirectionsService 对象计算路线(使用各种交通方式)。此对象会与 Google Maps API 路线服务进行通信,该服务会接收路线请求并返回高效路径。出行时间是经过优化的主要因素,但距离、转弯次数和许多其他因素也会考虑在内。您可以自行处理这些路线结果,也可以使用 DirectionsRenderer 对象呈现这些结果。

在路线请求中指定出发地或目的地时,您可以指定查询字符串(例如“伊利诺斯州芝加哥市”或“伊利诺斯州达尔文”、“新南威尔士州达尔文”)、LatLng 值或 Place 对象。

路线服务可以使用一系列航点返回多段路线。路线可以显示为一条在地图上绘制路线的多段线,或者作为 <div> 元素中的一系列文字说明显示(例如,“右转上中山南路”)。

开始使用

在 Maps JavaScript API 中使用路线服务之前,请先确保在 Google Cloud Console 中为您为 Maps JavaScript API 设置的项目中启用了 Directions API。

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

  1. 转到 Google Cloud Console
  2. 点击选择项目按钮,然后选择您为 Maps JavaScript API 设置的同一项目,然后点击打开
  3. 信息中心的 API 列表中,查找 Directions API
  4. 如果您在列表中看到了该 API,就说明一切就绪。如果未列出该 API,请启用:
    1. 在页面顶部,选择 ENABLE API 以显示标签页。或从左侧菜单中选择
    2. 搜索 Directions API,然后从结果列表中选择它。
    3. 选择启用。该过程完成后,Directions API 会显示在信息中心的 API 列表中。

价格和政策

价格

自 2018 年 7 月 16 日起,地图、路线和地点产品将采用全新的随用随付定价方案。如需详细了解 JavaScript 路线服务的使用新价格和用量限额,请参阅 Directions API 的使用情况和结算

速率限制

对于其他请求的限制,请注意以下几点:

无论有多少用户共享同一项目,都按用户会话应用速率限制。首次加载 API 时,系统会为您分配初始请求配额。您使用此配额后,该 API 会对每秒的请求施加速率限制。如果某个时间段内发出的请求过多,该 API 会返回 OVER_QUERY_LIMIT 响应代码。

基于会话的速率限制可防止将客户端服务用于批量请求。对于批量请求,请使用 Directions API 网络服务

政策

必须按照针对 Directions API 所述的政策使用路线服务。

路线请求

由于 Google Maps API 需要调用外部服务器,因此对路线服务的访问是异步进行的。因此,您需要传递一个回调方法,以便在请求完成后执行。此回调方法将会对结果进行处理。请注意,路线服务可能会以单个 routes[] 数组的形式返回多个可能的行程。

如需在 Maps JavaScript API 中使用路线,请创建类型为 DirectionsService 的对象并调用 DirectionsService.route(),以向路线服务发送请求,并向其传递 DirectionsRequest 对象字面量(其中包含输入字词)以及用于在收到响应后执行的回调方法。

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

{
  origin: LatLng | String | google.maps.Place,
  destination: LatLng | String | google.maps.Place,
  travelMode: TravelMode,
  transitOptions: TransitOptions,
  drivingOptions: DrivingOptions,
  unitSystem: UnitSystem,
  waypoints[]: DirectionsWaypoint,
  optimizeWaypoints: Boolean,
  provideRouteAlternatives: Boolean,
  avoidFerries: Boolean,
  avoidHighways: Boolean,
  avoidTolls: Boolean,
  region: String
}

这些字段的含义如下:

  • origin(必需)用于指定计算路线时所用的起始地点。此值可指定为 String(例如“伊利诺斯州芝加哥市”),也可指定为 LatLng 值或地点对象。如果您使用地点对象,则可以指定地点 ID、查询字符串或 LatLng 位置。您可以通过 Maps JavaScript API 中的地理编码、地点搜索和地点自动补全服务检索地点 ID。如需查看使用地点自动补全功能中的地点 ID 的示例,请参阅地点自动补全和路线
  • destination(必需)用于指定计算路线时所用的结束地点。这些选项与上述 origin 字段相同。
  • travelMode(必需)指定计算路线时所用的交通方式。有效值见下文出行模式部分所述。
  • transitOptions(可选)指定仅适用于 travelModeTRANSIT 的请求的值。有效值见下文公交选项部分所述。
  • drivingOptions(可选)指定仅适用于 travelModeDRIVING 的请求的值。有效值见下文驾驶选项部分所述。
  • unitSystem(可选)指定显示结果时使用的单位制。您可在下面的单位制中指定有效值。

  • waypoints[](可选)指定 DirectionsWaypoint 数组。航点可以通过指定路线来路由路线。将某个航点指定为带有如下字段的对象字面量:

    • location 将航点的位置指定为 LatLngPlace 对象或将进行地理编码的 String
    • stopover 是一个布尔值,表示航点是路线上的一个停留点,可将路线拆分为两条路线。

    (如需详细了解航点,请参阅下文中的在路线中使用航点部分。)

  • optimizeWaypoints可选)指定使用所提供的 waypoints 的路线可以通过更有效的顺序重新排列这些航点进行优化。如果为 true,路线服务将在 waypoint_order 字段中返回重新排序的 waypoints(如需了解详情,请参阅下文中的在路线中使用航点)。
  • provideRouteAlternatives(可选)设置为 true 时,指定路线服务可在响应中提供多条备用路线。请注意,提供备用路线可能会增加服务器的响应时间。此方式仅适用于没有中间航点的请求。
  • avoidFerries(可选)设置为 true 时,表示计算的路线应尽可能避开轮渡。
  • avoidHighways(可选)设置为 true 时,表示计算的路线应尽可能避开主要高速公路。
  • avoidTolls(可选)设置为 true 时,表示计算的路线应避开收费道路(如果可能)。
  • region(可选)指定地区代码,以 ccTLD(“顶级域名”)双字符值的形式指定。(如需了解详情,请参阅下文的区域偏向)。

以下是一个示例 DirectionsRequest

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  waypoints: [
    {
      location: 'Joplin, MO',
      stopover: false
    },{
      location: 'Oklahoma City, OK',
      stopover: true
    }],
  provideRouteAlternatives: false,
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(/* now, or future date */),
    trafficModel: 'pessimistic'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

出行模式

计算路线时,您需要指定要使用的交通模式。目前支持以下出行方式:

  • DRIVING(默认)指示使用道路网络的标准行车路线。
  • BICYCLING 用于请求经过自行车道和首选街道的骑行路线。
  • TRANSIT 请求通过公交路线查询路线。
  • WALKING 请求通过步道和人行道的步行路线。

请查阅 Google Maps Platform 覆盖范围详细信息,确定某个国家/地区支持的路线范围。如果您针对没有该方向类型的区域请求路线,响应将返回 DirectionsStatus=“ZERO_RESULTS”。

注意:步行路线可能不包含明确的步道,因此,如果您未使用默认的 DirectionsRenderer,步行路线将在您必须显示的 DirectionsResult 中返回警告。

公共交通选项

可用的路线请求选项因出行方式而异。 请求公交路线时,avoidHighwaysavoidTollswaypoints[]optimizeWaypoints 选项将被忽略。您可以通过 TransitOptions 对象字面量指定特定于公交的路由选项。

公交路线具有时效性。系统只会针对将来的时间返回路线。

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

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

这些字段的含义如下:

  • arrivalTime(可选)以 Date 对象的形式指定所需的到达时间。如果指定到达时间,系统会忽略出发时间。
  • departureTime(可选)以 Date 对象的形式指定期望的出发时间。如果指定了 arrivalTimedepartureTime 将被忽略。如果未为 departureTimearrivalTime 指定任何值,则默认值为现在(即当前时间)。
  • modes[](可选)是包含一个或多个 TransitMode 对象字面量的数组。只有在请求中包含 API 密钥时,才可以添加此字段。每个 TransitMode 均指定首选交通方式。允许使用以下值:
    • BUS 表示计算的路线应首选公交车出行。
    • RAIL 表示计算的路线应首选火车、电车、轻轨和地铁出行。
    • SUBWAY 表示计算的路线应首选地铁出行。
    • TRAIN 表示计算的路线应首选火车出行。
    • TRAM 表示计算的路线应首选有轨电车和轻轨出行。
  • routingPreference(可选)指定公交路线的偏好设置。使用此选项,您可以自定义返回的选项,而不是接受 API 选择的默认最佳路线。 只有在请求中包含 API 密钥时,才能指定此字段。允许使用以下值:
    • FEWER_TRANSFERS 表示计算的路由应首选有限数量的传输。
    • LESS_WALKING 表示计算的路线应首选有限的步行距离。

公交 DirectionsRequest 示例如下所示:

{
  origin: 'Hoboken NJ',
  destination: 'Carroll Gardens, Brooklyn',
  travelMode: 'TRANSIT',
  transitOptions: {
    departureTime: new Date(1337675679473),
    modes: ['BUS'],
    routingPreference: 'FEWER_TRANSFERS'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

行车选项

您可以通过 DrivingOptions 对象指定行车路线的路线选项。

DrivingOptions 对象包含以下字段:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

这些字段的含义如下:

  • departureTime必须使 drivingOptions 对象字面量有效)以 Date 对象的形式指定所需的出发时间。该值必须设置为当前时间或未来的某个时间,而不能是过去的时间。(API 会将所有日期转换为 UTC,以确保跨时区一致处理。)对于 Google Maps Platform 高级计划客户,如果您在请求中包含 departureTime,则该 API 会根据当时的预期路况条件返回最佳路线,并在响应中加入预测的路况时间 (duration_in_traffic)。如果您未指定出发时间(即请求不包含 drivingOptions),则返回的路线通常是不考虑路况条件的常规路线。
  • trafficModel(可选)指定在计算交通时间时使用的假设。此设置会影响响应中 duration_in_traffic 字段中返回的值,该值包含根据历史平均值预测的流量。默认为 bestguess。允许使用以下值:
    • bestguess(默认)表示返回的 duration_in_traffic 应该是根据已知交通状况和实时路况信息得出的最佳出行时间估算值。departureTime 越接近当前时间,实时流量就越重要。
    • pessimistic 表示在大多数情况下返回的 duration_in_traffic 应该比实际出行时间更长,但交通状况特别糟糕的少数日期有时可能会超过此值。
    • optimistic 表示在大多数日子里返回的 duration_in_traffic 应该短于实际行程时间,但在交通状况特别好的日子里,偶尔偶尔会比该值更快。

以下是行车路线示例 DirectionsRequest

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

单位制

默认情况下,系统会使用起点所在国家或地区的单位制计算和显示路线。(注意:以纬度/经度坐标而不是地址表示的源站始终默认采用公制单位。)例如,从“伊利诺伊州芝加哥市”到“多伦多安大略省”的路线将以英里为单位显示结果,而反向路线将以公里为单位显示结果。您可以使用以下某个 UnitSystem 值在请求中显式设置一个单位制,从而覆盖此单位制:

  • UnitSystem.METRIC 用于指定使用公制。以公里为单位显示距离
  • UnitSystem.IMPERIAL 用于指定使用英制。以英里为单位显示距离

注意:此单位制设置仅会影响向用户显示的文字。路线结果也包括始终以米为单位表示的距离,但这些值不向用户显示。

路线的区域偏向

Google Maps API 路线服务会返回受您从中加载 JavaScript 引导加载程序的网域(国家或地区)影响的地址结果。(由于大多数用户都会加载 https://maps.googleapis.com/,因此对于美国用户而言,这会设置隐式网域。)如果您从其他受支持的网域加载引导加载程序,则会获得受该网域影响的结果。例如,对于加载“旧金山”的搜索,加载 https://maps.googleapis.com/(美国)的应用与加载 http://maps.google.es/(西班牙)的应用可能会返回不同的结果。

您还可以使用 region 参数将路线服务设置为返回偏向特定区域的结果。此参数采用地区代码,指定为两个字符(非数字)Unicode 区域子标记。在大多数情况下,这些标记会直接映射到 ccTLD(“顶级域名”)双字符值,例如“co.uk”中的“uk”。在某些情况下,region 标记也支持 ISO-3166-1 代码,该代码有时会与 ccTLD 值有所不同(例如,“GB”表示“大不列颠”)。

使用 region 参数时:

  • 请仅指定一个国家或地区。系统会忽略多个值,这可能会导致请求失败。
  • 只能使用两个字符的区域子标记(Unicode CLDR 格式)。所有其他输入都会导致错误。

区域自定义调整仅支持支持路线的国家/地区。如需了解 Directions API 的国际覆盖范围,请参阅 Google Maps Platform 覆盖范围详细信息

呈现路线

如果使用 route() 方法向 DirectionsService 发起路线请求,则必须传递一个在服务请求完成后执行的回调。此回调将在响应中返回 DirectionsResultDirectionsStatus 代码。

路线查询状态

DirectionsStatus 可能会返回以下值:

  • OK 表示响应包含有效的 DirectionsResult
  • NOT_FOUND 表示请求的出发地、目的地或航点中指定的地点中至少有一个无法进行地理编码。
  • ZERO_RESULTS 表示在源站和目的地之间找不到任何路由。
  • MAX_WAYPOINTS_EXCEEDED 表示 DirectionsRequest 中提供的 DirectionsWaypoint 字段过多。请参阅下文有关路线点限制的部分。
  • MAX_ROUTE_LENGTH_EXCEEDED 表示请求的路线过长,无法处理。当返回更复杂的路线时,会发生此错误。请尝试减少航点、转弯或指令的数量。
  • INVALID_REQUEST 表示提供的 DirectionsRequest 无效。此类错误代码最常见的原因是缺少出发地或目的地的请求,或包含航点的公交请求。
  • OVER_QUERY_LIMIT 表示网页在允许的时间段内发送的请求过多。
  • REQUEST_DENIED 表示不允许网页使用路线服务。
  • UNKNOWN_ERROR 表示路线请求因服务器出错而无法得到处理。如果您重试,请求可能会成功。

在处理结果之前,您应通过检查该值来确保路线查询返回的结果有效。

显示 DirectionsResult

DirectionsResult 包含路线查询的结果,您可以自行处理该结果,也可以将其传递到 DirectionsRenderer 对象,该对象可自动处理该结果在地图上的显示方式。

如需使用 DirectionsRenderer 显示 DirectionsResult,您需要执行以下操作:

  1. 创建 DirectionsRenderer 对象。
  2. 在渲染程序上调用 setMap(),以将其绑定到传递的地图。
  3. 在渲染程序上调用 setDirections(),并向其传递 DirectionsResult(如上所述)。由于渲染程序是一个 MVCObject,因此它会自动检测其属性发生的任何变化,并在其关联路线更改时更新地图。

以下示例计算了 66 号公路上两个地点之间的路线,其中起点和终点由下拉列表中指定的 "start""end" 值设置。DirectionsRenderer 会处理指定位置之间的多段线显示,并将标记放在起点、终点和所有航点(如适用)。

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin: start,
    destination: end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(result, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(result);
    }
  });
}

在 HTML 正文中:

<div>
<strong>Start: </strong>
<select id="start" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
</div>

查看示例

以下示例显示了从加利福尼亚州旧金山的海特-黑什伯里区到海滩之间使用不同出行方式的路线:

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var haight = new google.maps.LatLng(37.7699298, -122.4469157);
  var oceanBeach = new google.maps.LatLng(37.7683909618184, -122.51089453697205);
  var mapOptions = {
    zoom: 14,
    center: haight
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var selectedMode = document.getElementById('mode').value;
  var request = {
      origin: haight,
      destination: oceanBeach,
      // Note that JavaScript allows us to access the constant
      // using square brackets and a string value as its
      // "property."
      travelMode: google.maps.TravelMode[selectedMode]
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

在 HTML 正文中:

<div>
<strong>Mode of Travel: </strong>
<select id="mode" onchange="calcRoute();">
  <option value="DRIVING">Driving</option>
  <option value="WALKING">Walking</option>
  <option value="BICYCLING">Bicycling</option>
  <option value="TRANSIT">Transit</option>
</select>
</div>

查看示例

DirectionsRenderer 不仅可以处理多段线和任何关联标记的显示方式,也可以将路线的文本显示处理为一系列步骤。为此,请对 DirectionsRenderer 调用 setPanel(),并向其传递要在其中显示此信息的 <div>。这样做还可确保显示适当的版权信息,以及与结果相关的任何警告。

系统将使用浏览器的首选语言设置或在加载 API JavaScript 时使用 language 参数指定的语言来提供文本路线。(如需了解详情,请参阅本地化。)如果是公交路线,时间将以相应公交车站所在的时区显示。

以下示例与上面显示的示例相同,但包含了一个用于显示路线的 <div> 面板:

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
  directionsRenderer.setPanel(document.getElementById('directionsPanel'));
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin:start,
    destination:end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

在 HTML 正文中:

<div id="map" style="float:left;width:70%;height:100%"></div>
<div id="directionsPanel" style="float:right;width:30%;height:100%"></div>

查看示例

DirectionsResult 对象

DirectionsService 发送路线请求时,您会收到一个响应,该响应包含状态代码和结果(即 DirectionsResult 对象)。DirectionsResult 是一个包含以下字段的对象字面量:

  • geocoded_waypoints[] 包含一个 DirectionsGeocodedWaypoint 对象数组,其中每个对象都包含起点、目的地和航点的地理编码详情。
  • routes[] 包含 DirectionsRoute 对象的数组。每条路线均表示一种从出发地到达 DirectionsRequest 中提供的目的地的方式。通常,除非请求的 provideRouteAlternatives 字段设置为 true(在这种情况下,可能会返回多条路线),否则不会为任何给定请求返回一条路线。

注意:备用属性中已弃用 via_waypoint 属性。版本 3.27 是该 API 的最后一个版本,它通过替代路线添加了额外的路径点。对于 3.28 版及更高版本的 API,您可以通过停用拖动备用路线的功能,继续使用路线服务实现可拖动路线。 只有主路线可以拖动。用户可以拖动主路由,直到它与备用路由匹配。

经过地理编码的路线路径点

DirectionsGeocodedWaypoint 包含有关出发地、目的地和航点的地理编码详情。

DirectionsGeocodedWaypoint 是一个包含以下字段的对象字面量:

  • geocoder_status 表示地理编码操作产生的状态代码。此字段可能包含下列值。
    • "OK" 表示未发生错误;地址已成功解析,并且至少返回了一个地理编码。
    • "ZERO_RESULTS" 表示地理编码成功,但未返回任何结果。如果向地理编码器传递了不存在的 address,就可能会发生这种情况。
  • partial_match 表示地理编码器未针对原始请求返回完全匹配,但能够匹配所请求的地址的一部分。您不妨检查一下原始请求中是否有拼写错误和/或地址不完整的情况。

    部分匹配最常出现在不在您传递的请求中所处的市行政区内街道地址。当请求与同一市行政区内的两个或更多位置匹配时,也可能会返回部分匹配项。例如,“Hillpar St, Bristol, UK”将同时返回 Henry Street 和 Henrietta Street 的部分匹配结果。请注意,如果请求中包含拼写错误的地址组成部分,地理编码服务可能会建议一个备用地址。以这种方式触发的建议也将被标记为部分匹配。

  • place_id 是地点的唯一标识符,可用于其他 Google API。例如,您可以将 place_idGoogle Places API 库结合使用,以获取本地商家的详细信息,例如电话号码、营业时间、用户评价等。请参阅地点 ID 概览
  • types[] 是一个数组,表示返回结果的类型。此数组包含一组零个或多个标记,这些标记用于标识结果中返回的特征类型。例如,对“芝加哥”的地理编码返回“芝加哥”(表示“芝加哥”),同时返回“政治”来表明其为政治实体。

路线

注意:旧版 DirectionsTrip 对象已重命名为 DirectionsRoute。请注意,路线现在是指从开始到结束的整个行程,而不只是父级行程的一段路程。

DirectionsRoute 包含来自指定出发地和目的地的一条结果。此路线可以包含一条或多段路程(类型为 DirectionsLeg),具体取决于是否指定了任何航点。此外,除了路由信息之外,该路线还包含必须向用户显示的版权和警告信息。

DirectionsRoute 是一个包含以下字段的对象字面量:

  • legs[] 包含一个 DirectionsLeg 对象数组,每个对象均包含关于路线的一段路程(介于指定路线中的两个位置之间)的信息。系统会为每个指定的航点或目的地显示一个单独的航段。(没有任何航点的路线将仅包含一个 DirectionsLeg。)每段路程均由一系列 DirectionStep 组成。
  • waypoint_order 包含一个数组,该数组指示计算路线中所有航点的顺序。如果向 DirectionsRequest 传递了 optimizeWaypoints: true,此数组可能会包含经过更改的顺序。
  • overview_path 包含一个 LatLng 数组,表示所生成路线的近似(平滑)路径。
  • overview_polyline 包含一个 points 对象,该对象包含路线的编码多段线表示形式。此多段线是生成的路线的近似(平滑)路径。
  • bounds 包含一个 LatLngBounds,用于指示沿此给定路线的多段线的边界。
  • copyrights 包含为此路线显示的版权文本。
  • warnings[] 包含要在显示这些路线时显示的一系列警告。如果您不使用提供的 DirectionsRenderer 对象,则必须自行处理和显示这些警告。
  • fare 包含此路线的总费用(即总票价)。此属性仅针对公交请求返回,且仅适用于可获取所有公交路程的票价信息的路线。这些信息包括:
    • currencyISO 4217 货币代码,用于表示金额所用的货币。
    • value:总票价金额,以上述货币为单位。

路线路程

注意:旧版 DirectionsRoute 对象已重命名为 DirectionsLeg

DirectionsLeg 定义计算的路线中从起点到终点的一段行程路程。对于不包含任何航点的路线,将包含一段“路程”;但对于定义一个或多个航点的路线,将包含一段或多段路程(与行程的特定路程相对应)。

DirectionsLeg 是一个包含以下字段的对象字面量:

  • steps[] 包含一个 DirectionsStep 对象数组,这些对象表示关于行程路程的各单独步骤的信息。
  • distance 表示该路程包含的总距离,格式为 Distance 对象,格式如下:

    • value 表示距离(以米为单位)
    • text 包含距离的字符串表示形式,默认情况下,以起点所使用的单位显示。(例如,美国境内的任何起点都将使用英里)。您可以通过在原始查询中专门设置一个 UnitSystem 来替换此单位制。请注意,无论您使用哪种单位制,distance.value 字段始终会包含一个以米为单位表示的值。

    如果距离未知,那么这些字段可能未定义。

  • duration 表示该路程的总持续时间,表示为以下形式的 Duration 对象:

    • value 表示时长(以秒为单位)。
    • text 包含时长的字符串表示形式。

    如果持续时间未知,那么这些字段可能未定义。

  • duration_in_traffic 表示在考虑当前路况的情况下此路程的总持续时间。只有在满足以下所有条件时,才会返回 duration_in_traffic

    • 此请求不包含停靠航点。也就是说,它不包含 stopovertrue 的路径点。
    • 该请求专用于行车路线,即 mode 设置为 driving
    • departureTime 包含在请求的 drivingOptions 字段中。
    • 可以获得所请求路线的交通状况。

    duration_in_traffic 包含以下字段:

    • value 表示时长(以秒为单位)。
    • text 包含以可人工读取的形式表示的持续时间。
  • arrival_time 包含此路程的预计到达时间。系统只针对公交路线返回该属性。结果以 Time 对象形式返回,具有以下三个属性:
    • value 指定作为 JavaScript Date 对象的时间。
    • text 以字符串形式指定的时间。时间以公交站点的时区显示。
    • time_zone 包含此站点的时区。该值就是 IANA 时区数据库中定义的时区名称,例如 &mer.America/New_York。
  • departure_time 包含此路程的预计出发时间,指定为 Time 对象。departure_time 仅适用于公交路线。
  • start_location 包含此路程起点的 LatLng。由于路线网络服务会使用距起点和终点最近的交通选项(通常为道路)计算不同位置间的路线,因此在道路不靠近该路程提供的起点等情况下,start_location 可能与该起点不同。
  • end_location 包含此路程终点的 LatLng。由于 DirectionsService 会使用距起点和终点最近的交通选项(通常为道路)计算不同位置间的路线,因此在道路不靠近该路程提供的目的地等情况下,end_location 可能会不同。
  • start_address 包含这段路程起点的可人工读取的地址(通常为街道地址)。

    此内容旨在按原样读取。请勿以编程方式解析格式化地址。
  • end_address 包含这段路程终点的可人工读取的地址(通常为街道地址)。

    此内容旨在按原样读取。请勿以编程方式解析格式化地址。

路线路段

DirectionsStep 是路线路线的最小单元,其中包含用于介绍相应行程中的某个特定说明的单个步骤。例如“在 W 左转”。第四大道此步骤不仅介绍了说明,还包含了有关此步骤与下一步之间的关系的距离和时长信息。 例如,一个指示“并入 I-80 West”的路段可能包含 37 英里和 40 分钟的持续时间,表示下一个路段距离此路段有 37 英里/40 分钟。

使用路线服务搜索公交路线时,步数数组将以 transit 对象的形式包含其他公交专属信息。如果路线包含多种交通方式,那么系统会针对 steps[] 数组中的步行或驾车路线提供详细路线。 例如,步行步数将包括从起点和终点位置开始的路线:步行至 Innes Ave & Fitch St”。该步骤会在 steps[] 数组中包含该路线的详细步行路线,例如:“向西北方向走”、“左转进入 Arelious Walker”和“向左转上‘Innes Ave’”。

DirectionsStep 是一个包含以下字段的对象字面量:

  • instructions 在文本字符串中包含此步骤的说明。
  • distanceDistance 对象的形式包含此路段与下一个路段之间的距离。(请参阅上文 DirectionsLeg 中的说明。)如果距离未知,则此字段可能未定义。
  • duration 包含以某种 Duration 对象形式表示执行该步骤到下一个步骤所需的时间估算值。(请参阅上文 DirectionsLeg 中的说明。)如果持续时间未知,则此字段可能未定义。
  • start_location 包含此路段起点的经过地理编码的 LatLng
  • end_location 包含此步骤终点的 LatLng
  • polyline 包含一个 points 对象,该对象包含步骤的编码多段线表示。此多段线是步骤的近似(平滑)路径。
  • steps[] 是一个 DirectionsStep 对象字面量,其中包含公交路线中步行或驾车步骤的详细路线。子路段只适用于公共交通路线。
  • travel_mode 包含此步骤中使用的 TravelMode。公交路线可能同时包含步行路线和公交路线。
  • path 包含描述此步骤的 LatLngs 数组。
  • transit 包含公交专属信息,例如到达和出发时间以及公交线路的名称。

公共交通专属信息

公交路线会返回与其他交通方式无关的额外信息。这些附加属性通过 TransitDetails 对象公开,并作为 DirectionsStep 的属性返回。在 TransitDetails 对象中,您可以访问 TransitStopTransitLineTransitAgencyVehicleType 对象的其他信息,如下所述。

公共交通详情

TransitDetails 对象具有以下属性:

  • arrival_stop 包含一个代表到达站点的车站的 TransitStop 对象,具有以下属性:
    • name:公交站点的名称。例如 “联合广场”。
    • location:中转站/车站的位置,以 LatLng 表示。
  • departure_stop 包含一个表示出发站点/站点的 TransitStop 对象。
  • arrival_time 包含到达时间,指定为具有以下三个属性的 Time 对象:
    • value 指定作为 JavaScript Date 对象的时间。
    • text 以字符串形式指定的时间。时间以公交站点的时区显示。
    • time_zone 包含此站点的时区。该值就是 IANA 时区数据库中定义的时区名称,例如 &mer.America/New_York。
  • departure_time 包含以 Time 对象指定的出发时间。
  • headsign 用于指定该线路的行驶方向,即车辆或出发车站所标示的方向。这通常是终点站。
  • headway(如果有),用于指定目前从同一站点出发的预计间隔秒数。例如,当 headway 值为 600 时,如果您错过了一班公交,那么预计需要 10 分钟才能等到下一班。
  • line 包含一个 TransitLine 对象字面量,其中包含此步骤中所用的公交线路的相关信息。TransitLine 提供该行的名称和运算符,以及 TransitLine 参考文档中所述的其他属性。
  • num_stops 包含此步骤中的站点数量。该数量包含到达站点,但不含出发站点。例如,如果您的路线是从站点 A 出发,经过站点 B 和 C,最终到达站点 D,那么 num_stops 会返回 3。

公共交通线路

TransitLine 对象具有以下属性:

  • name 包含该公交线路的全名。例如: “7号大道快线”或“14路跨市区线”。
  • short_name 包含此公交线路的简称。这通常是线路编号,例如“2”或“M14”。
  • agencies 是包含单个 TransitAgency 对象的数组。TransitAgency 对象提供有关此行运算符的信息,包括以下属性:
    • name 包含公交公司的名称。
    • phone 包含公交公司的电话号码。
    • url 包含公交公司的网址。

    注意:如果您要手动呈现公交路线,而不是使用 DirectionsRenderer 对象,则必须显示提供行程结果的公交公司的名称和网址。

  • url 包含由公交公司提供的该公交线路的网址。
  • icon 包含与此行关联的图标的网址。 大多数城市都会使用根据交通工具类型而变化的通用图标。某些公交线路(如纽约地铁系统)有专门针对该线路的图标。
  • color 包含此公交站牌上常用的颜色。颜色以十六进制字符串形式指定,例如:#FF0033。
  • text_color 包含该线路站牌上常用的文字颜色。颜色以十六进制字符串形式指定。
  • vehicle 包含一个 Vehicle 对象,该对象包含以下属性:
    • name 包含该线上交通工具的名称。例如 “地铁”。
    • type 包含该线路所用车辆的类型。如需查看受支持值的完整列表,请参阅车辆类型文档。
    • icon 包含通常与该车辆类型相关联的图标的网址。
    • local_icon 包含与此车辆类型关联的图标的网址(基于当地交通标识牌)。

交通工具类型

VehicleType 对象具有以下属性:

定义
VehicleType.RAIL 铁路。
VehicleType.METRO_RAIL 轻轨交通。
VehicleType.SUBWAY 地下轻轨。
VehicleType.TRAM 地上轻轨。
VehicleType.MONORAIL 单轨。
VehicleType.HEAVY_RAIL 重轨。
VehicleType.COMMUTER_TRAIN 通勤铁路。
VehicleType.HIGH_SPEED_TRAIN 高速列车。
VehicleType.BUS 公共汽车。
VehicleType.INTERCITY_BUS 长途客车。
VehicleType.TROLLEYBUS 无轨电车
VehicleType.SHARE_TAXI 合乘出租车是一种在公交路线上随叫随到的公共汽车。
VehicleType.FERRY 渡船
VehicleType.CABLE_CAR 一种通常在陆上依靠缆线运行的交通工具。空中缆车可能属于 VehicleType.GONDOLA_LIFT 类型。
VehicleType.GONDOLA_LIFT 空中缆车
VehicleType.FUNICULAR 一种由缆线拉上陡坡的交通工具。索道缆车通常由两辆车组成,每辆车充当另一台的平衡车。
VehicleType.OTHER 所有其他车辆都返回此类型。

检查 DirectionsResults

在解析任何路线响应时,都可以检查和使用 DirectionsResults 组件(DirectionsRouteDirectionsLegDirectionsStepTransitDetails)。

重要提示:如果您要手动呈现公交路线,而不是使用 DirectionsRenderer 对象,则必须显示提供行程结果的公交公司的名称和网址。

以下示例绘制了前往纽约市某些旅游景点的步行路线。我们会检查路线的 DirectionsStep,为各个路段添加标记,然后通过该路段的说明文本将信息附加到 InfoWindow

注意:由于我们计算的是步行路线,因此也会在单独的 <div> 面板中向用户显示任何警告。

var map;
var directionsRenderer;
var directionsService;
var stepDisplay;
var markerArray = [];

function initMap() {
  // Instantiate a directions service.
  directionsService = new google.maps.DirectionsService();

  // Create a map and center it on Manhattan.
  var manhattan = new google.maps.LatLng(40.7711329, -73.9741874);
  var mapOptions = {
    zoom: 13,
    center: manhattan
  }
  map = new google.maps.Map(document.getElementById('map'), mapOptions);

  // Create a renderer for directions and bind it to the map.
  var rendererOptions = {
    map: map
  }
  directionsRenderer = new google.maps.DirectionsRenderer(rendererOptions)

  // Instantiate an info window to hold step text.
  stepDisplay = new google.maps.InfoWindow();
}

function calcRoute() {

  // First, clear out any existing markerArray
  // from previous calculations.
  for (i = 0; i < markerArray.length; i++) {
    markerArray[i].setMap(null);
  }

  // Retrieve the start and end locations and create
  // a DirectionsRequest using WALKING directions.
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
      origin: start,
      destination: end,
      travelMode: 'WALKING'
  };

  // Route the directions and pass the response to a
  // function to create markers for each step.
  directionsService.route(request, function(response, status) {
    if (status == "OK") {
      var warnings = document.getElementById("warnings_panel");
      warnings.innerHTML = "" + response.routes[0].warnings + "";
      directionsRenderer.setDirections(response);
      showSteps(response);
    }
  });
}

function showSteps(directionResult) {
  // For each step, place a marker, and add the text to the marker's
  // info window. Also attach the marker to an array so we
  // can keep track of it and remove it when calculating new
  // routes.
  var myRoute = directionResult.routes[0].legs[0];

  for (var i = 0; i < myRoute.steps.length; i++) {
      var marker = new google.maps.Marker({
        position: myRoute.steps[i].start_point,
        map: map
      });
      attachInstructionText(marker, myRoute.steps[i].instructions);
      markerArray[i] = marker;
  }
}

function attachInstructionText(marker, text) {
  google.maps.event.addListener(marker, 'click', function() {
    stepDisplay.setContent(text);
    stepDisplay.open(map, marker);
  });
}

在 HTML 正文中:

<div>
<strong>Start: </strong>
<select id="start">
  <option value="penn station, new york, ny">Penn Station</option>
  <option value="grand central station, new york, ny">Grand Central Station</option>
  <option value="625 8th Avenue New York NY 10018">Port Authority Bus Terminal</option>
  <option value="staten island ferry terminal, new york, ny">Staten Island Ferry Terminal</option>
  <option value="101 E 125th Street, New York, NY">Harlem - 125th St Station</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="260 Broadway New York NY 10007">City Hall</option>
  <option value="W 49th St & 5th Ave, New York, NY 10020">Rockefeller Center</option>
  <option value="moma, New York, NY">MOMA</option>
  <option value="350 5th Ave, New York, NY, 10118">Empire State Building</option>
  <option value="253 West 125th Street, New York, NY">Apollo Theatre</option>
  <option value="1 Wall St, New York, NY">Wall St</option>
</select>
<div>

查看示例

在路线中使用路径点

DirectionsRequest 中所述,您也可以在使用路线服务计算步行、骑车或行车路线时指定航点(类型为 DirectionsWaypoint)。航点不适用于公交路线。航点可让您通过其他位置计算路线,在这种情况下,返回的路线会经过指定的航点。

waypoint 包含以下字段:

  • location(必需)指定航点的地址。
  • stopover(可选)表示此航点是路线上的实际站点 (true),还是仅为通过指定位置 (false) 的路线首选项。默认情况下,中途停留点为 true

默认情况下,路线服务会按所提供航点的指定顺序计算经过这些航点的路线。或者,您也可以在 DirectionsRequest 中传递 optimizeWaypoints: true,以便路线服务以更高效的顺序重新排列这些航点,从而优化提供的路线。(此优化用于解决旅行推销员问题。)行程时间是经过优化的主要因素,但在决定哪个路线最高效时,可能要考虑距离、转弯次数和许多其他因素。所有航点都必须中途停留,以便路线服务优化它们的路线。

如果您指示路线服务对航点的顺序进行优化,那么该顺序将在 DirectionsResult 对象内的 waypoint_order 字段中返回。

以下示例使用各种起点、终点和航点来计算跨美国的跨国家/地区路线。(要选择多个航点,请在选择列表项时按住 Ctrl 键并点击。) 请注意,我们会检查 routes.start_addressroutes.end_address,以向我们提供每个路线的起点和终点的文本。

TypeScript

function initMap(): void {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 6,
      center: { lat: 41.85, lng: -87.65 },
    }
  );

  directionsRenderer.setMap(map);

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      calculateAndDisplayRoute(directionsService, directionsRenderer);
    }
  );
}

function calculateAndDisplayRoute(
  directionsService: google.maps.DirectionsService,
  directionsRenderer: google.maps.DirectionsRenderer
) {
  const waypts: google.maps.DirectionsWaypoint[] = [];
  const checkboxArray = document.getElementById(
    "waypoints"
  ) as HTMLSelectElement;

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: (checkboxArray[i] as HTMLOptionElement).value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: (document.getElementById("start") as HTMLInputElement).value,
      destination: (document.getElementById("end") as HTMLInputElement).value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById(
        "directions-panel"
      ) as HTMLElement;

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const routeSegment = i + 1;

        summaryPanel.innerHTML +=
          "<b>Route Segment: " + routeSegment + "</b><br>";
        summaryPanel.innerHTML += route.legs[i].start_address + " to ";
        summaryPanel.innerHTML += route.legs[i].end_address + "<br>";
        summaryPanel.innerHTML += route.legs[i].distance!.text + "<br><br>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

function initMap() {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 6,
    center: { lat: 41.85, lng: -87.65 },
  });

  directionsRenderer.setMap(map);
  document.getElementById("submit").addEventListener("click", () => {
    calculateAndDisplayRoute(directionsService, directionsRenderer);
  });
}

function calculateAndDisplayRoute(directionsService, directionsRenderer) {
  const waypts = [];
  const checkboxArray = document.getElementById("waypoints");

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: checkboxArray[i].value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: document.getElementById("start").value,
      destination: document.getElementById("end").value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById("directions-panel");

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const routeSegment = i + 1;

        summaryPanel.innerHTML +=
          "<b>Route Segment: " + routeSegment + "</b><br>";
        summaryPanel.innerHTML += route.legs[i].start_address + " to ";
        summaryPanel.innerHTML += route.legs[i].end_address + "<br>";
        summaryPanel.innerHTML += route.legs[i].distance.text + "<br><br>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

window.initMap = initMap;

路径点的限额和限制

执行以下使用限额和限制:

  • 在 Maps JavaScript API 中使用路线服务时,允许的航点数上限为 25,再加上起点和目的地。Directions API 网络服务的限制也相同。
  • 对于 Directions API 网络服务,客户可以使用 25 个航点,外加出发地和目的地。
  • Google Maps Platform 高级计划客户可使用 25 个航点,外加出发地和目的地。
  • 公共交通路线不支持路径点。

可拖动方向

如果地图为可拖动方式,用户可以通过点击并拖动地图上的结果路径来选择和更改路线,用户可以使用DirectionsRenderer动态地修改骑车、步行或驾车路线。 要表示渲染程序允许显示可拖动路线,请将该程序的 draggable 属性设置为 true。公共交通路线无法设为可拖动。

当路线可以拖动时,用户可以选择所呈现结果的路径上的任意点(或航点),然后将指示的组件移至新位置。系统会动态更新 DirectionsRenderer,以显示修改后的路径。松开鼠标后,系统会向地图添加一个过渡航点(由小白色标记表示)。选择并移动路径段会更改路线的该路程,而选择并移动航点标记(包括起点和终点)将会更改经过该航点的路线的路程。

由于可拖动路线是在客户端进行修改和呈现的,因此您可能需要监控并处理 DirectionsRenderer 上的 directions_changed 事件,以便在用户修改了显示的路线时收到通知。

以下代码显示了从澳大利亚西海岸的珀斯到东海岸悉尼的行程。该代码会监控 directions_changed 事件,以便更新该行程的全部路程的总距离。

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -24.345, lng: 134.46 }, // Australia.
    }
  );

  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel") as HTMLElement,
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });

  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer
  );
}

function displayRoute(
  origin: string,
  destination: string,
  service: google.maps.DirectionsService,
  display: google.maps.DirectionsRenderer
) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result: google.maps.DirectionsResult) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result: google.maps.DirectionsResult) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i]!.distance!.value;
  }

  total = total / 1000;
  (document.getElementById("total") as HTMLElement).innerHTML = total + " km";
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -24.345, lng: 134.46 }, // Australia.
  });
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel"),
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });
  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer
  );
}

function displayRoute(origin, destination, service, display) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i].distance.value;
  }

  total = total / 1000;
  document.getElementById("total").innerHTML = total + " km";
}

window.initMap = initMap;
查看示例

试用示例