路線規劃服務

總覽

您可以使用 DirectionsService 物件來計算路線 (使用各種交通方式)。這個物件會與 Google Maps API 路線規劃服務通訊,該服務會接收路線規劃要求並傳回有效路徑。交通時間是經過最佳化調整的主要因素,但系統也會將距離、轉彎次數和許多其他因素納入考量。您可以自行處理這些路線規劃結果,也可以使用 DirectionsRenderer 物件呈現這些結果。

在路線規劃要求中指定起點或目的地時,您可以指定查詢字串 (例如「伊利諾州芝加哥」或「澳洲新南威爾斯州達爾文」)、LatLng 值或 Place 物件。

路線規劃服務會使用一系列路線控點,傳回多個部分的路線。路線規劃結果可以是地圖上以折線繪製的路線,或是在 <div> 元素中的一系列文字描述 (例如「右轉上中港交流道」)。

開始使用

請先在 Google Cloud 控制台中,確認您為 Maps JavaScript API 設定的專案已啟用 Directions API,然後再開始使用 Maps JavaScript API 路線規劃服務。

如要查看已啟用的 API 清單,請按照下列步驟操作:

  1. 前往 Google Cloud 控制台
  2. 按一下「選取專案」按鈕,選取您為 Maps JavaScript API 設定的專案,然後點選「開啟」
  3. 在「Dashboard」(資訊主頁) 的 API 清單中,找出 Directions API
  4. 如果在清單中看到該 API,表示一切就緒。如果「沒有」看到這個 API,請按照下列步驟進行啟用:
    1. 選取頁面頂端的「ENABLE API」(啟用 API),即會顯示「Library」(程式庫) 分頁。或者,您也可以從左側選單中選取「程式庫」
    2. 搜尋「Directions API」,然後從結果清單中選取該 API。
    3. 選取「啟用」。這個程序完成後,「Dashboard」(資訊主頁) 的 API 清單就會顯示「Directions API」

定價和政策

定價

自 2018 年 7 月 16 日起,地圖介面集、路徑介面集和地點介面集採用新的「即付即用」定價方案,如要進一步瞭解新的 JavaScript 路線規劃服務使用費和用量限制,請參閱 Directions API 的「用量與計費」一文。

政策

使用路線規劃服務時,必須遵循 Directions API 的既定政策

路線規劃要求

Google Maps API 必須呼叫外部伺服器,因此路線規劃服務是以非同步的方式存取。基於這個理由,您必須傳遞在完成要求後執行的「回呼」方法。這個回呼方法會處理結果。請注意,路線規劃服務可能會以不同 routes[] 陣列的形式,傳回多個可能行程。

如要在 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,
  avoidFerries: Boolean,
  avoidHighways: Boolean,
  avoidTolls: Boolean,
  region: String
}

這些欄位的說明如下:

  • origin (必要) 指定用於計算路線的起點。這個值可指定為 String (例如「伊利諾州芝加哥」)、LatLng 值或 Place 物件。如果使用 Place 物件,可以指定地點 ID、查詢字串或 LatLng 位置。您可以從 Maps JavaScript API 中的 Geocoding、Place Search 和 Place Autocomplete 服務擷取地點 ID。如需使用 Place Autocomplete 服務中地點 ID 的範例,請參閱 Place Autocomplete 和路線規劃
  • destination (必要) 指定用於計算路線的終點。選項與上述 origin 欄位相同。
  • travelMode (必要) 指定計算路線時採用的交通方式。如需有效值的說明,請參閱下方的交通方式
  • transitOptions (選用) 指定的值只適用於 travelModeTRANSIT 的要求。如需有效值的說明,請參閱下方的大眾運輸選項
  • drivingOptions (選用) 指定的值只適用於 travelModeDRIVING 的要求。如需有效值的說明,請參閱下方的行車選項
  • unitSystem (選用) 指定顯示結果時要使用的單位系統。如需有效值的說明,請參閱下方的單位系統

  • waypoints[] (選用) 指定 DirectionsWaypoint 的陣列。路線控點是透過行經的指定位置來調整路線。路線控點可以指定為物件常值,欄位如下所示:

    • location 可將路線控點的位置指定為 LatLngPlace 物件,或要進行地理編碼的 String
    • stopover 為布林值,表示路線控點是路線上的行經點,可將路線一分為二

    (如要進一步瞭解路線控點,請參閱下方的使用路線上的路線控點)。

  • optimizeWaypoints (選用) 指定路線使用提供的 waypoints 時,是否可透過更有效率的順序調整路線控點,進而達到最佳化。如果為 true,路線規劃服務會在 waypoint_order 欄位中傳回重新排序的 waypoints (詳情請參閱下方的使用路線上的路線控點)。
  • provideRouteAlternatives (選用) 設定為 true 時,表示路線規劃服務可在回應中提供多條替代路線。請注意,提供替代路線可能會延長伺服器的回應時間。這個方法僅適用於沒有中繼路線控點的要求。
  • avoidFerries (選用) 設為 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: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(/* now, or future date */),
    trafficModel: 'pessimistic'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

