路线服务

概览

您可以使用 DirectionsService 对象来计算（使用各种交通方式时的）路线。此对象与 Google Maps API Directions Service 通信，后者接收路线请求并返回计算得出的结果。您可以自行处理这些路线结果，也可以使用 DirectionsRenderer 对象呈现这些结果。

在路线请求中指定路线的起点或终点时，您可以指定查询字符串（例如，“伊利诺斯州芝加哥市”或“澳大利亚新南威尔士州达尔文市”）、LatLng 值或 google.maps.Place 对象。

“路线”服务可使用一系列路径点返回多段式路线。路线可以折线形式绘制在地图上，或者，还以一系列文本描述显示在 <div> 元素内（例如“右转上中山南路”）。

路线请求

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

要使用 Google 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,
  avoidHighways: Boolean,
  avoidTolls: Boolean,
  region: String
}

这些字段解释如下：

• origin（必填）：用于指定计算路线时所用的起始地点。该值可以指定为 String（例如“伊利诺斯州芝加哥市”）、LatLng 值或 google.maps.Place 对象。如果使用 google.maps.Place 对象，您可以指定一个地点 ID、一个查询字符串或一个 LatLng 地点。您可以从 Google Maps JavaScript API 中的地理编码服务、地点搜索服务和地点自动完成服务检索地点 ID。如需查看使用来自“地点自动完成”的地点 ID 的示例，请参阅地点自动完成和路线。
• destination（必填）：用于指定计算路线时所用的结束地点。其选项与上面所述 origin 字段的选项相同
• travelMode（必填）：用于指定计算路线时所用的交通方式。有效值见下文出行方式部分所述
• transitOptions（可选）：用于指定仅适用于其中 travelMode 为 google.maps.TravelMode.TRANSIT 的请求的值。有效值见下文公交选项部分所述
• drivingOptions（可选）：用于指定仅适用于其中 travelMode 为 google.maps.TravelMode.DRIVING 的请求的值。有效值见下文行车选项部分所述

• unitSystem（可选）：用于指定显示结果时所用的单位制。有效值见下文单位制部分所述

• waypoints[]（可选）：用于指定 DirectionsWaypoint 数组。路径点通过使路线经过指定位置来改变路线。您可将路径点指定为带有如下所示字段的一个对象字面量：

  • location：用于以 LatLng、google.maps.Place 对象或将进行地理编码的 String 形式指定路径点位置
  • stopover：一个布尔值，表示路径点是路线上的一个停留点，可将路线一分为二

  （如需了解有关路径点的详细信息，请参阅下文的在路线中使用路径点。）

• optimizeWaypoints（可选）：用于指明可对使用提供的 waypoints 的路线进行优化，以提供尽可能最短的路线。如果该值设置为 true，那么“路线”服务将在 waypoint_order 字段中返回重新排序的 waypoints。（有关详细信息，请参阅下文在路线中使用路径点部分。）
• provideRouteAlternatives（可选）：设置为 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: google.maps.TravelMode.DRIVING,
  drivingOptions: {
    departureTime: new Date(/* now, or future date */),
    trafficModel: google.maps.TrafficModel.PESSIMISTIC
  }
  unitSystem: UnitSystem.IMPERIAL
}

出行模式

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

• google.maps.TravelMode.DRIVING（默认）：表示使用道路网络的标准行车路线
• google.maps.TravelMode.BICYCLING：用于请求经过骑行道和优先街道的骑行路线
• google.maps.TravelMode.TRANSIT：用于请求经过公交路线的路线
• google.maps.TravelMode.WALKING：用于请求经过步行街和人行道的步行路线

请查阅 Google Maps 覆盖范围数据，确定某个国家/地区支持的路线范围。如果您对该路线类型不适用的区域请求路线，响应将会返回 DirectionsStatus="ZERO_RESULTS"。

步行路线有时可能不包含畅通无阻的步道，因此，如果您未使用默认的 DirectionsRenderer，那么步行路线将会在您应显示的 DirectionsResult 中返回警告。

公交选项

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

适用于某一路线请求的选项会根据出行方式的不同而有所区别。请求公交路线时，将会忽略 avoidHighways、avoidTolls、waypoints[] 和 optimizeWaypoints 选项。您可以通过 TransitOptions 对象字面量指定公交专属路线选项。

公交路线具有时效性。只有对于未来的时间才会返回路线。

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

