透過 Directions API (舊版) 取得路線指引

歐洲經濟區 (EEA) 開發人員

這項產品目前處於舊版狀態。2026 年 10 月起，新的 Google Cloud 雲端專案將無法再啟用 Directions API (舊版)。現有專案仍可獲得完整支援。如要使用新功能並提升效能，請遷移至 Routes API。

如要根據使用者輸入內容即時計算路線 (例如在使用者介面元素中)，可以使用 Directions API (舊版)；如果您使用的是 Maps JavaScript API，則可使用路線規劃服務。如要在伺服器端使用，請參閱「Google 地圖服務適用的 Java、Python、Go 和 Node.js 用戶端」一文。

Directions API (舊版) 的功能如下：

  • 搜尋多種交通方式的路線，包括大眾運輸、開車、步行或騎自行車。
  • 使用一系列路線控點，傳回多個部分的路線。
  • 以文字字串 (例如「伊利諾州芝加哥」或「澳洲北領地達爾文」)、地點 ID 或經緯度座標，指定起點、目的地和路線控點。

API 會在計算路線時傳回最有效率的路線。行程時間是最佳化的主要因素，但在判斷哪條路線最有效率時，API 也可能將距離、轉彎次數和許多其他因素納入考量。

事前準備

您必須擁有已連結帳單帳戶的專案，並啟用 Directions API (舊版)，才能開始使用 Directions API (舊版)。請參閱這篇文章，進一步瞭解如何在 Cloud 控制台完成相關設定。

建構 Directions API (舊版) 要求

Directions API (舊版) 要求格式如下：

https://maps.googleapis.com/maps/api/directions/outputFormat?parameters

其中 outputFormat 可以是下列任一值：

  • json (建議)：表示以 JavaScript 物件標記法 (JSON) 輸出
  • xml 表示輸出為 XML

注意：網址必須正確編碼才有效，且所有網路服務的網址長度上限為 16,384 個字元。建構網址時，請留意這項限制。

依照網址標準，所有參數都會以 & 字元分隔。所有保留字元 (例如加號「+」) 都必須經過網址編碼。參數清單和其可能的值列舉如下。

必要參數

  • 目的地

    您要計算路線的地點 ID、地址或文字經緯度值。目的地參數的選項與起點參數相同。

  • origin

    要計算路線的地點 ID、地址或文字格式經緯度值。

    • 地點 ID 的開頭必須是 place_id:。您可以從 Geocoding API 和 Places API (包括 Place Autocomplete) 擷取地點 ID。如需使用 Place Autocomplete 服務中地點 ID 的範例，請參閱「Place Autocomplete 和路線規劃」。如要進一步瞭解地點 ID，請參閱地點 ID 總覽。 

      origin=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

    • 如果您傳遞地址，路線規劃服務會對字串進行地理編碼，並將其轉換為經緯度座標，以計算路線。這個座標可能與 Geocoding API 傳回的座標不同，例如建築物入口而非中心。

      origin=24+Sussex+Drive+Ottawa+ON

      建議使用地點 ID，而非地址或經緯度座標。使用座標時，系統一律會將點貼齊至最靠近這些座標的道路，但這可能不是房地產的入口，甚至不是能快速或安全抵達目的地的道路。

    • 如果傳遞座標，點會貼齊最近的道路。 建議傳遞地點 ID。如要傳遞座標，請確認經緯度值之間沒有空格。 

      origin=41.43206,-81.38992

    • Plus Code 格式必須為全球代碼或複合代碼。 請按照這裡指定的格式設定 Plus Code (加號在網址中會逸出為 %2B，空格則逸出為 %20)。

      • 全球代碼是 4 個半形字元的區碼，加上 6 個半形字元以上的地區代碼 (例如 849VCWC8+R9 為 849VCWC8%2BR9)。
      • 複合代碼是 6 個半形字元以上的地區代碼，加上明確的位置 (例如 CWC8+R9 Mountain View, CA, USA 為 CWC8%2BR9%20Mountain%20View%20CA%20USA)。
    注意：為提高效率和準確度，請盡可能使用地點 ID。這些 ID 就像經緯度值組合一樣，具有明確的唯一性，可為路線規劃提供地理編碼優勢，例如存取點和交通變數。與地址不同的是，ID 不需要服務執行搜尋或地點詳細資料的中繼要求，因此效能較佳。