交通方式

計算路線時,您必須指定要使用哪種交通方式。目前支援下列交通方式︰

  • DRIVING (預設) 表示使用路網的標準行車路線。
  • BICYCLING 會要求沿途設有單車道與專用道路的單車路線。
  • TRANSIT 會要求使用大眾運輸的路線。
  • WALKING 會要求沿途設有人行道和騎樓的步行路線。

如要瞭解特定國家/地區支援的路線範圍,請參閱 Google 地圖平台涵蓋範圍詳細資料。如果要求路線的區域沒有提供指定的路線類型,則回應將傳回 DirectionsStatus="ZERO_RESULTS"。

注意:步行路線有時無法明確提供人行道指示,因此會在 DirectionsResult 中傳回警告,您必須向使用者顯示這類警告。如果未使用預設的 DirectionsRenderer,則您必須負責確保顯示警告。

大眾運輸選項

路線規劃要求的可用選項會因交通方式而異。要求大眾運輸路線時,系統會忽略 avoidHighwaysavoidTollswaypoints[]optimizeWaypoints 選項。您可以透過 TransitOptions 物件常值,指定大眾運輸專屬的路線選項。

大眾運輸路線有時效性,系統只會傳回未來時間的路線。

TransitOptions 物件常值包含下列欄位:

{
  arrivalTime: Date,
  departureTime: Date,
  modes[]: TransitMode,
  routingPreference: TransitRoutePreference
}

這些欄位的說明如下:

  • arrivalTime (選用) 會將所需的抵達時間指定為 Date 物件。如果指定抵達時間,系統就會略過出發時間。
  • departureTime (選用) 會將所需的出發時間指定為 Date 物件。如果指定 arrivalTime,系統就會略過 departureTime。如未指定 departureTimearrivalTime 的值,則會預設為現在 (也就是目前時間)。
  • modes[] (選用) 陣列包含一或多個 TransitMode 物件常值。這個欄位只有在要求包含 API 金鑰時才能加入。每個 TransitMode 都會指定偏好的交通方式。可使用的值如下:
    • BUS 表示計算出的路線應優先選擇以公車做為交通方式。
    • RAIL 表示計算出的路線應優先選擇以火車、電車、輕軌電車和地鐵做為交通方式。
    • SUBWAY 表示計算出的路線應優先選擇以地鐵做為交通方式。
    • TRAIN 表示計算出的路線應優先選擇以火車做為交通方式。
    • TRAM 表示計算出的路線應優先選擇以電車和輕軌電車做為交通方式。
  • routingPreference (選用) 會指定大眾運輸路線的偏好設定。使用這個選項時,您可以自訂調整傳回的選項,而不接受 API 選擇的預設最佳路線。這個欄位只有在要求包含 API 金鑰時才能指定。可使用的值如下:
    • FEWER_TRANSFERS 表示計算出的路線應優先選擇轉乘次數較少的選項。
    • LESS_WALKING 表示計算出的路線應優先選擇步行距離較短的選項。

以下是搭乘大眾運輸的 DirectionsRequest 範例:

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

行車選項

您可以透過 DrivingOptions 物件指定行車路線的路線選項。

