Google Maps API V3 之 路线服务

时间:2024-04-16 10:38:16

Google官方教程:

Google 地图 API V3 使用入门

Google 地图 API V3 针对移动设备进行开发

Google 地图 API V3 之事件

Google 地图 API V3 之控件

Google 地图 API V3 之 叠加层

Google Maps API V3 之绘图库 信息窗口

Google Maps API V3 之 图层

Google Maps API V3 之 路线服务

概述

您可以使用 DirectionsService 对象计算路线(使用各种交通方式)。此对象与 Google Maps API 路线服务进行通信,该服务会接收路线请求并返回计算的结果。您可以自行处理这些路线结果,也可以使用 DirectionsRenderer 对象呈现这些结果。

您可以通过文本字符串(例如,“伊利诺斯州芝加哥市”或“澳大利亚新南威尔士州达尔文市”)或 LatLng 值的形式来指定路线的起点和终点。路线服务可以使用一系列路标返回多段路线。路线可以显示为一条在地图上绘制路线的折线,此外,也可以显示为 <div> 元素中的一些文字说明(例如,“右转上中山南路”)。

路线请求

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

要在 V3 中使用路线,请创建一个类型为 DirectionsService 的对象,并调用 DirectionsService.route() 向路线服务发起请求,同时向其传递一个 DirectionsRequest 对象常量(其中包含输入字词和一个用于在收到响应后执行的回调方法)。

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

{
  origin: LatLng | String,
  destination: LatLng | String,
  travelMode: TravelMode,
  transitOptions: TransitOptions,
  unitSystem: UnitSystem,
  waypoints[]: DirectionsWaypoint,
  optimizeWaypoints: Boolean,
  provideRouteAlternatives: Boolean,
  avoidHighways: Boolean,
  avoidTolls: Boolean
  region: String
}

下面对这些字段进行了说明:

  • origin(必填),用于指定计算路线时所用的起始地点。该值可以指定为 String(例如“伊利诺斯州芝加哥市”),也可以指定为 LatLng 值。
  • destination(必填),用于指定计算路线时所用的结束地点。该值可以指定为 String(例如“伊利诺斯州芝加哥市”),也可以指定为 LatLng 值。
  • travelMode(必填),用于指定计算路线时所用的交通方式。下面的出行方式中指明了有效值。
  • transitOptions(可选),用于指定仅适用于其中 travelMode 为 google.maps.TravelMode.TRANSIT 的请求的值。下面的公交选项中说明了有效值。
  • unitSystem(可选),用于指定显示结果时所用的单位制。您可在下面的单位制中指定有效的值。

  • waypoints[](可选),用于指定 DirectionsWaypoint 数组。路标可使路线经过指定地点,从而更改路线。您可将路标指定为带有如下字段的一个对象常量:

    • location,用于以 LatLng 或要进行地理编码的 String 的形式指定路标的位置。
    • stopover(布尔值),用于表示路标是否为路线上的车站(可将该路线一分为二)。

    (有关路标的详情,请参阅下面的在路线中使用路标。)

  • optimizeWaypoints(可选),用于指定可对使用提供的 waypoints 的路线进行优化,以提供尽可能最短的路线。如果该值为 true,那么路线服务将在 waypoints 字段中返回重新排序的 waypoint_order。(有关详情,请参阅下面的在路线中使用路标。)
  • 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: TravelMode.DRIVING,
  unitSystem: UnitSystem.IMPERIAL
}

出行方式

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

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

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

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

公交选项

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

适用于某一路线请求的选项会根据出行方式的不同而有所区别。在请求公交路线时,将会忽略 avoidHighwaysavoidTollswaypoints[] 和 optimizeWaypoints 选项。您可以通过 TransitOptions 对象常量指定专门针对公交的路线选项。

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

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

{
  departureTime: Date,
  arrivalTime: Date
}

下面对这些字段进行了说明:

  • departureTime(可选),用于以 Date 对象的形式指定期望出发时间。如果指定了 arrivalTime,就会忽略 departureTime。如果未对 departureTime 或 arrivalTime 指定任何值,则默认采用当前时间。
  • arrivalTime(可选),用于以 Date 对象的形式指定期望到达时间。如果指定了到达时间,就会忽略出发时间。

公交 DirectionsRequest 的示例如下所示:

