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 的公平使用对每次加载地图的总查询次数设定上限。

适用于某一路线请求的选项会根据出行方式的不同而有所区别。在请求公交路线时，将会忽略 avoidHighways、avoidTolls、waypoints[] 和 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 对象，您可以访问如下所述的 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，其中包含公交机构的网址。
    • 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 组件，其中包括 DirectionsRoute、DirectionsLeg、DirectionsStep 和 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";

}

相关文章