DrivingOptions 物件包含下列欄位:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

這些欄位的說明如下:

  • departureTime (讓 drivingOptions 物件常值有效的必要欄位) 會將所需的出發時間指定為 Date 物件。這個值必須設為目前時間或未來時間,不得設為過去的時間 (API 會將所有日期轉換為世界標準時間,確保不同時區的資料能以一致的方式處理)。針對 Google 地圖平台付費方案客戶,如果您在要求中加入 departureTime,API 就會根據當時的預期路況傳回最佳路線,並在回應中附上預估交通時間 (duration_in_traffic)。如未指定出發時間 (也就是如果要求不包含 drivingOptions),系統傳回的路線通常是不考慮路況的最佳路線。
  • trafficModel (選用) 會指定計算交通時間時要採用的假設。這項設定會影響回應中 duration_in_traffic 欄位傳回的值,其中包含根據歷來平均值預估的交通時間。預設值為 bestguess。可使用的值如下:
    • bestguess (預設) 表示傳回的 duration_in_traffic 應是最準確的預估交通時間 (根據歷來路況和即時車流量兩者的已知相關資訊計算而得)。departureTime 距離現在的時間越近,即時車流量的影響力就越大。
    • pessimistic 表示傳回的 duration_in_traffic 在大多數日子應該都會比實際交通時間長,但偶爾路況特別差時,實際交通時間可能會超過這個值。
    • optimistic 表示傳回的 duration_in_traffic 在大多數日子應該都會比實際交通時間短,但偶爾路況特別好時,實際交通時間可能會短於這個值。