選用參數

  • 替代方案

    如果設為 true，表示路線規劃服務可在回應中提供多條替代路線。請注意，提供替代路線可能會延長伺服器的回應時間。這個方法僅適用於沒有中繼路線控點的要求。詳情請參閱路線控點指南。

  • arrival_time

    指定大眾運輸路線的偏好抵達時間，以自世界標準時間 1970 年 1 月 1 日午夜起經過的秒數表示。您可以指定 departure_time 或 arrival_time，但不能同時指定兩者。請注意，arrival_time 必須指定為整數。

  • avoid

    表示計算出的路線應避開指定的地圖項目。這項參數支援下列引數：

    • tolls 表示計算出的路線應避開收費路段/橋梁。
    • highways 表示計算出的路線應避開高速公路。
    • ferries 表示計算出的路線應避開渡輪。
    • indoor 表示計算出的路線應避免室內階梯，適用於步行和大眾運輸路線。

    您可以將多項限制傳遞至 avoid 參數，要求避開收費路段、高速公路和渡輪的任何組合。例如： 

    avoid=tolls|highways|ferries.

  • departure_time

    指定偏好的出發時間。您可以將時間指定為整數，代表自世界標準時間 1970 年 1 月 1 日午夜起經過的秒數。如果指定的 departure_time 晚於 9999-12-31T23:59:59.999999999Z，API 會將 departure_time 設回 9999-12-31T23:59:59.999999999Z。或者，您也可以指定 now 值，將出發時間設為目前時間 (精確到秒)。出發時間可在以下兩種情況指定：

    • 如果要求中的交通方式為大眾運輸，您可以視需要指定 departure_time 或 arrival_time。如未指定任何時間，departure_time 會預設為現在 (也就是出發時間預設為目前時間)。
    • 如果要求中的交通方式是開車：您可以指定 departure_time，取得考量路況後的路線和行程時間 (回應欄位：duration_in_traffic)。departure_time 必須設為目前時間或未來時間，不得設為過去的時間。
    注意：如未指定出發時間，路線和所需時間的選擇將取決於路網，以及不考慮時間的平均路況。受到路網變動、平均路況更新，以及這項服務的分散性質影響，特定要求的結果可能會隨時間而改變。此外，在時間或頻率都沒有限制的情況下，即使兩條路線幾乎相同，結果還是有可能不同。
    注意：如果距離矩陣要求在 mode=driving 時指定 departure_time，則每項要求最多只能包含 100 個元素。「起點」數量乘以「目的地」數量就等於元素數量。

  • language

    傳回結果時使用的語言。請注意，這項設定僅適用於 start_address 和 end_address 中經過地理編碼的地址、distance 和 duration 欄位 (在路段和步驟中) 的本地化文字，以及 html_instructions 中的行進說明，但不適用於 html_instructions 中的名稱和地址，這些名稱和地址會以當地語言和文字格式顯示。

    • 請參閱支援語言清單。Google 會經常更新支援的語言，因此這份清單可能不完整。
    • 如未提供 language，API 會嘗試使用 Accept-Language 標頭中指定的偏好語言。
    • API 會盡可能提供使用者和當地人都能理解的街道地址。為達成這個目標，系統會以當地語言傳回街道地址，並視需要按照偏好語言，將地址音譯為使用者可閱讀的文字。所有其他地址都會以偏好語言傳回。傳回的所有地址元件都會採用相同語言，也就是第一個元件所選的語言。
    • 如果沒有偏好語言的名稱，API 會使用最接近的相符項目。
    • 偏好語言對 API 選擇傳回的結果集和傳回順序影響不大。地理編碼器會根據語言以不同方式解讀縮寫，例如街道類型的縮寫，或可能在某種語言中有效，但在另一種語言中無效的同義詞。舉例來說，utca 和 tér 在匈牙利文中都是街道的同義詞。

  • 模式

    計算距離和路線時，您可以指定要使用的交通方式。根據預設，系統會使用 driving 模式。根據預設，系統會計算行車路線。支援的交通方式如下：

    • driving (預設) 表示使用路網的標準行車路線或距離。
    • walking 會要求沿途設有人行道和騎樓 (如有) 的步行路線或距離。
    • bicycling 會要求沿途設有單車道與專用道路 (如有) 的單車路線或距離。
    • transit 會要求使用大眾運輸路線 (如有) 的路線或距離。如果將模式設為大眾運輸，可以選擇指定 departure_time 或 arrival_time。如未指定任何時間，departure_time 預設為現在 (也就是說，出發時間預設為目前時間)。您也可以視需要加入 transit_mode 和/或 transit_routing_preference。系統最多可提供過去 7 天或未來 100 天內的大眾運輸行程，具體取決於資料供應商提供的大眾運輸資訊。大眾運輸時刻表經常變動，可搭乘的大眾運輸行程可能會隨時間變化，因此無法保證能提供一致的預測結果。
    注意：步行和單車路線有時可能不會包含明確的人行道或單車道，因此這些路線會在傳回的結果中傳回警告，您必須向使用者顯示這些警告。

  • 區域

    區碼，指定為 ccTLD (「頂層網域」) 雙字元值。大多數 ccTLD 代碼與 ISO 3166-1 代碼相同，但有一些需要注意的例外情況。舉例來說，英國的 ccTLD 是「uk」(.co.uk)，而 ISO 3166-1 代碼則是「gb」(技術上代表「大不列顛暨北愛爾蘭聯合王國」)。

  • traffic_model

    指定計算交通時間時要採用的假設。這項設定會影響回應中 duration_in_traffic 欄位傳回的值，其中包含根據歷來平均值預估的交通時間。只有在要求包含 departure_time 的行車路線中，才能指定 traffic_model 參數。這個參數可用的值如下：

    • best_guess (預設) 表示傳回的 duration_in_traffic 應是最準確的預估行程時間 (根據歷來路況和即時路況兩者的已知相關資訊計算而得)。departure_time 距離現在的時間越近，即時車流量的影響力就越大。
    • pessimistic 表示傳回的 duration_in_traffic 在大多數日子應該都會比實際行程時間長，但偶爾路況特別差時，實際行程時間可能會超過這個值。
    • optimistic 表示傳回的 duration_in_traffic 在大多數日子應該都會比實際行程時間短，但偶爾路況特別好時，實際行程時間可能會短於這個值。

    best_guess 的預設值可為絕大多數用途提供最實用的預測結果。由於 best_guess 預測模型整合即時路況資訊的方式，best_guess 行程時間預測可能會比 optimistic 短，或比 pessimistic 長。

  • transit_mode

    指定一或多種偏好的交通方式。這個參數只能用於大眾運輸路線。這個參數支援下列引數：

    • bus 表示計算出的路線應優先選擇以公車做為交通方式。
    • subway 表示計算出的路線應優先選擇以地鐵做為交通方式。
    • train 表示計算出的路線應優先選擇以火車做為交通方式。
    • tram 表示計算出的路線應優先選擇以電車和輕軌電車做為交通方式。
    • rail 表示計算出的路線應優先選擇以火車、電車、輕軌電車和地鐵做為交通方式。這相當於 transit_mode=train|tram|subway。

  • transit_routing_preference

    指定大眾運輸路線的偏好設定。使用這個參數時，您可以自訂調整傳回的選項，而不接受 API 選擇的預設最佳路線。這個參數只能用於大眾運輸路線。這個參數支援下列引數：

    • less_walking 表示計算出的路線應優先選擇步行距離較短的選項。
    • fewer_transfers 表示計算出的路線應優先選擇轉乘次數較少的選項。

  • 個單元

    指定顯示結果時使用的單位系統。

    路線規劃結果的距離欄位中含有文字，可向使用者顯示路線中特定「步驟」的距離。根據預設，這段文字會使用起點國家/地區的單位系統。

    例如，從「伊利諾州芝加哥」到「安大略省多倫多」的路線會以英里顯示結果，但回程路線會以公里顯示結果。您可以在要求的 units 參數中明確設定單位，並傳遞下列其中一個值，覆寫這個單位系統：

    • metric 會指定使用公制系統。文字距離則以公里和公尺為單位。
    • imperial 會指定使用英制系統。文字距離會以英里和英尺傳回。
    注意：此單位系統設定只會影響距離欄位中顯示的文字。距離欄位也包含一律以公尺表示的值。

  • 路點

    注意：如果要求使用超過 10 個路線控點 (介於 11 至 25 之間) 或路線控點最佳化，系統會以較高的費率計費。進一步瞭解 Google Maps Platform 產品的計費方式。

    指定起點和目的地之間路線上要包含的中間位置陣列，做為經過或停留位置。路線控點會引導路線行經指定位置，進而改變路線。API 支援下列交通方式的路線控點：開車、步行和單車，但不支援大眾運輸。您可以提供一或多個地點，並以直立線字元 (| 或 %7C) 分隔，格式可以是地點 ID、地址或經緯度座標。根據預設，路線規劃服務會依指定的路線控點順序計算路線。剖析路線控點值的優先順序為地點 ID、經緯度座標，然後是地址。

    • 如果傳遞地點 ID，則必須在前面加上 place_id:。 您可以從 Geocoding API 和 Places API (包括 Place Autocomplete) 擷取地點 ID。如需使用 Place Autocomplete 服務中地點 ID 的範例，請參閱 Place Autocomplete 和路線規劃。如要進一步瞭解地點 ID，請參閱地點 ID 總覽。
      為提高效率和準確度，請盡可能使用地點 ID。這些 ID 就像經緯度值組合一樣，具有明確的獨特性，並可為路線規劃提供地理編碼優勢，例如存取點和交通變數。與地址不同，ID 不需要服務執行搜尋或地點詳細資料的中繼要求，因此效能較佳。
    • 如果您傳遞經緯度座標，這些值會直接傳送至前端伺服器，用於計算路線，不需經過地理編碼。這些點會貼齊道路，可能無法提供應用程式所需的準確度。如果您確信這些值確實指定了應用程式規劃路線所需的點，而不考慮可能的存取點或其他地理編碼詳細資料，請使用座標。請務必使用半形逗號 (%2C) 分隔經緯度值，而非空格 (%20)。
    • 如果傳遞地址，路線規劃服務會對字串進行地理編碼，並將其轉換為經緯度座標，以計算路線。如果地址值不明確，系統可能會進行搜尋，從類似地址中找出正確地址。舉例來說，「1st Street」可能是「1st street NE」或「1st St SE」的完整值或部分值。這個結果可能與 Geocoding API 傳回的結果不同。使用地點 ID 可避免可能的誤解。
    • 或者，您也可以使用編碼折線演算法提供一組編碼點。如果路線控點數量龐大，編碼組合會非常實用，因為網址會大幅縮短。所有網路服務的網址長度上限都是 16384 個字元。
      • 編碼折線必須在開頭加上 enc:，後面接著冒號 (:)。例如：waypoints=enc:gfo}EtohhU:。
      • 您也可以加入多個編碼折線，並以直立線字元 (|) 分隔。例如：waypoints=via:enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:| via:enc:udymA{~bxM:
    透過中途停留點和經過點影響路線

    針對要求中的每個路線控點，路線規劃回應會在 legs 陣列中附加一個項目，提供該段旅程中途點的詳細資料。

    如要使用路線控點影響路線，但不新增中途點，請在路線控點加上 via: 前置字元。如果路線控點的前置字元為 via:，系統不會在 legs 陣列中新增項目，但會規劃行經該路線控點的路線。

    下列網址會修改先前的要求，讓行程經過 Lexington，但不停靠：

    https://maps.googleapis.com/maps/api/directions/json?
origin=Boston,MA&destination=Concord,MA
&waypoints=Charlestown,MA|via:Lexington,MA

    如果建立路線是為了回應使用者在地圖上拖曳路線控點，則 via: 前置字元最有效。這樣一來，使用者就能即時查看最終路線，並確保路線控點位於 Directions API 可存取的位置。

    注意：使用 via: 前置字元來避免行經停靠點，會導致路線對路線控點的解釋過於嚴格。這可能會導致路線嚴重繞路，或者，如果 Directions API 無法建立行經該點的路線，回應狀態碼可能會傳回 ZERO_RESULTS。
    最佳化路線控點

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

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

    以下範例使用路線最佳化功能，計算從南澳阿德萊德到南澳各主要葡萄酒產區的公路行程。

    https://maps.googleapis.com/maps/api/directions/json?
origin=Adelaide,SA&destination=Adelaide,SA
&waypoints=optimize:true|Barossa+Valley,SA|Clare,SA|Connawarra,SA|McLaren+Vale,SA

    檢查計算出的路線後，您會發現計算時使用的路線控點順序如下：

    "waypoint_order": [ 3, 2, 0, 1 ]
    注意：使用路線控點最佳化的要求，會以較高的費率計費。 進一步瞭解 Google Maps Platform 產品的計費方式。

後續步驟

路線範例

路線規劃回應