{
  origin: "Hoboken NJ",
  destination: "Carroll Gardens, *lyn",
  travelMode: google.maps.TravelMode.TRANSIT,
  transitOptions: {
    departureTime: new Date(1337675679473)
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

单位制

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

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

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

路线的区域偏向

Google Maps API Directions Service 将返回受到您从中载入 JavaScript 启动的域(区域或国家/地区)影响的地址结果。(由于大多数用户都会加载http://maps.google.com/,因此对于美国用户而言,这就设置了一个隐式域。)如果您是从其他的支持域加载该引导程序的,那么所获得的结果将会受到该域的影响。例如,当加载 http://maps.google.com/(美国)与加载 http://maps.google.es/(西班牙)时,搜索“San Francisco”可能会从应用返回不同的结果。

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

请查阅 Google 地图覆盖范围电子表格,确定某个国家/地址支持的路线范围。

呈现路线

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

路线查询状态

DirectionsStatus 可能会返回以下值:

  • OK,用于表示相关响应包含一个有效的 DirectionsResult
  • NOT_FOUND,用于表示请求的起点、终点或路标中指定的至少一个位置无法进行地理编码。
  • ZERO_RESULTS,用于表示在起点和终点之间找不到路线。
  • MAX_WAYPOINTS_EXCEEDED,用于表示 DirectionsRequest 中提供的 DirectionsWaypoint 过多。允许的路标数目上限为 8 个,此外还包括起点和终点。Maps API for Business 客户可使用 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,
    mapTypeId: google.maps.MapTypeId.ROADMAP,
    center: chicago
  }
  map = new google.maps.Map(document.getElementById("map_canvas"), 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>

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

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,
    mapTypeId: google.maps.MapTypeId.ROADMAP,
    center: haight
  }
  map = new google.maps.Map(document.getElementById("map_canvas"), 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>

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,
    mapTypeId: google.maps.MapTypeId.ROADMAP,
    center: chicago
  }
  map = new google.maps.Map(document.getElementById("map_canvas"), 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_canvas" style="float:left;width:70%; height:100%"></div>
<div id="directionsPanel" style="float:right;width:30%;height 100%"></div>

DirectionsResult 对象

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

  • routes[] 包含一个 DirectionsRoute 对象数组。每条路线均表示一种从起点到终点(DirectionsRequest 中所提供)的方式。通常,除非请求的 provideRouteAlternatives 字段设为 true(在这种情况下,可能会返回多条路线),否则,该服务只会针对所有给定请求返回一条路线。

路线

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

DirectionsRoute 包含一个从指定起点到指定终点的结果。该路线可包含一段或多段路程(类型为 DirectionsLeg),具体取决于是否指定了任何路标。除路线信息外,该路线还包含了必须向用户显示的版权和警告信息。

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

  • legs[],其中包含一组 DirectionsLeg 对象,每个该对象均包含关于路线的一段路程(介于给定路线中的两个位置之间)的信息。系统将会针对每个指定的路标或终点显示一段单独的路程(没有任何路标的路线将仅包含一个 DirectionsLeg)。每段路程均由一系列 DirectionStep 组成
  • waypoint_order,其中包含一个数组,该数组用于表示计算的路线中所有路标的顺序。如果已向 DirectionsRequest 传递了 optimizeWaypoints: true,那么此数组可能会包含经过更改的顺序。
  • overview_path,其中包含一组 LatLng,用于表示所生成路线的近似(平滑)路径。
  • bounds,其中包含一个 LatLngBounds,用于表示沿着此给定路线的折线的边界。
  • copyrights,其中包含要为该路线显示的版权文本。如果您不使用提供的 DirectionsRenderer 对象,那么必须自行处理和显示此信息。
  • warnings[],其中包含要在显示这些路线时显示的一组警告。如果您不使用提供的 DirectionsRenderer 对象,那么必须自行处理和显示这些警告。

路线路程

旧版的 DirectionsRoute 对象已重命名为 DirectionsLeg

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

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

  • steps[],其中包含 DirectionsStep 对象数组,这些对象用于表示关于行程路程的各单独路段的信息。
  • distance,用于通过采用以下形式的 Distance 对象来表示该路程包含的总距离:

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

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

  • duration,用于通过采用以下形式的 Duration 对象来表示该路程的总持续时间:

    • value,用于表示持续时间(以秒为单位)。
    • text,其中包含以字符串形式表示的持续时间。

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

  • arrival_time,其中包含此路程的预计到达时间。该属性只针对公交路线返回。返回的结果采用 Time 对象的形式,其中包含以下 3 个属性:
    • value,以 JavaScript Date 对象形式指定的时间。
    • text,以字符串形式指定的时间。时间按照相关公交站点所在的时区来显示。
    • time_zone,其中包含该站点的时区。该值就是 IANA 时区数据库中定义的时区名称,例如“America/New_York”。
  • departure_time,其中包含以 Time 对象形式指定的此路程的预计出发时间。departure_time 只适用于公交路线。
  • start_location,其中包含该路程起点的 LatLng。由于路线网络服务会使用距起点和终点最近的交通选项(通常为道路)计算不同位置间的路线,因此在道路不靠近该路程提供的起点等情况下,start_location 可能与该起点不同。
  • end_location,其中包含该路程终点的 LatLng。由于 DirectionsService 会使用距起点和终点最近的交通选项(通常为道路)计算不同位置间的路线,因此在道路不靠近该路程提供的终点等情况下,end_location 可能与该终点不同。
  • start_address,其中包含便于用户理解的该路程起点地址(通常为街道地址)。
  • end_address,其中包含便于用户理解的该路程终点地址(通常为街道地址)。

路线路段

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

使用路线服务搜索公交路线时,路段数组中会另外包含 transit 对象形式的专门针对公交的信息。如果路线包含多种交通方式,那么针对步行或行车路段的详细路线将在steps[] 数组中提供。例如,某个步行路段会包含从起点和终点位置开始的路线:“步行至中山路和人民路”。该路段会在 steps[] 数组中包含上述路线的详细步行路线,例如:“向西北方向走”、“左转上解放路”和“左转上中山路”。

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

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

专门针对公交的信息

公交路线会返回与其他交通方式无关的额外信息。这些额外属性是通过 TransitDetails 对象展示的,返回的形式为 DirectionsStep 的属性。通过 TransitDetails 对象,您可以访问如下所述的 TransitStopTransitLineTransitAgency 和 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,其中包含公交机构的网址。
    • phone,其中包含公交机构的电话号码。

    如果您要手动呈现公交路线,而不是使用 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 组件,其中包括 DirectionsRouteDirectionsLegDirectionsStep 和 TransitDetails

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

以下示例绘制了到纽约市某个游览胜地的步行路线。我们会检查路线的 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,
    mapTypeId: google.maps.MapTypeId.ROADMAP,
    center: manhattan
  }
  map = new google.maps.Map(document.getElementById("map_canvas"), 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>

在路线中使用路标

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

允许的路标数目上限为 8 个,此外还包括起点和终点。Maps API for Business 客户可使用 23 个路标,此外还包括起点和终点。公交路线不支持路标。

waypoint 包含以下字段:

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

默认情况下,路线服务会按所提供路标的给定顺序计算经过这些路标的路线。或者,您也可以在 DirectionsRequest 中传递 optimizeWaypoints: true,以便以更有效的顺序重新排列这些路标,从而让路线服务对提供的路线进行优化。(此优化用于解决旅行推销员问题。)所有路标都必须中途停留,以便路线服务优化它们的路线。

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

以下示例使用各种起点、终点和路标计算跨美国的跨国家/地区路线。(要选择多个路标,请在选择列表项时按住 Ctrl 的同时点击。)请注意,我们会对分别为各条路线起点和终点提供文本的 routes.start_address 和 routes.end_address 进行检查。

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: 6,
    mapTypeId: google.maps.MapTypeId.ROADMAP,
    center: chicago
  }
  map = new google.maps.Map(document.getElementById("map_canvas"), mapOptions);
  directionsDisplay.setMap(map);
} function calcRoute() {
  var start = document.getElementById("start").value;
  var end = document.getElementById("end").value;
  var waypts = [];
  var checkboxArray = document.getElementById("waypoints");
  for (var i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected == true) {
      waypts.push({
          location:checkboxArray[i].value,
          stopover:true
      });
    }
  }   var request = {
      origin: start,
      destination: end,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING
  };
  directionsService.route(request, 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 />";
      }
    }
  });
}