以下是行車路線的 DirectionsRequest 範例:

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  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 Bootstrap 的網域 (多數使用者會載入 https://maps.googleapis.com/,因此網域會預設為美國)。如果您從另一個支援的網域載入 Bootstrap,收到的結果將受到該網域的影響。例如,在載入 https://maps.googleapis.com/ (美國) 的應用程式中搜尋「San Francisco」傳回的結果,會與在載入 http://maps.google.es/ (西班牙) 的應用程式中進行搜尋所傳回的結果不同。

您也可以使用 region 參數,讓路線規劃服務只傳回特定區域的結果。這個參數會指定區碼,採用兩位字元 (非數字) 萬國碼 (Unicode) 區域子標記。在大多數情況下,這些標記會直接對應到 ccTLD (「頂層網域」) 的兩位字元值,例如「co.uk」的「uk」。而在某些情況下,region 標記也支援 ISO-3166-1 代碼,這些代碼有時會與 ccTLD 值不同 (例如「GB」代表「Great Britain」)。

使用 region 參數時的注意事項如下:

  • 請只指定一個國家/地區。如果超過一個,除了會遭到忽略以外,還可能會導致要求失敗。
  • 請只使用兩位字元區域子標記 (萬國碼 (Unicode) CLDR 格式),所有其他輸入內容都會造成錯誤。

區域自訂調整僅適用於支援路線規劃服務的國家/地區。請參閱 Google 地圖平台涵蓋範圍詳細資料,瞭解 Directions API 的全球涵蓋範圍。

呈現路線

使用 route() 方法向 DirectionsService 發出路線規劃要求時,您必須傳遞一個回呼,以便在完成服務要求後執行。這個回呼會在回應中傳回 DirectionsResultDirectionsStatus 代碼。

路線規劃查詢狀態

DirectionsStatus 可能會傳回下列值:

  • OK 表示回應包含有效的 DirectionsResult
  • NOT_FOUND 表示在要求的起點、目的地或路線控點中,有至少一個指定地點無法進行地理編碼處理。
  • ZERO_RESULTS 表示系統在起點和目的地之間找不到路線。
  • MAX_WAYPOINTS_EXCEEDED 表示 DirectionsRequest 中提供的 DirectionsWaypoint 欄位過多。請參閱下文,瞭解路線控點的限制
  • MAX_ROUTE_LENGTH_EXCEEDED 表示要求的路線過長,無法處理。系統傳回更複雜的路線時,就會發生這項錯誤。請嘗試減少路線控點、轉彎或指示的數量。
  • 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 會負責顯示指定地點之間的折線,並在起點、目的地和任何路線控點上放置標記 (如有)。

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

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

查看範例

以下範例顯示使用不同交通工具的路線,路線為加州舊金山的海特艾許伯里前往大洋灘︰

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var haight = new google.maps.LatLng(37.7699298, -122.4469157);
  var oceanBeach = new google.maps.LatLng(37.7683909618184, -122.51089453697205);
  var mapOptions = {
    zoom: 14,
    center: haight
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.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 == 'OK') {
      directionsRenderer.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>。這樣做還可確保顯示正確的版權資訊,以及與結果相關的任何警告。

提供文字路線時,系統會使用瀏覽器的偏好語言設定,或使用您以 language 參數載入 API JavaScript 時所指定的語言 (詳情請參閱本地化)。在大眾運輸路線中,顯示的時間會以大眾運輸站點所在的時區為準。

以下範例與上述範例相同,不同之處在於以下範例包含顯示路線的 <div> 面板:

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

查看範例

DirectionsResult 物件

DirectionsService 傳送路線規劃要求時,您會收到回應,其中包含狀態碼和結果 (即 DirectionsResult 物件)。DirectionsResult 為物件常值,包含下列欄位:

  • geocoded_waypoints[] 包含 DirectionsGeocodedWaypoint 物件的陣列,每個物件皆包含起點、目的地和路線控點地理編碼的詳細資料。
  • routes[] 包含 DirectionsRoute 物件的陣列。每條路線都指出要如何從起點到達目的地的方法 (由 DirectionsRequest 提供)。一般來說,除非將要求的 provideRouteAlternatives 欄位設為 true,才會傳回多條路線,否則每個指定的要求都僅會傳回一條路線。

注意:替代路線中的 via_waypoint 屬性已淘汰。3.27 版是最新版 API,可在替代路線中新增額外的路線控點。針對 3.28 以上版本的 API,您可以停用替代路線的拖曳功能,繼續使用路線規劃服務導入可拖曳的路線。只有主要路線可拖曳。使用者可以拖曳主要路線,直到該路線與替代路線相符為止。

經過地理編碼的路線控點

DirectionsGeocodedWaypoint 包含起點、目的地和路線控點地理編碼的詳細資料。

DirectionsGeocodedWaypoint 為物件常值,包含下列欄位:

  • geocoder_status 表示地理編碼作業產生的狀態碼。這個欄位可能包含的值如下:
    • "OK" 表示沒有發生任何錯誤。地址剖析成功,且系統傳回至少一組地理編碼。
    • "ZERO_RESULTS" 表示地理編碼成功,但沒有傳回任何結果。如果地理編碼器收到不存在的 address,就有可能發生這種情況。
  • partial_match 指出地理編碼器沒有傳回與原始要求完全相符的結果,但可以比對部分要求的地址。建議您檢查原始要求,確認是否有拼寫錯誤和/或不完整的地址。

    出現部分相符結果的最常見原因,是系統在要求中傳遞的縣市內找不到街道地址。如果要求比對同一個縣市內的兩個或更多地點,也可能會傳回部分相符的結果。舉例來說,「Hillpar St, Bristol, UK」會傳回 Henry Street 和 Henrietta Street 這兩項部分相符的結果。請注意,如果要求包含拼寫錯誤的地址元件,地理編碼服務可能就會建議使用替代地址。透過這種方式觸發的建議,也會標示為部分相符。

  • place_id 是地點的專屬 ID,可與其他 Google API 搭配使用。舉例來說,您可以搭配 Google Places API 程式庫使用 place_id,以取得當地商家的詳細資料,例如電話號碼、營業時間和使用者評論等等。請參閱地點 ID 總覽
  • types[] 是一個陣列,用來指出傳回結果的「類型」。這個陣列不含任何標記或包含一個以上標記的組合,用於識別結果中傳回的地圖項目類型。舉例來說,「台北」的地理編碼會傳回「縣市」,指出「台北」是一個城市,並傳回「政治」,指出這是一個政治實體。

導航路線

注意:舊版 DirectionsTrip 物件已重新命名為 DirectionsRoute。請注意,路線現在是指從起點到終點的整段旅程,而不只是整個行程中的一段。

DirectionsRoute 包含從指定起點到目的地的一項結果。路線可能包含一個以上的路段 (類型為 DirectionsLeg),視路線中是否指定任何路線控點而定。同樣地,路線也包含版權和警告資訊,因此顯示路線資訊時,您必須向使用者顯示這些資訊。

DirectionsRoute 為物件常值,包含下列欄位:

  • legs[] 包含 DirectionsLeg 物件的陣列,其中的每個物件都包含指定路線中,兩個地點之間路線的路段相關資訊。每指定一個路線控點或目的地時,就會有一個不同的路段 (沒有路線控點的路線只會包含一個 DirectionsLeg)。每個路段包含一系列的 DirectionStep
  • waypoint_order 包含一個陣列,表示計算的路線中任何路線控點的順序。如果向 DirectionsRequest 傳遞 optimizeWaypoints: true,則此陣列包含的順序可能經過調整。
  • overview_path 包含 LatLng 的陣列,用來表示導航路線的近似 (順暢) 路徑。
  • overview_polyline 包含單一 points 物件,其中包含路線的編碼折線表示法。這條折線是導航路線的近似 (順暢) 路徑。
  • bounds 包含 LatLngBounds,表示指定路線中的折線範圍。
  • copyrights 包含這條路線中要顯示的版權文字。
  • warnings[] 包含警告的陣列,以供在顯示導航路線時同時顯示。如果您沒有使用提供的 DirectionsRenderer 物件,就必須自行處理並顯示這些警告。
  • fare 包含這條路線的總車資 (也就是總票價)。這個屬性只會針對大眾運輸要求傳回,且僅適用於所有大眾運輸路段皆有車資資訊的路線。這些資訊包括:
    • currencyISO 4217 貨幣代碼,表示金額採用的貨幣。
    • value:總車資金額,以上方指定的貨幣為單位。

導航路段

注意:舊版 DirectionsRoute 物件已重新命名為 DirectionsLeg

在計算的路線中,DirectionsLeg 代表從起點到目的地之間的一個旅程路段。如果路線沒有任何路線控點,路線只會包含一個「路段」,但如果路線定義一個以上的路線控點,路線會包含一或多個路段,對應旅程中的特定路段。

DirectionsLeg 為物件常值,包含下列欄位:

  • steps[] 包含 DirectionsStep 物件的陣列,表示旅程路段中每個不同步驟的相關資訊。
  • distance 表示這個路段所涵蓋的總距離,會以下列格式的 Distance 物件表示:

    • value 表示距離 (以公尺為單位)
    • text 包含以字串形式表示的距離,根據預設,顯示的單位與起點使用的單位相同 (例如,美國境內的任何起點都會使用英里做為單位)。您可以在原始查詢中明確設定 UnitSystem,覆寫這個單位系統。請注意,無論使用何種單位系統,distance.value 欄位的值一律會使用公尺做為單位。

    如果沒有距離資訊,就無法定義這些欄位。

  • duration 表示這個路段所需的總時間,會以下列格式的 Duration 物件表示:

    • value 表示所需時間 (以秒為單位)。
    • text 包含以字串形式表示的所需時間。

    如果沒有所需時間資訊,就無法定義這些欄位。

  • duration_in_traffic 表示在考量目前路況的情況下,這個路段所需的總時間。只有符合下列所有條件時,系統才會傳回 duration_in_traffic

    • 要求不含行經停靠點的路線控點。也就是說,不包含 stopovertrue 的路線控點。
    • 專為行車路線發出的要求,也就是 mode 設為 driving
    • 要求中的 drivingOptions 欄位會納入 departureTime
    • 要求的路線可提供路況。

    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。路線規劃網路服務在計算地點之間的路線時,會使用距離起點和終點最近的交通選項 (通常是道路),因此 start_location 可能與這個路段的起點不同 (例如道路不位於起點附近)。
  • end_location 包含這個路段的目的地 LatLngDirectionsService 在計算地點之間的路線時,會使用距離起點和終點最近的交通選項 (通常是道路),因此 end_location 可能和這個路段的目的地不同 (例如道路不位於目的地附近)。
  • start_address 包含這個路段起點的清楚易懂地址 (通常是街道地址)。

    這類內容應按原樣讀取。請勿以程式輔助方式剖析格式化地址。
  • end_address 包含這個路段終點的清楚易懂地址 (通常是街道地址)。

    這類內容應按原樣讀取。請勿以程式輔助方式剖析格式化地址。

導航步驟

DirectionsStep 是導航路線中最小的組成單位,其中包含單一步驟,用來描述旅程中某條具體指示。例如:「在自由路向左轉」。步驟不僅描述指示,也提供距離和所需時間相關資訊,說明目前步驟和下個步驟之間的關係。例如,在步驟「併入國道六號」中,可能包含「37 公里」和「40 分鐘」的所需時間,表示從目前步驟到下個步驟的所需時間為 37 公里/40 分鐘。

當您使用路線規劃服務搜尋大眾運輸路線時,步驟陣列還會包含以 transit 物件形式表示的額外大眾運輸專屬資訊。如果路線規劃包含多種交通方式,系統就會在 steps[] 陣列中提供步行或行車步驟的詳細路線。舉例來說,步行步驟會包含從開始到結束地點的路線指示:「從火車站步行到 228 公園」。這個步驟會在 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 物件,取得 TransitStopTransitLineTransitAgencyVehicleType 物件的額外資訊,如下所述。

大眾運輸詳細資料

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 包含這條大眾運輸路線的全名。例如,「指南客運」或「台北捷運」。
  • short_name 包含這條大眾運輸路線的簡稱。通常是一個路線編號,例如「板南線」或「237」。
  • agencies 是包含單一 TransitAgency 物件的陣列。TransitAgency 物件提供路線的運輸公司相關資訊,其中包含下列屬性:
    • name 包含運輸公司的名稱。
    • phone 包含運輸公司的電話號碼。
    • url 包含運輸公司的網址。

    重要資訊:如果您要手動呈現大眾運輸路線,而不使用 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 元件 (包括 DirectionsRouteDirectionsLegDirectionsStepTransitDetails)。

重要資訊:如果您要手動呈現大眾運輸路線,而不使用 DirectionsRenderer 物件,請務必顯示行程結果中提供服務的運輸公司名稱和網址。

以下範例規劃前往紐約市內特定旅遊景點的步行路線。我們會檢查路線的 DirectionsStep,為每個步驟新增標記,然後將資訊附加到 InfoWindow,其中包含該步驟的指示文字。

注意:我們計算的是步行路線,因此也會在另一個 <div> 面板中向使用者顯示任何警告。

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

function initMap() {
  // 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
  }
  directionsRenderer = 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: '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 == "OK") {
      var warnings = document.getElementById("warnings_panel");
      warnings.innerHTML = "" + response.routes[0].warnings + "";
      directionsRenderer.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)。大眾運輸路線無法使用路線控點。您可以運用路線控點計算行經其他地點的路線,因此傳回的路線會通過指定的路線控點。

waypoint 包含下列欄位:

  • location (必要) 指定路線控點的地址。
  • stopover (選用) 指出這個路線控點是否為路線上的實際停靠點 (true),或只是偏好經過的指定地點 (false)。停靠點預設為 true

在預設情況下,路線規劃服務會依指定的路線控點順序計算路線。或者,您可以選擇在 DirectionsRequest 中傳送 optimizeWaypoints: true,如此一來,路線規劃服務就能透過更有效率的順序調整路線控點,規劃出最佳路線 (這項最佳化做法是旅行推銷員問題的實際應用)。交通時間是最佳化的主要因素,但在判斷哪條路線最有效率時,系統也會將距離、轉彎次數和許多其他因素納入考量。所有路線控點都必須為停靠點,路線規劃服務才能進行路線最佳化。

如果您指示路線規劃服務進行路線控點順序最佳化,系統會在 DirectionsResult 物件的 waypoint_order 欄位中傳回這些順序。

以下範例使用各種起點、終點和路線控點,計算橫越美國的路線 (如要選取多個路線控點,在清單中選取項目時,請按下 Ctrl 鍵 + 滑鼠左鍵)。請注意,我們會檢查 routes.start_addressroutes.end_address,以取得每條路線的起點和終點文字資訊。

TypeScript

function initMap(): void {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 6,
      center: { lat: 41.85, lng: -87.65 },
    }
  );

  directionsRenderer.setMap(map);

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      calculateAndDisplayRoute(directionsService, directionsRenderer);
    }
  );
}

