路線規劃服務

總覽

您可以使用 DirectionsService 物件計算使用各種運輸方法的路線規劃。此物件會與接收路線規劃要求的 Google Maps API 路線規劃服務通訊，然後傳回計算的結果。您可以自行處理這些路線規劃，或者使用 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 地圖涵蓋資料以判斷國家/地區支援的路線規劃範圍。如果您要求路線規劃的地區沒有該路線規劃類型，回應將會傳回 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 路線規劃服務傳回的地址結果會受到您載入 JavaScript 啟動程序的網域 (地區或國家) 影響。(由於大多數使用者是載入 https://maps.google.com/，所以自然會將網域設定為美國)。如果您從不同支援的網域載入啟動程序，就會得到該網域影響的結果。例如，應用程式載入 https://maps.google.com/ (美國) 時搜尋 "San Francisco" 傳回的結果和載入 http://maps.google.es/ (西班牙) 時不同。

您也可以設定路線規劃服務，使用 region 參數傳回偏向特定地區的結果。此參數使用指定為 IANA 語言 region 子標籤的地區代碼。在大多數情況下，這些標記會直接對應至 ccTLD (「頂層地區」) 的兩字元值，例如 "co.uk" 中的 "uk"。在某些情況下，region 標籤也支援 ISO-3166-1 代碼，有時候會與 ccTLD 值不同 (例如「Great Britain」的「GB」)。

請參閱 Google 地圖涵蓋資料以判斷國家/地區支援的路線規劃範圍。

轉譯路線規劃

使用 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)

下列範例顯示在加州舊金山的 Haight-Ashbury 到 Ocean Beach 之間使用不同旅行模式的路線規劃：

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 搭配使用。例如，您可以搭配 Google Places API 程式庫使用 place_id，以取得當地商家的詳細資料，例如電話號碼、營業時間、使用者評論等。請參閱地點 ID 總覽。
• types[] 是指出傳回結果之「類型」的陣列。此陣列包含零個或多個標籤，指出結果中傳回的特徵類型。例如「芝加哥」的地理編碼會傳回 "locality"，指出「芝加哥」是城市，也會傳回 "political"，指出它是政治實體。

路線規劃路線

舊版的 DirectionsTrip 物件已經重新命名為 DirectionsRoute。請注意，路線現在代表的是從開始到結束的一個完整行程，而不是只是一小段行程。

DirectionsRoute 包含指定起點與目的地的一個結果。此路線可以包含一或多段行程 (DirectionsLeg 類型)，取決於是否指定任何途經地點。同樣地，除了路線資訊之外，此路線也包含必須對使用者顯示的著作權與警告資訊。

DirectionsRoute 是包含下列欄位的物件常值：

• legs[] 包含 DirectionsLeg 物件的陣列，每個物件都包含指定路線內兩個位置之間的路線分段資訊。將針對指定的每個途經地點或目的地顯示各個分段。(沒有途經地點的路線只會包含一個 DirectionsLeg)。每個分段都包含一連串 DirectionStep。
• waypoint_order 包含的陣列會指出計算路線中任何途經地點的順序。如果將 optimizeWaypoints: true 傳遞到 DirectionsRequest ，此陣列的順序可能會有所改變。
• 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 指出在考量目前路況下此分段的總時間長度。只有在有路況資料、mode 設定為 driving，而且要求的 drivingOptions 欄位有 departureTime 時，才會對 Google Maps API for Work 客戶傳回 duration_in_traffic。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 是規劃路線時的最小單位，包含的單一步驟會描述行程上特定的單一指示。例如，「在忠孝路向左轉」。步驟不只會描述指示，還包含此步驟會如何影響下一步驟的距離和時間長度資訊。例如，表示為「併入 80 號快速道路」的步驟可能包含「37 公里」的時間長度與「40 分鐘」，指出下一步驟會在此步驟的 37 公里/40 分鐘後開始。

使用路線規劃服務搜尋大眾運輸路線時，步驟陣列會以 transit 陣列的形式包括額外的大眾運輸特定資訊。如果路線包括多種運輸模式，將會在 steps[] 陣列中提供步行或開車步驟的詳細路線。例如，步行步驟會包括從起點到終點位置的路線：「走到信義路與仁愛街」。該步驟將會在 steps[] 陣列中，包括該路線的詳細步行路線，例如：「朝西北方前進」、「在人行步道向左轉」及「在和平路向左轉」。

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 包含此大眾運輸路線的完整名稱。例如，「285 快速公車」或「信義幹線」。
• short_name 包含此大眾運輸路線的簡短名稱。這通常是路線號碼，例如 "2" 或 "M14"。
• 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-Click)。請注意，我們會檢查 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)。