總覽
您可以使用 DirectionsService
物件來計算路線 (使用各種交通方式)。這個物件會與 Google Maps API 路線規劃服務通訊,該服務會接收路線規劃要求並傳回有效路徑。交通時間是經過最佳化調整的主要因素,但系統也會將距離、轉彎次數和許多其他因素納入考量。您可以自行處理這些路線規劃結果,也可以使用 DirectionsRenderer
物件呈現這些結果。
在路線規劃要求中指定起點或目的地時,您可以指定查詢字串 (例如「伊利諾州芝加哥」或「澳洲新南威爾斯州達爾文」)、LatLng
值或 Place 物件。
路線規劃服務會使用一系列路線控點,傳回多個部分的路線。路線規劃結果可以是地圖上以折線繪製的路線,或是在 <div>
元素中的一系列文字描述 (例如「右轉上中港交流道」)。
開始使用
請先在 Google Cloud 控制台中,確認您為 Maps JavaScript API 設定的專案已啟用 Directions API,然後再開始使用 Maps JavaScript API 路線規劃服務。
如要查看已啟用的 API 清單,請按照下列步驟操作:
- 前往 Google Cloud 控制台。
- 按一下「選取專案」按鈕,選取您為 Maps JavaScript API 設定的專案,然後點選「開啟」。
- 在「Dashboard」(資訊主頁) 的 API 清單中,找出 Directions API。
- 如果在清單中看到該 API,表示一切就緒。如果「沒有」看到這個 API,請按照下列步驟進行啟用:
- 選取頁面頂端的「ENABLE API」(啟用 API),即會顯示「Library」(程式庫) 分頁。或者,您也可以從左側選單中選取「程式庫」。
- 搜尋「Directions API」,然後從結果清單中選取該 API。
- 選取「啟用」。這個程序完成後,「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
(選用) 指定的值只適用於travelMode
為TRANSIT
的要求。如需有效值的說明,請參閱下方的大眾運輸選項。drivingOptions
(選用) 指定的值只適用於travelMode
為DRIVING
的要求。如需有效值的說明,請參閱下方的行車選項。unitSystem
(選用) 指定顯示結果時要使用的單位系統。如需有效值的說明,請參閱下方的單位系統。waypoints[]
(選用) 指定DirectionsWaypoint
的陣列。路線控點是透過行經的指定位置來調整路線。路線控點可以指定為物件常值,欄位如下所示:location
可將路線控點的位置指定為LatLng
、Place 物件,或要進行地理編碼的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
,則您必須負責確保顯示警告。
大眾運輸選項
路線規劃要求的可用選項會因交通方式而異。要求大眾運輸路線時,系統會忽略 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
都會指定偏好的交通方式。可使用的值如下: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
發出路線規劃要求時,您必須傳遞一個回呼,以便在完成服務要求後執行。這個回呼會在回應中傳回 DirectionsResult
和 DirectionsStatus
代碼。
路線規劃查詢狀態
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
,您必須執行下列操作:
- 建立
DirectionsRenderer
物件。 - 在轉譯器上呼叫
setMap()
,將此函式繫結到傳遞的地圖中。 - 在轉譯器上呼叫
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
包含這條路線的總車資 (也就是總票價)。這個屬性只會針對大眾運輸要求傳回,且僅適用於所有大眾運輸路段皆有車資資訊的路線。這些資訊包括:currency
:ISO 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
:- 要求不含行經停靠點的路線控點。也就是說,不包含
stopover
為true
的路線控點。 - 專為行車路線發出的要求,也就是
mode
設為driving
。 - 要求中的
drivingOptions
欄位會納入departureTime
。 - 要求的路線可提供路況。
duration_in_traffic
包含下列欄位:value
表示所需時間 (以秒為單位)。text
包含所需時間 (清楚易懂的表示法)。
- 要求不含行經停靠點的路線控點。也就是說,不包含
arrival_time
包含這個路段的預計到達時間。只有大眾運輸路線才會傳回這個屬性。結果會以Time
物件的形式傳回,其中包含三個屬性:value
表示時間,以 JavaScriptDate
物件的形式指定。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
是導航路線中最小的組成單位,其中包含單一步驟,用來描述旅程中某條具體指示。例如:「在自由路向左轉」。步驟不僅描述指示,也提供距離和所需時間相關資訊,說明目前步驟和下個步驟之間的關係。例如,在步驟「併入國道六號」中,可能包含「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
物件,取得 TransitStop
、TransitLine
、TransitAgency
和 VehicleType
物件的額外資訊,如下所述。
大眾運輸詳細資料
TransitDetails
物件會顯示下列屬性:
arrival_stop
包含TransitStop
物件,表示內含下列屬性的抵達車站/站點:name
轉運站/站點的名稱。例如:「光復廣場」。location
轉運站/站點的地點,以LatLng
表示。
departure_stop
包含代表出發車站/站點的TransitStop
物件。arrival_time
包含抵達時間,以Time
物件形式指定,內涵下列三個屬性:value
表示時間,以 JavaScriptDate
物件的形式指定。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
元件 (包括 DirectionsRoute
、DirectionsLeg
、DirectionsStep
和 TransitDetails
)。
重要資訊:如果您要手動呈現大眾運輸路線,而不使用 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_address
和 routes.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;