{
  arrivalTime: Date,
  departureTime: Date,
  modes[]: TransitMode,
  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：表示计算的路线应首选有限的步行距离

下面是针对公交方式的 DirectionsRequest 示例：

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

行车选项

您可以通过 DrivingOptions 对象指定行车路线的行程选项。如果您想在 DirectionsRequest 中包含 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 应短于大多数日子里的实际行程时间，尽管交通状况特别好的少数日子里的行程时间可能小于此值

下面是针对行车路线的 DirectionsRequest 示例：

{
  origin: "Chicago, IL",
  destination: "Los Angeles, CA",
  travelMode: google.maps.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 Directions Service 返回的地址结果受到您从中载入 JavaScript 引导程序的域（国家或地区）的影响。（由于大多数用户都会加载 https://maps.google.com/，因此对于美国用户而言，这就设置了一个隐式域。）如果您是从其他的支持域加载该引导程序的，那么所获得的结果将会受到该域的影响。例如，搜索“San Francisco”时，加载 https://maps.google.com/（美国）的应用与加载 http://maps.google.es/（西班牙）的应用可能会返回不同的结果。

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

请查阅 Google Maps 覆盖范围数据，确定某个国家/地区支持的路线范围。

呈现路线

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

路线查询状态

DirectionsStatus 可能会返回以下值：

• OK：表示响应包含一个有效的 DirectionsResult
• NOT_FOUND 表示请求的起点、目的地或路径点中指定的至少其中一个位置无法接受地理编码。
• ZERO_RESULTS 表示在起点与目的地之间未找到路线。
• MAX_WAYPOINTS_EXCEEDED：表示 DirectionsRequest 中提供的 DirectionsWaypoint 过多。允许的路径点数目上限为 8 个，另加起点和终点。Google Maps API for Work 客户可使用 23 个路径点，另加起点和终点。公交路线不支持路径点。
• 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 处理指定位置之间折线的显示，并将标记放在起点、终点和所有路径点（如适用）上。

var directionsDisplay;
var directionsService = new google.maps.DirectionsService();
var map;

function initialize() {
  directionsDisplay = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  map = new google.maps.Map(document.getElementById("map"), mapOptions);
  directionsDisplay.setMap(map);
}

function calcRoute() {
  var start = document.getElementById("start").value;
  var end = document.getElementById("end").value;
  var request = {
    origin:start,
    destination:end,
    travelMode: google.maps.TravelMode.DRIVING
  };
  directionsService.route(request, function(result, status) {
    if (status == google.maps.DirectionsStatus.OK) {
      directionsDisplay.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>

查看示例 (directions-simple.html)

下例显示了从美国加州旧金山的海特-黑什伯里区到海滩之间使用不同出行方式的路线：

var directionsDisplay;
var directionsService = new google.maps.DirectionsService();
var map;
var haight = new google.maps.LatLng(37.7699298, -122.4469157);
var oceanBeach = new google.maps.LatLng(37.7683909618184, -122.51089453697205);

function initialize() {
  directionsDisplay = new google.maps.DirectionsRenderer();
  var mapOptions = {
    zoom: 14,
    center: haight
  }
  map = new google.maps.Map(document.getElementById("map"), mapOptions);
  directionsDisplay.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 == google.maps.DirectionsStatus.OK) {
      directionsDisplay.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>

查看示例 (directions-travel-modes.html)

DirectionsRenderer 不仅处理折线和任何关联标记的显示，也可以处理以文本形式将路线显示为一系列路段。为此，您只需对 DirectionsRenderer 调用 setPanel()，向其传递 <div>（用于显示此信息）。这样做还可确保显示相应的版权信息，以及可能与该结果相关联的任何警告。

该服务将使用浏览器的首选语言设置或在加载 API JavaScript 时使用 language 参数所指定的语言来提供文本路线。（如需了解详细信息，请参阅本地化。）对于公交路线，将按照相应公交站点所在的时区显示时间。

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

var directionsDisplay;
var directionsService = new google.maps.DirectionsService();
var map;

function initialize() {
  directionsDisplay = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  map = new google.maps.Map(document.getElementById("map"), mapOptions);
  directionsDisplay.setMap(map);
  directionsDisplay.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: google.maps.TravelMode.DRIVING
  };
  directionsService.route(request, function(response, status) {
    if (status == google.maps.DirectionsStatus.OK) {
      directionsDisplay.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>

查看示例 (directions-panel.html)

DirectionsResult 对象

向 DirectionsService 发送路线请求后，您会收到一个包含状态代码和结果（即 DirectionsResult 对象）的响应。DirectionsResult 是一个带有以下字段的对象字面量：

• geocoded_waypoints[]：包含一个 DirectionsGeocodedWaypoint 对象数组，其中每个对象均包含有关起点、终点和路径点的地理编码详情
• routes[]：包含一个 DirectionsRoute 对象数组。每条路线均表示一种从 DirectionsRequest 中所提供的起点到终点的方式。通常，对于任何给定请求，均只会返回一条路线，除非请求的 provideRouteAlternatives 字段设置为 true（此情况下，可能会返回多条路线）

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

DirectionsGeocodedWaypoint 包含有关起点、终点和路径点的地理编码详情。

DirectionsGeocodedWaypoint 是一个带有以下字段的对象字面量：

• geocoder_status：表示地理编码操作所产生的状态代码。此字段可能包含以下值：
  • "OK" 表示未出现任何错误；已成功解析地址，并且至少返回了一个地理编码。
  • "ZERO_RESULTS" 表示地理编码成功，但未返回任何结果。如果向地理编码器传递了一个不存在 address，就可能会发生这种情况。

• partial_match 表示虽然地理编码器能够匹配所请求的地址的一部分，但它未能返回原始请求的精确匹配项。您不妨检查一下原始请求中是否有拼写错误和/或地址不完整的情况。

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

• place_id：是地点的唯一标识符，可与其他 Google API 结合使用。例如，您可以将 place_id 与Google Places API 库结合使用，以获取某家当地商家的详细信息，例如电话号码、营业时间、用户评价及更多信息。请参阅地点 ID 概览。
• types[]：是一个表示所返回结果的类型 的数组。此数组包含一组标记（可能为零个或多个），用于标识结果中所返回特征的类型。例如，“芝加哥”的地理编码返回“locality”，这表明“芝加哥”是一个城市，并且还返回“political”，这表明它是一个政治实体。

路线

旧版的 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：其中包含此路线的总交通费用（即总票价）。此属性只针对公交请求返回，且仅适用于所有公交路程均有票价信息的路线。这些信息包括：
  • currency：ISO 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 仅返回给符合以下要求的 Google Maps API for Work 客户：交通数据可用；mode 设置为 driving；departureTime 作为 drivingOptions 字段的一部分包含在请求中。duration_in_traffic 包含以下字段：

  • value：表示持续时间（以秒为单位）
  • text：其中包含以可人工读取形式表示的持续时间
• arrival_time：其中包含此路程的预计到达时间。该属性只针对公交路线返回。结果以 Time 对象形式返回，具有以下三个属性：
  • value：以 JavaScript Date 对象指定的时间
  • text：以字符串形式指定的时间。时间以公共交通车站的时区显示。
  • time_zone 包含该站的时区。该值就是 IANA 时区数据库中定义的时区名称，例如“America/New_York”
• departure_time：其中包含以 Time 对象指定的此路程的预计出发时间。只会为公共交通路线提供 departure_time。
• start_location：其中包含以 LatLng 形式表示的此路程起点。由于路线 Web 服务会使用距起点和终点最近的交通选项（通常为道路）计算不同位置间的路线，因此，start_location 可能与为该路程提供的起点不同，例如，如果道路不靠近起点，这两个值就有所不同
• end_location：其中包含以 LatLng 形式表示的此路程终点。由于 DirectionsService 会使用距起点和终点最近的交通选项（通常为道路）计算不同位置间的路线，因此end_location 可能与为该路程提供的终点不同，例如，如果道路不靠近终点，这两个值就有所不同
• start_address：其中包含以可人工读取形式表示的该路程起点地址（通常为街道地址）
• end_address：其中包含以可人工读取形式表示的该路程终点地址（通常为街道地址）

路线路段

DirectionsStep 是路线中的最小单元，其中包含用于介绍相应行程中某个特定指示的单个路段。例如：“在西四街左转”。这个路段不仅介绍指示，同时也包含有关此路段到下个路段的距离和持续时间信息。例如，一个以“并入 I-80 West”表示的路段可能包含距离“37 英里”和持续时间“40 分钟”这些信息，指示下一个路段距离此路段有 37 英里/40 分钟。

使用“路线”服务搜索公交路线时，路段数组会以 transit 对象形式包含其他公交专属信息。如果路线包含多种交通方式，那么将在 steps[] 数组中提供针对步行或行车路段的详细路线。例如，步行分段将包括从开始位置和结束位置开始的路线：“步行前往 Innes Ave & Fitch St”。该路段会在 steps[] 数组中包含上述路线的详细步行路线，例如：“朝西北方向走”、“左转进入 Arelious Walker”和“左转进入 Innes Ave”。

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

• instructions：其中包含以文本字符串表示的该路段相关说明
• distance：其中包含该路段与下一个路段之间的距离，以 Distance 对象表示。（请参阅上面 DirectionsLeg 中的说明。）如果距离未知，那么此字段可能未定义
• duration：其中包含走完此路段到达下一个路段预计所需的时间，以 Duration 对象表示。（请参阅上面 DirectionsLeg 中的说明。）如果持续时间未知，该字段可能处于未定义状态。
• start_location：其中包含以经过地理编码的 LatLng 形式表示的此路段起点
• end_location：其中包含以 LatLng 形式表示的此路段终点
• polyline：其中包含一个 points 对象，用于储存以经过编码的折线形式表示的路段。该多段线是分段的近似（平滑）路径。
• steps[]：一个 DirectionsStep 对象字面量，其中包含公交路线中步行或行车路段的详细路线。子路段只适用于公交路线
• travel_mode：其中包含此路段中使用的 TravelMode。公交路线中可包含步行路线与公交路线的组合
• path：其中包含 LatLngs 数组，用于描述此路段的路程
• transit：其中包含公交专属信息，例如出发和到达时间以及公交线路的名称

公交专属信息

公共交通路线返回与其他交通模式无关的附加信息。这些额外属性是通过 TransitDetails 对象展示的，并作为 DirectionsStep 的属性返回。通过 TransitDetails 对象，您可以访问如下所述的 TransitStop、TransitLine、TransitAgency 和 VehicleType 的更多信息。

公交详情

TransitDetails 对象显示以下属性：

• arrival_stop：其中包含表示到达站点的 TransitStop 对象，具有以下属性：
  • name，公共交通车站的名称，例如：“联合广场”
  • location：公交站点的位置，以 LatLng 表示。
• departure_stop：其中包含表示出发站点的TransitStop 对象
• arrival_time：其中包含以 Time 对象指定的到达时间，具有以下三个属性：
  • value：以 JavaScript Date 对象指定的时间
  • text：以字符串形式指定的时间。时间以公共交通车站的时区显示。
  • time_zone 包含该站的时区。该值就是 IANA 时区数据库中定义的时区名称，例如“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”或“M 14”
• agencies：其中包含 TransitAgency 类型数组。每个 TransitAgency 对象均提供此线路运营商的相关信息，其中包含以下属性：
  • name：其中包含公交机构的名称
  • url：其中包含公交机构的 URL
  • phone 包含公共交通运营机构的电话号码

  如果您要手动呈现公交路线，而不是使用 DirectionsRenderer 对象，则必须显示提供行程结果的公交机构的名称和 URL。

• url：其中包含由公交机构提供的该公交线路的 URL
• icon：其中包含与该线路相关联的图标的 URL。大多数城市都会使用因交通工具类型而异的通用图标。某些公交线路（例如纽约地铁系统）具有该线路专用的图标
• color：其中包含该公交线路站牌上常用的颜色。颜色以十六进制字符串形式指定，例如：#FF0033
• text_color：其中包含该线路站牌上常用的文字颜色。颜色以十六进制字符串形式指定
• vehicle：其中包含 Vehicle 对象，具有以下属性：
  • name：其中包含该线路上交通工具的名称。例如：“地铁”。
  • type：其中包含该线路所用交通工具的类型。有关受支持值的完整列表，请参阅交通工具类型文档
  • icon：其中包含通常与该交通工具类型相关联的图标的 URL
  • local_ icon：其中包含与该交通工具类型本地关联的图标的 URL

交通工具类型

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 组件，其中包括：DirectionsRoute、DirectionsLeg、DirectionsStep 和 TransitDetails。

重要说明：如果您要手动呈现公交路线，而不是使用 DirectionsRenderer 对象，则必须显示提供行程结果的公交机构的名称和 URL。

下例绘制了到纽约市某些游览胜地的步行路线。我们会检查路线的 DirectionsStep，以便为各个路段添加标记，然后通过该路段的说明文本将信息附加到 InfoWindow。

由于我们要计算的是步行路线，因此还会在一个独立 <div> 面板中向用户显示任何警告。

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

function initialize() {
  // 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
  }
  directionsDisplay = 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: google.maps.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 == google.maps.DirectionsStatus.OK) {
      var warnings = document.getElementById("warnings_panel");
      warnings.innerHTML = "" + response.routes[0].warnings + "";
      directionsDisplay.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>

查看示例 (directions-complex.html)

在路线中使用路径点

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

允许的路径点数目上限为 8 个，另加起点和终点。Google Maps API for Work 客户可使用 23 个路径点，另加起点和终点。公交路线不支持路径点。

waypoint 包含以下字段：

• location（必填）：用于指定路径点的地址
• stopover（可选）：用于表示此路径点是路线上的实际停靠点 (true)，还是只是通过指定位置的路线首选项 (false)。停靠点默认设置为 true

默认情况下，“路线”服务会按所提供路径点的给定顺序计算经过这些路径点的路线。或者，您也可以在 DirectionsRequest 中传递 optimizeWaypoints: true，以便让“路线”服务能够以更有效的顺序重新排列这些路径点，从而对提供的路线进行优化。（此优化用于求解旅行推销员问题。）所有路径点都必须是停靠点，以便“路线”服务优化它们的路线。

如果您指示“路线”服务对路径点的顺序进行优化，那么它将在 DirectionsResult 对象中的 waypoint_order 字段内返回优化后的顺序。

下例使用各种起点、终点和路径点计算横跨美国的越野路线。（要选择多个路径点，请按住 Ctrl 并点击选择列表中的相应项目。）请注意，我们会对分别为各条路线起点和终点提供文本的 routes.start_address 和 routes.end_address 进行检查。

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

  document.getElementById('submit').addEventListener('click', function() {
    calculateAndDisplayRoute(directionsService, directionsDisplay);
  });
}

function calculateAndDisplayRoute(directionsService, directionsDisplay) {
  var waypts = [];
  var checkboxArray = document.getElementById('waypoints');
  for (var 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
  }, function(response, status) {
    if (status === google.maps.DirectionsStatus.OK) {
      directionsDisplay.setDirections(response);
      var route = response.routes[0];
      var summaryPanel = document.getElementById('directions-panel');
      summaryPanel.innerHTML = '';
      // For each route, display summary information.
      for (var i = 0; i < route.legs.length; i++) {
        var 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>';
      }
    } else {
      window.alert('Directions request failed due to ' + status);
    }
  });
}

查看示例 (directions-waypoints.html)。

可拖动方向

如果显示的骑行、步行或行车路线可以拖动，用户就可以使用 DirectionsRenderer 动态修改该路线：用户只需点击并拖动地图上的结果路径，即可选择和更改路线。要表示呈现程序允许显示可拖动路线，请将该程序的 draggable 属性设置为 true。公交路线无法设为可拖动。

如果路线可以拖动，那么用户可以选中所呈现结果的路径上的任意点（或路径点），然后将指示的部分移动到新的位置。系统会动态更新 DirectionsRenderer，以显示修改后的路径。松开鼠标后，系统会向地图添加一个过渡路径点（以一个白色小标记表示）。选中并移动某段路径将会更改该路线的路程，而选中并移动路径点标记（包括起点和终点）将会更改经过该路径点的路线的路程。

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

以下代码显示了从悉尼到新南威尔士州内地的往返行程。该代码会监控 directions_changed 事件，以便更新该行程的全部路程的总距离。

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

  var directionsService = new google.maps.DirectionsService;
  var directionsDisplay = new google.maps.DirectionsRenderer({
    draggable: true,
    map: map,
    panel: document.getElementById('right-panel')
  });

  directionsDisplay.addListener('directions_changed', function() {
    computeTotalDistance(directionsDisplay.getDirections());
  });

  displayRoute('Perth, WA', 'Sydney, NSW', directionsService,
      directionsDisplay);
}

function displayRoute(origin, destination, service, display) {
  service.route({
    origin: origin,
    destination: destination,
    waypoints: [{location: 'Cocklebiddy, WA'}, {location: 'Broken Hill, NSW'}],
    travelMode: google.maps.TravelMode.DRIVING,
    avoidTolls: true
  }, function(response, status) {
    if (status === google.maps.DirectionsStatus.OK) {
      display.setDirections(response);
    } else {
      alert('Could not display directions due to: ' + status);
    }
  });
}

function computeTotalDistance(result) {
  var total = 0;
  var myroute = result.routes[0];
  for (var i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i].distance.value;
  }
  total = total / 1000;
  document.getElementById('total').innerHTML = total + ' km';
}

查看示例 (directions-draggable.html)。