可拖动路线

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

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

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

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

var rendererOptions = {
  draggable: true
};
var directionsDisplay = new google.maps.DirectionsRenderer(rendererOptions);;
var directionsService = new google.maps.DirectionsService();
var map; var australia = new google.maps.LatLng(-25.274398, 133.775136); function initialize() {   var mapOptions = {
    zoom: 7,
    mapTypeId: google.maps.MapTypeId.ROADMAP,
    center: australia
  };
  map = new google.maps.Map(document.getElementById("map_canvas"), mapOptions);
  directionsDisplay.setMap(map);
  directionsDisplay.setPanel(document.getElementById("directionsPanel"));   google.maps.event.addListener(directionsDisplay, 'directions_changed', function() {
    computeTotalDistance(directionsDisplay.directions);
  });   calcRoute();
} function calcRoute() {   var request = {
    origin: "Sydney, NSW",
    destination: "Sydney, NSW",
    waypoints:[{location: "Bourke, NSW"}, {location: "Broken Hill, NSW"}],
    travelMode: google.maps.TravelMode.DRIVING
  };
  directionsService.route(request, function(response, status) {
    if (status == google.maps.DirectionsStatus.OK) {
      directionsDisplay.setDirections(response);
    }
  });
} function computeTotalDistance(result) {
  var total = 0;
  var myroute = result.routes[0];
  for (i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i].distance.value;
  }
  total = total / 1000.
  document.getElementById("total").innerHTML = total + " km";
}