function calculateAndDisplayRoute(
  directionsService: google.maps.DirectionsService,
  directionsRenderer: google.maps.DirectionsRenderer
) {
  const waypts: google.maps.DirectionsWaypoint[] = [];
  const checkboxArray = document.getElementById(
    "waypoints"
  ) as HTMLSelectElement;

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: (checkboxArray[i] as HTMLOptionElement).value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: (document.getElementById("start") as HTMLInputElement).value,
      destination: (document.getElementById("end") as HTMLInputElement).value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById(
        "directions-panel"
      ) as HTMLElement;

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const 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>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

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

  directionsRenderer.setMap(map);
  document.getElementById("submit").addEventListener("click", () => {
    calculateAndDisplayRoute(directionsService, directionsRenderer);
  });
}

function calculateAndDisplayRoute(directionsService, directionsRenderer) {
  const waypts = [];
  const checkboxArray = document.getElementById("waypoints");

  for (let 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,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById("directions-panel");

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const 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>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

window.initMap = initMap;

路線控點的限制和上限

請務必遵守下列用量限制和上限:

  • 在 Maps JavaScript API 中使用路線規劃服務時,最多可包含 25 個路線控點,再加上起點和目的地。Directions API 網路服務的限制也相同。
  • Directions API 網路服務 中,客戶可以使用 25 個路線控點,再加上起點和目的地。
  • Google 地圖平台付費方案客戶可以使用 25 個路線控點,再加上起點和目的地。
  • 大眾運輸路線不支援路線控點。

可拖曳的路線

如果顯示的單車、步行或行車路線為「可拖曳」路線,使用者便可使用 DirectionsRenderer 動態修改這些路線。這樣一來,使用者就能點選並拖曳地圖上產生的路徑,藉此選取及調整路線。您也可將轉譯器的 draggable 屬性設為 true,指定轉譯器顯示可拖曳的路線。大眾運輸路線無法設定為可拖曳的路線。

只要是可拖曳的路線,使用者即可選取結果路徑上的任一點 (或路線控點),將指定元件移至新的位置。系統會動態更新 DirectionsRenderer,以顯示修改後的路徑。修改後的路徑出現後,系統會在地圖上新增一個精簡路線控點 (以白色小標記表示)。選取並移動路徑區段會變更路線中的該路段,選取並移動路線控點標記 (包括起點與終點) 則會變更在路線中通過該路線控點的路段。

可拖曳的路線是由用戶端進行修改與呈現,因此建議您監控及處理 DirectionsRenderer 上的 directions_changed 事件,以便在使用者修改顯示的路線時收到通知。

下列程式碼顯示的行程起點為澳洲西岸的伯斯,終點為東岸的雪梨。程式碼會監控 directions_changed 事件,以更新旅程中所有路段的總距離。

TypeScript

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

  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel") as HTMLElement,
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });

  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer
  );
}

function displayRoute(
  origin: string,
  destination: string,
  service: google.maps.DirectionsService,
  display: google.maps.DirectionsRenderer
) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result: google.maps.DirectionsResult) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result: google.maps.DirectionsResult) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i]!.distance!.value;
  }

  total = total / 1000;
  (document.getElementById("total") as HTMLElement).innerHTML = total + " km";
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -24.345, lng: 134.46 }, // Australia.
  });
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel"),
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });
  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer,
  );
}

function displayRoute(origin, destination, service, display) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i].distance.value;
  }

  total = total / 1000;
  document.getElementById("total").innerHTML = total + " km";
}

window.initMap = initMap;
查看範例

測試範例程式碼