Google Maps API V3 之 路線服務

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, Brooklyn",
  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";
}