Google Maps Directions API

簡介

Google Maps Directions API 這個服務會使用 HTTP 要求來計算位置之間的路線。

此影片說明如何使用 Google Maps Directions API 幫助人們找路。影片中建議當您以行動應用程式使用 API 時，透過您的伺服器為 Web 服務進行 Proxy 處理，可以保護您的 API 金鑰。

您可以搜尋數種運輸模式的路線，包括大眾運輸、開車、步行或騎單車。使用文字字串 (例如 "Chicago, IL" 或 "Darwin, NT, Australia") 或緯度/經度座標，來指定路線的起點、目的地及途經地點。Directions API 可以使用一連串途經地點傳回多部分路線。

此服務通常是設計來計算靜態 (事先已知) 地址的路線，以在地圖上放置應用程式內容；此服務在設計上不能即時回應使用者輸入。對於動態路線計算 (例如，在使用者介面元素內)，請參閱有關 Google Maps JavaScript API 路線規劃服務的文件。

計算路線不但是費時且相當耗用資源的工作。請儘可能事先計算已知地址 (使用本文所述的服務)，並將結果儲存在您自己設計的暫存快取中。

取得金鑰 使用限制

目標對象

本文件的適用對象是，想要在其中一個 Google Maps API 提供的地圖內計算路線資料的網站與行動開發人員。它提供使用 API 的簡介和可用參數的參考資料。

路線規劃要求

Google Maps Directions API 要求使用下列格式：

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

其中 output 可以是下列任何一個值：

• json (建議) 指出以 JavaScript 物件標記法 (JSON) 格式輸出
• xml 指出以 XML 格式輸出

如果要透過 HTTP 存取 Google Maps Directions API，請使用：

http://maps.googleapis.com/maps/api/directions/output?parameters

針對要求中會包括敏感使用者資料 (例如使用者的位置) 的應用程式，建議使用 HTTPS。

經過 URL 編碼後的 Google Maps Directions API URL 大約以 2000 個字元為限。有些 Google Maps Directions API URL 在路徑上可能會牽涉到許多位置，建構您的 URL 時務必注意此限制。

要求參數

有些是必要參數，其他則是選擇性參數。根據 URL 標準，所有參數都使用 & 字元來分隔。參數清單與其可能值列舉如下。

必要參數

• origin - 您要用來計算路線的地址、地點 ID 或文字型緯度/經度值。
  • 如果您將地址當成字串傳遞，路線規劃服務會為字串進行地理編碼，然後將它轉換成緯度/經度座標以計算路線。此座標可能與由 Google Maps Geocoding API 傳回的座標不同，例如建築物入口，而不是建築中央。
  • 如果您傳遞座標，系統將會直接使用它們來計算路線。確定緯度與經度值之間沒有空格存在。
  • 地點 ID 前面必須加上 place_id:。只有要求包括 API 金鑰或 Google Maps API for Work 用戶端 ID 時，才可以指定地點 ID。您可以從 Google Maps Geocoding API 與 Google Places API (包括「地點自動完成」) 擷取地點 ID。如需「地點自動完成」中的地點 ID 使用範例，請參閱地點自動完成與路線規劃。如需有關地點 ID 的詳細資訊，請參閱地點 ID 總覽。
• destination - 您要用來計算路線的地址、文字型緯度/經度值或地點 ID。destination 參數的可用選項和 origin 參數的可用選項相同，如上所述。
• key - 您應用程式的 API 金鑰。此金鑰會依配額管理目的識別您的應用程式。瞭解如何取得金鑰。

注意：Google Maps API for Work 使用者必須在路線規劃要求中包括有效的 client 與 signature 參數。如需詳細資訊，請參閱 Google Maps API for Work Web 服務一章。

選擇性參數

• mode (預設為 driving) - 指定計算路線時要使用的運輸模式。有效值與其他要求詳細資料是在旅行模式中指定。
• waypoints - 指定途經地點的陣列。途經地點更改路線的方法是指定要行經的位置。途經地點可以指定為緯度/經度座標 (例如，地點 ID)，或指定為將進行地理編碼的地址。地點 ID 前面必須加上 place_id:。只有要求包括 API 金鑰或 Google Maps API for Work 用戶端 ID 時，才可以指定地點 ID。開車、步行及單車路線才支援途經地點。(如需途經地點的詳細資訊，請參閱下方的在路線中使用途經地點)。
• alternatives - 如果設定為 true，可指定路線規劃服務會在回應中提供多條替代路線。請注意，提供替代路線會增加伺服器的回應時間。
• avoid - 指出計算的路線應該避開指定的特徵。此參數支援下列引數：
  • tolls 指出計算的路線應該避開收費道路/橋樑。
  • highways 指出計算的路線應該避開高速公路。
  • ferries 指出計算的路線應該避開渡輪。
  • indoor 指出計算的路線應該避開有室內臺階的步行與大眾運輸路線。根據預設，只有包括 API 金鑰或 Google Maps API for Work 用戶端 ID 的要求，才會收到室內臺階。
  如需詳細資訊，請參閱下方的路線限制。
• language - 指定要以哪種語言傳回結果。請參閱支援的地區語言清單。請注意，我們經常更新支援的語言，因此這份清單可能並不詳盡。如果未提供 language，服務將會嘗試使用傳送要求時來源地區的當地語言。
• units - 指定顯示結果時要使用的單位系統。有效值是在下方的單位系統中指定。
• region - 指定地區代碼 (以兩字元值的 ccTLD (頂層地區) 方式指定)。(如需詳細資訊，請參閱下方的地區偏向)。
• arrival_time - 針對大眾運輸路線指定想要的抵達時間 (秒)，自 1970 年 1 月 1 日午夜 (UTC) 起算。您可以指定 departure_time 或 arrival_time，但不得同時指定兩者。請注意，arrival_time 必須指定為整數。
• departure_time - 指定想要的出發時間。您能以整數值 (秒) 來指定時間，自 1970 年 1 月 1 日午夜 (UTC) 起算。或者，您可以將值指定為 now，以將出發時間設定為目前的時間 (最接近的秒)。出發時間可在兩種情況下指定：
  • 針對旅行模式為大眾運輸的要求：您可以選擇性指定 departure_time 或 arrival_time。如果未指定任一時間，departure_time 會預設為現在 (也就是將出發時間預設為目前時間)。
  • 針對旅行模式為開車的要求：您可以指定 departure_time 接收路線與考量路況的行程時間 (回應欄位：duration_in_traffic)。只有要求包含有效的 API 金鑰，或有效的 Google Maps API for Work 用戶端 ID 與簽章時，才能使用此選項。departure_time 必須設定為目前時間或未來的某個時間。它不能是過去的時間。
• traffic_model (預設為 best_guess) - 指定計算旅行時間時要使用的假設。此設定會影響回應中以 duration_in_traffic 欄位傳回的值，包含的值是根據歷史平均值預測的旅行時間。只有要求包括 API 金鑰或 Google Maps API for Work 用戶端 ID，並只有要求包括 departure_time 時，才可以針對開車路線指定 traffic_model 參數。
  • best_guess (預設) 指出傳回的 duration_in_traffic 應該是考量歷史路況與即時路況下的最佳預估旅行時間。departure_time 越接近現在，即時路況就越重要。
  • pessimistic 指出傳回的 duration_in_traffic 應該比過去大部分的實際旅行時間更久，雖然偶有路況特別壅塞而超過此值的日子。
  • optimistic 指出傳回的 duration_in_traffic 應該比過去大部分的實際旅行時間更短，雖然偶有路況特別順暢而比此值更快的日子。
• transit_mode - 指定一或多種偏好的大眾運輸模式。只有要求包括 API 金鑰或 Google Maps API for Work 用戶端 ID 時，才可以針對大眾運輸路線指定此參數。此參數支援下列引數：
  • bus 指出計算的路線應該偏好搭乘公車。
  • subway 指出計算的路線應該偏好搭乘地下鐵。
  • train 指出計算的路線應該偏好搭乘火車。
  • tram 指出計算的路線應該偏好搭乘有軌電車或輕軌。
  • rail 指出計算的路線應該偏好搭乘火車、有軌電車、輕軌及地下鐵。這相當於 transit_mode=train|tram|subway。
• transit_routing_preference - 指定大眾運輸路線的偏好設定。您可以使用此參數調整傳回的選項，而不是接受 API 選擇的最佳預設路線。只有要求包括 API 金鑰或 Google Maps API for Work 用戶端 ID 時，才能針對大眾運輸路線指定此參數。此參數支援下列引數：
  • less_walking 指出計算的路線應該偏好較少步行距離。
  • fewer_transfers 指出計算的路線應該偏好偏好較少轉乘次數。

範例路線規劃要求

下列要求會傳回從安大略省多倫多前往魁北克省蒙特婁的開車路線。

https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&key=YOUR_API_KEY

透過變更 mode 與 avoid 參數，可以修改初始要求，以傳回行經風景秀麗且避開主要高速公路的單車行程路線。

https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&avoid=highways&mode=bicycling&key=YOUR_API_KEY

下列要求會搜尋從紐約布魯克林區前往紐約皇后區的大眾運輸路線。此要求未指定 departure_time，因此出發時間會預設為目前時間：

https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&mode=transit&key=YOUR_API_KEY

下列要求包括特定出發時間。

注意：在此範例中，出發時間指定為 2012 年 7 月 30 日上午 9:45。為避免發生錯誤，在提交要求之前，您必須將此參數變更為未來的時間。

https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&departure_time=1343641500&mode=transit&key=YOUR_API_KEY

下列要求會使用地點 ID 傳回從英國格拉斯哥前往英國柏斯的開車路線。

https://maps.googleapis.com/maps/api/directions/json?origin=place_id:ChIJ685WIFYViEgRHlHvBbiD5nE&destination=place_id:ChIJA01I-8YVhkgRGJb0fW4UX7Y&key=YOUR_API_KEY

旅行模式

當您計算路線時，您可以指定要使用的運輸方式 mode。根據預設，會將路線計算為 driving 路線。以下是支援的旅行模式：

• driving (預設) 指出行駛公路網的標準開車路線。
• walking 要求行經 (可用) 人行道的步行路線。
• bicycling 要求行經 (可用) 單車道與偏好街道的單車路線。
• transit 要求行經 (可用) 大眾運輸路線的路線。如果您將模式設定為 transit，您可以選擇性指定 departure_time 或 arrival_time。如果未指定任一時間，departure_time 會預設為現在 (也就是將出發時間預設為目前時間)。您也可以選擇性包括 transit_mode 和/或 transit_routing_preference。

注意：步行與單車路線有可能可能不會包括明顯的人行道或單車道，因此這些路線在您必須向使用者顯示的傳回結果中將會傳回 warnings。

途經地點

使用 Google Maps Directions API 計算路線時，您也可以指定開車、步行或單車路線的「途經地點」(大眾運輸路線無法使用途經地點)。途經地點可讓您計算經過其他位置的路線，傳回的路線會包括每個指定途經地點的中途停留點。

途經地點是在 waypoints 參數內指定，並包含一或多個以直立線符號 (|) 字元分隔的地址或位置。

例如，下列 URL 起始的路線規劃要求會提供麻州波士頓與麻州康科特之間路線，中途依序在查爾斯頓與萊星頓停留：

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

對於要求中的每個途經地點，路線規劃回應會在 legs 陣列中包括額外項目，提供分段行程的對應詳細資料。

如果您不要增加中途停留點，而要以使用途經地點的方式來影響路線，可以在途經地點前面加上 via:。在途經地點前面加上 via:，不會新增項目到 legs 陣列，但行程會改為經過提供的途經地點。

下列 URL 會修改先前的要求，讓行程通過萊星頓但不會停留：

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

via: 前置詞在回應使用者在地圖上拖曳途經地點時最有效。這樣做可以讓使用者即時查看最終的路線，並有助於將途經地點確實放在 Google Maps Directions API 可以存取的位置。

最佳化途經地點

根據預設，路線規劃服務會依照提供的途經地點順序來計算路線。或者，您可以傳遞 optimize:true 做為 waypoints 參數內的第一個引數，讓路線規劃服務以最有效的順序重新安排途經地點，將提供的路線最佳化。(上述的最佳化是旅行推銷員問題的應用)。

如果您指示路線規劃服務最佳化途經地點的順序，將會在 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&key=YOUR_API_KEY

檢查計算的路線會指出路線是使用下列途經地點順序來計算：

"waypoint_order": [ 1, 0, 2, 3 ]

限制

路線規劃可以根據特定限制來計算。使用 avoid 參數來指出限制，而該參數的引數可以指出要避開的限制。以下是支援的限制：

• avoid=tolls
• avoid=highways
• avoid=ferries

您可以透過將上述限制傳送至 avoid 參數，要求路線要避開任何收費、高速公路與渡輪的組合。例如：avoid=tolls|highways|ferries。

注意：增加限制不會將包括限制特徵的路線排除，只是會將結果調整為更適合的路線。

單位系統

路線規劃結果會在 distance 欄位內包含可向使用者顯示的 text，以指出特定路線「步驟」的距離。根據預設，此文字會使用起點所在國家或地區的單位系統。

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

• metric 指定要使用公制系統。使用公里與公尺傳回文字型距離。
• imperial 指定要使用英制 (英文) 系統。使用英里與英尺傳回文字型距離。

注意：此單位系統設定只會影響 distance 欄位內顯示的 text。distance 欄位也包含一律以公尺表示的 values。

地區偏向

您也可以設定路線規劃服務，使用 region 參數傳回偏向特定地區的結果。此參數可接受指定地區偏向的 ccTLD (國家/地區代碼頂層地區) 引數。大部分 ccTLD 代碼和 ISO 3166-1 代碼完全相同，有些則是明顯例外。例如，英國的 ccTLD 是 "uk" (.co.uk)，但 ISO 3166-1 代碼是 "gb" (嚴格來說是指「大不列顛與北愛爾蘭聯合王國」)。

您可以在主要「Google 地圖」應用程式已啟用規劃開車路線的任何地區使用。

例如，當 region 設定為 es 時，會將「托利多」解譯為西班牙的城市，因此從「托利多」前往「馬德里」的路線規劃要求會傳回結果：

https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&region=es&key=YOUR_API_KEY

{
  "status": "OK",
  "routes": [ {
    "summary": "AP-41",
    "legs": [ {
        ...
    } ],
    "copyrights": "Map data ©2010 Europa Technologies, Tele Atlas",
    "warnings": [ ],
    "waypoint_order": [ ]
  } ]
}

傳送從「托利多」前往「馬德里」的路線規劃要求沒有 region 參數時，會將「托利多」解譯為俄亥俄州的城市，因而不會傳回任何結果：

https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&key=YOUR_API_KEY

{
  "status": "ZERO_RESULTS",
  "routes": [ ]
}

路線規劃回應

傳回路線規劃回應時，會依照 URL 要求路徑內 output 旗標所指示的格式傳回。

範例回應

範例 HTTP 要求顯示如下，它會計算經由兩個途經地點 (密蘇里州喬普林與奧克拉荷馬州奧克拉荷馬市)，從伊利諾伊州芝加哥前往加州洛杉磯的路線。

https://maps.googleapis.com/maps/api/directions/json?origin=Chicago,IL&destination=Los+Angeles,CA&waypoints=Joplin,MO|Oklahoma+City,OK&key=YOUR_API_KEY

上述範例要求 JSON 輸出。您也可以要求 XML 輸出。按下面的分頁可查看範例 JSON 與 XML 回應。

因為路線規劃結果會相當冗長，所以省略回應內的重複元素會更加清楚。

{
  "status": "OK",
  "geocoded_waypoints" : [
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJ7cv00DwsDogRAMDACa2m4K8",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJ69Pk6jdlyIcRDqM1KDY3Fpg",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJgdL4flSKrYcRnTpP0XQSojM",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJE9on3F3HwoAR9AhGJW_fL-I",
        "types" : [ "locality", "political" ]
     }
  ],
  "routes": [ {
    "summary": "I-40 W",
    "legs": [ {
      "steps": [ {
        "travel_mode": "DRIVING",
        "start_location": {
          "lat": 41.8507300,
          "lng": -87.6512600
        },
        "end_location": {
          "lat": 41.8525800,
          "lng": -87.6514100
        },
        "polyline": {
          "points": "a~l~Fjk~uOwHJy@P"
        },
        "duration": {
          "value": 19,
          "text": "1 min"
        },
        "html_instructions": "Head \u003cb\u003enorth\u003c/b\u003e on \u003cb\u003eS Morgan St\u003c/b\u003e toward \u003cb\u003eW Cermak Rd\u003c/b\u003e",
        "distance": {
          "value": 207,
          "text": "0.1 mi"
        }
      },
      ...
      ... additional steps of this leg
    ...
    ... additional legs of this route
      "duration": {
        "value": 74384,
        "text": "20 hours 40 mins"
      },
      "distance": {
        "value": 2137146,
        "text": "1,328 mi"
      },
      "start_location": {
        "lat": 35.4675602,
        "lng": -97.5164276
      },
      "end_location": {
        "lat": 34.0522342,
        "lng": -118.2436849
      },
      "start_address": "Oklahoma City, OK, USA",
      "end_address": "Los Angeles, CA, USA"
    } ],
    "copyrights": "Map data ©2010 Google, Sanborn",
    "overview_polyline": {
      "points": "a~l~Fjk~uOnzh@vlbBtc~@tsE`vnApw{A`dw@~w\\|tNtqf@l{Yd_Fblh@rxo@b}@xxSfytAblk@xxaBeJxlcBb~t@zbh@jc|Bx}C`rv@rw|@rlhA~dVzeo@vrSnc}Axf]fjz@xfFbw~@dz{A~d{A|zOxbrBbdUvpo@`cFp~xBc`Hk@nurDznmFfwMbwz@bbl@lq~@loPpxq@bw_@v|{CbtY~jGqeMb{iF|n\\~mbDzeVh_Wr|Efc\\x`Ij{kE}mAb~uF{cNd}xBjp]fulBiwJpgg@|kHntyArpb@bijCk_Kv~eGyqTj_|@`uV`k|DcsNdwxAott@r}q@_gc@nu`CnvHx`k@dse@j|p@zpiAp|gEicy@`omFvaErfo@igQxnlApqGze~AsyRzrjAb__@ftyB}pIlo_BflmA~yQftNboWzoAlzp@mz`@|}_@fda@jakEitAn{fB_a]lexClshBtmqAdmY_hLxiZd~XtaBndgC"
    },
    "warnings": [ ],
    "waypoint_order": [ 0, 1 ],
    "bounds": {
      "southwest": {
        "lat": 34.0523600,
        "lng": -118.2435600
      },
      "northeast": {
        "lat": 41.8781100,
        "lng": -87.6297900
      }
    }
  } ]
}

<DirectionsResponse>
 <status>OK</status>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ7cv00DwsDogRAMDACa2m4K8</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ69Pk6jdlyIcRDqM1KDY3Fpg</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJgdL4flSKrYcRnTpP0XQSojM</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJE9on3F3HwoAR9AhGJW_fL-I</place_id>
 </geocoded_waypoint>
 <route>
  <summary>I-40 W</summary>
  <leg>
   <step>
    <travel_mode>DRIVING</travel_mode>
    <start_location>
     <lat>41.8507300</lat>
     <lng>-87.6512600</lng>
    </start_location>
    <end_location>
     <lat>41.8525800</lat>
     <lng>-87.6514100</lng>
    </end_location>
    <polyline>
     <points>a~l~Fjk~uOwHJy@P</points>
    </polyline>
    <duration>
     <value>19</value>
     <text>1 min</text>
    </duration>
    <html_instructions>Head <b>north</b> on <b>S Morgan St</b> toward <b>W Cermak Rd</b></html_instructions>
    <distance>
     <value>207</value>
     <text>0.1 mi</text>
    </distance>
   </step>
   ...
   ... additional steps of this leg
  ...
  ... additional legs of this route
   <duration>
    <value>74384</value>
    <text>20 hours 40 mins</text>
   </duration>
   <distance>
    <value>2137146</value>
    <text>1,328 mi</text>
   </distance>
   <start_location>
    <lat>35.4675602</lat>
    <lng>-97.5164276</lng>
   </start_location>
   <end_location>
    <lat>34.0522342</lat>
    <lng>-118.2436849</lng>
   </end_location>
   <start_address>Oklahoma City, OK, USA</start_address>
   <end_address>Los Angeles, CA, USA</end_address>
  <copyrights>Map data ©2010 Google, Sanborn</copyrights>
  <overview_polyline>
   <points>a~l~Fjk~uOnzh@vlbBtc~@tsE`vnApw{A`dw@~w\|tNtqf@l{Yd_Fblh@rxo@b}@xxSfytAblk@xxaBeJxlcBb~t@zbh@jc|Bx}C`rv@rw|@rlhA~dVzeo@vrSnc}Axf]fjz@xfFbw~@dz{A~d{A|zOxbrBbdUvpo@`cFp~xBc`Hk@nurDznmFfwMbwz@bbl@lq~@loPpxq@bw_@v|{CbtY~jGqeMb{iF|n\~mbDzeVh_Wr|Efc\x`Ij{kE}mAb~uF{cNd}xBjp]fulBiwJpgg@|kHntyArpb@bijCk_Kv~eGyqTj_|@`uV`k|DcsNdwxAott@r}q@_gc@nu`CnvHx`k@dse@j|p@zpiAp|gEicy@`omFvaErfo@igQxnlApqGze~AsyRzrjAb__@ftyB}pIlo_BflmA~yQftNboWzoAlzp@mz`@|}_@fda@jakEitAn{fB_a]lexClshBtmqAdmY_hLxiZd~XtaBndgC</points>
  </overview_polyline>
  <waypoint_index>0</waypoint_index>
  <waypoint_index>1</waypoint_index>
  <bounds>
   <southwest>
    <lat>34.0523600</lat>
    <lng>-118.2435600</lng>
   </southwest>
   <northeast>
    <lat>41.8781100</lat>
    <lng>-87.6297900</lng>
   </northeast>
  </bounds>
 </route>
</DirectionsResponse>

本文件的剩餘部分將會使用 JSON 語法。在大部分情況下，用來在在文件中展示概念或欄位名稱的輸出格式不限。然而，請注意下列的微妙差異：

• XML 結果會以根 <DirectionsResponse> 元素包裝。
• JSON 透過複數陣列 (steps) 代表具有多個元素的項目，而 XML 使用多個單數元素 (<step>) 代表這些項目。
• 在 JSON 中是透過空陣列指出空白元素，但在 XML 中會以缺少這類元素的方式指出。例如，未產生任何結果的回應，在 JSON 中將會傳回空的 routes 陣列，但在 XML 中不會有 <route> 元素。

路線規劃回應元素

路線規劃回應包含下列根元素：

• status 包含與要求相關的中繼資料。請參閱下方的狀態碼。
• geocoded_waypoints 包含的陣列會有起點、目的地及途經地點的地理編碼詳細資料。請參閱下方的經過地理編碼的途經地點。
• routes 包含從起點前往目的地的路線陣列。請參閱下方的路線。路線包含巢狀分段與步驟。

狀態碼

路線規劃回應物件內的 status 欄位包含要求的狀態，並可以包含可協助您探究路線規劃服務失敗原因的偵錯資訊。status 欄位可能包含下列值：

• OK 指出回應包含有效的 result。
• NOT_FOUND 指出要求的起點、目的地或途經地點中，至少有一個位置無法進行地理編碼。
• ZERO_RESULTS 指出無法在起點與目的地之間找到任何路線。
• MAX_WAYPOINTS_EXCEEDED 指出要求中提供過多的 waypoints。允許的 waypoints 數目上限是 23，加上起點與目的地。(如果要求不包括 API 金鑰，允許的 waypoints 數目上限是 8。Google Maps API for Work 客戶可以提交最多具有 23 個途經地點的要求)。
• INVALID_REQUEST 指出提供的要求無效。出現此狀態的常見原因包括參數或參數值無效。
• OVER_QUERY_LIMIT 指出服務在允許的期間內從您應用程式接收到過多要求。
• REQUEST_DENIED 指出服務拒絕使用您應用程式提供的路線規劃服務。
• UNKNOWN_ERROR 指出由於發生伺服器錯誤，而無法處理路線規劃要求。重新嘗試該要求或許會成功。

錯誤訊息

當狀態碼不是 OK 時，則在路線規劃回應物件內可能有額外的 error_message 欄位。此欄位包含有關所提供之狀態碼背後原因的更多詳細資訊。

注意：此欄位不保證一律存在，且其內容可能變更。

經過地理編碼的途經地點

有關各途經地點以及起點與目的地的地理編碼詳細資料，都可以在 (JSON) geocoded_waypoints 陣列中找到。這些都能用來推論服務傳回非預期路線或未傳回任何路線的原因。

geocoded_waypoints 陣列中的元素會根據從零開始的位置，回應起點、途經地點 (依指定的順序) 及目的地。對於對應的途經地點，每個元素都包括下列有關地理編碼操作詳細資料：

• geocoder_status 指出從地理編碼操作產生的狀態碼。此欄位可能包含下列值。
  • "OK" 指出未發生任何錯誤，已順利剖析地址並且已至少傳回一個地理編碼。
  • "ZERO_RESULTS" 指出地理編碼成功，但是未傳回任何結果。如果傳遞了不存在的 address 給地理編碼器，就可能發生這種情況。

• partial_match 指出地理編碼器傳回的結果未能完全符合原始要求，但符合一部分要求的地址。您可以檢查原始要求是否有拼寫錯誤和/或不完整的地址。

  最常出現部分相符的情況是，當要求中傳遞的地區內沒有該街道地址存在時。當相同地區中有兩個以上的位置符合要求時，也會傳回部分相符。例如，"21 Henr St, Bristol, UK" 會傳回與 Henry Street 和 Henrietta Street 部分相符。請注意，如果要求包括拼寫錯誤的地址元件，地理編碼服務會建議替代地址。以這種方式觸發的建議也會標示為部分相符。

• place_id 是可與其他 Google API 搭配使用的唯一識別碼。例如，您可以使用來自 Google 地點自動完成回應的 place_id，計算前往本地商家的路線。請參閱地點 ID 總覽。
• types 指出用於計算路線之地理編碼結果的 address type。下列是傳回的類型：
  • street_address 指出明確的街道地址。
  • route 指出具名路線 (例如 "US 101")。
  • intersection 指出主要交叉路口 (通常是兩條主要道路的交叉)。
  • political 指出政治實體。一般而言，此類型會指出某行政機關的多邊形區域。
  • country 指出國家/地區政治實體，而且這通常是地理編碼器所傳回的最高順序類型。
  • administrative_area_level_1 指出國家/地區層級下的第一順位行政實體。在美國，這些行政層級是州。並非所有國家/地區都有這些行政層級。
  • administrative_area_level_2 指出國家/地區層級下的第二順位行政實體。在美國，這些行政層級是郡。並非所有國家/地區都有這些行政層級。
  • administrative_area_level_3 指出國家/地區層級下的第三順位行政實體。此類型指出次級行政單位。並非所有國家/地區都有這些行政層級。
  • administrative_area_level_4 指出國家/地區層級下的第四順位行政實體。此類型指出次級行政單位。並非所有國家/地區都有這些行政層級。
  • administrative_area_level_5 指出國家/地區層級下的第五順位行政實體。此類型指出次級行政單位。並非所有國家/地區都有這些行政層級。
  • colloquial_area 指出常用的實體替代名稱。
  • locality 指出合併的城市或鄉鎮政治實體。
  • ward 指出特定的日本地區類型，以區分日本地址中的多個地區部分。
  • sublocality 指出地區下的第一順位行政實體。有些位置會收到以下其中一個額外類型：sublocality_level_1 到 sublocality_level_5。每個 sublocality 層級都是一個行政實體。較大的數字表示較小的地理區域。
  • neighborhood 指出具名鄰近地區
  • premise 指出具名位置，通常是有通用名稱的一棟建築物或建築物集合
  • subpremise 指出具名位置下的第一順位實體，通常是有通用名稱的建築物集合內的單一建築物
  • postal_code 指出國家/地區內郵寄地址使用的郵遞區號。
  • natural_feature 指出高知名度的自然特徵。
  • airport 指出機場。
  • park 指出具名公園。
  • point_of_interest 指出具名搜尋點。一般而言，這些 "POI" 都是高知名度的地方實體，不太適合其他類別，例如「帝國大廈」或「自由女神像」。

  空的類型清單指出特定地址元件沒有已知類型，例如法國的 Lieu-dit。

如果服務未傳回任何結果，就不會向指定為文字型緯度/經度值的途經地點顯示這些詳細資料。這是因為此類途經地點只會進行反向地理編碼，以在找到路線之後取得代表的地址。空的 JSON 物件將會佔據 geocoded_waypoints 陣列中的對應地點。

路線

當 Google Maps Directions API 傳回結果時，會將這些結果放在 (JSON) routes 陣列內。即使此服務未傳回任何結果 (例如，起點和/或目的地不存在時)，仍會傳回空的 routes 陣列。(XML 回應是由零個或多個 <route> 元素所組成。)

routes 陣列的每個元素都包含來自指定起點與目的地的單一結果。此路線可能會包含一或多個 legs，取決於是否指定任何途經地點。同樣地，除了路線資訊之外，此路線也包含必須對使用者顯示的著作權與警告資訊。

routes 欄位內的每條路線都可能包含下列欄位：

• summary 包含路線的簡短文字型描述，適合用來命名路線和與替代路線清楚區分。
• legs[] 包含的陣列含有關於指定路線內兩個位置之間的路線分段資訊。將針對指定的每個途經地點或目的地顯示各個分段。(沒有途經地點的路線，在 legs 陣列內只會有一個分段)。每個分段都包含一連串 steps。(請參閱下方的路線規劃分段)。
• waypoint_order 包含的陣列會指出計算路線中任何途經地點的順序。如果要求在自己的 waypoints 參數內傳遞 optimize:true，可以重新排列此途經地點的順序。
• overview_polyline 包含的單一 points 物件保存路線的編碼折線呈現方式。這條折線是路線規劃結果的近似 (平滑) 路徑。
• bounds 包含 overview_polyline 的檢視點邊界方塊。
• copyrights 包含要為此條路線顯示的著作權文字。您必須自行處理並顯示此資訊。
• warnings[] 包含的警告陣列會在顯示這些路線時顯示。您必須自行處理並顯示這些警告。
• fare：如果有的話，會包含此路線的總票價 (總車票成本)。只會針對大眾運輸要求並只有當路線的所有大眾運輸分段有票價資訊時，才會傳回此屬性。資訊包括：
  • currency：ISO 4217 貨幣代碼，指出用以表示金額的貨幣。
  • value：總票價金額，以上述貨幣指定。
  • text：以所要求語言格式表示的總票價金額。

以下是路線內的票價資訊範例：

"routes" : [
   {
      "bounds" : {
         "northeast" : {
            "lat" : 37.8079996,
            "lng" : -122.4074334
         },
         "southwest" : {
            "lat" : 37.7881005,
            "lng" : -122.4203553
         }
      },
      "copyrights" : "Map data ©2015 Google",
      "fare" : {
         "currency" : "USD",
         "value" : 6
         "text" : "$6.00"
      },
      ...
   }]

分段

legs 陣列中的每個元素都指定從起點前往目的地的計算路線當中的一段行程。對於未包含途經地點的路線，該路線會包含單一「分段」，但對於定義一或多個途經地點的路線，該路線會包含一或多個分段，分別對應到特定的行程分段。

legs 欄位內的每個分段都可能包含下列欄位：

• steps[] 包含的步驟陣列會指出有關某行程分段每一步驟的資訊。(請參閱下方的路線規劃步驟)。

• distance 指出此分段的總距離，而此欄位包含下列元素：

  • value 指出以公尺表示的距離。
  • text 包含以人類看得懂的方式呈現的距離，顯示的單位和起點所用的單位相同 (或依照要求中的 units 參數內要覆寫的單位)。(例如，美國境內的任何起點都將使用英里與英尺)。請注意，不論顯示為文字的是哪種單位系統，distance.value 欄位包含的值一律會以公尺表示。

  如果距離不明，就不會有這些欄位。

• duration 指出此分段的總時間長度，而此欄位包含下列元素：

  • value 指出時間長度 (秒)。
  • text 包含以人類看得懂的方式呈現的時間長度。

  如果時間長度不明，就不會有這些欄位。

• duration_in_traffic 指出此分段的總時間長度。這個值是根據目前與歷史路況預估的時間。如需您可以用來要求傳回 optimistic、pessimistic 或 best-guess estimate 等值的選項，請參閱 traffic_model 要求參數。只有在符合下列所有情況時，才會傳回旅行時間長度：

  • 要求包括 departure_time 參數。
  • 要求包括有效的 API 金鑰，或有效的 Google Maps API for Work 用戶端 ID 與簽章。
  • 可為要求的路線提供路況。
  • 要求不包括中途停留的途經地點。
  • 特別針對開車路線規劃的要求 - mode 參數設定為 driving。

  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 包含此分段起點的緯度/經度座標。因為 Directions API 會使用距離起點與終點最近的運輸選項 (通常為道路) 來計算位置間的路線，如果道路不在起點附近，start_location 可能會和此分段提供的起點不同。
• end_location 包含此分段指定目的地的緯度/經度座標。因為 Google Maps Directions API 會使用距離起點與終點最近的運輸選項 (通常為道路) 來計算位置間的路線，如果道路不在目的地附近，end_location 可能會和此分段提供的目的地不同。
• start_address 包含由此分段 start_location 的反向地理編碼所產生人類看得懂的地址 (通常為街道地址)。
• end_address 包含為此分段的 end_location 進行反向地理編碼所產生人類看得懂的地址 (通常為街道地址)。

步驟

steps 陣列中的每個元素都會定義所計算路線的單一步驟。步驟是規劃路線時的最小單位，包含的單一步驟會描述行程上特定的單一指示。例如，「在忠孝路向左轉」。步驟不只會描述指示，還包含此步驟會如何影響下一步驟的距離和時間長度資訊。例如，表示為「併入 80 號快速道路」的步驟可能包含「37 公里」的時間長度與「40 分鐘」，指出下一步驟會在此步驟的 37 公里/40 分鐘後開始。

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

steps 欄位內的每個步驟都可能包含下列欄位：

• html_instructions 包含此步驟的格式化指示 (以 HTML 文字字串呈現)。
• distance 包含此步驟到下一步驟為止所涵蓋的距離。(請參閱上方路線規劃分段中有關此欄位的討論)。如果距離不明，就不會定義此欄位。
• duration 包含到下一步驟為止，一般執行步驟所需的時間長度。(請參閱上方路線規劃分段中的描述)。如果時間長度不明，就不會定義此欄位。
• start_location 包含此步驟的起點位置 (以一組 lat 與 lng 欄位的形式表示)。
• end_location 包含此步驟的終點位置 (以一組 lat 與 lng 欄位的形式表示)。
• polyline 包含的單一 points 物件保存步驟的編碼折線呈現方式。這條折線是步驟的近似 (平滑) 路徑。
• steps 包含大眾運輸路線中步行或開車步驟的詳細路線。只有在 travel_mode 設定為 "transit" 時，才能使用子步驟。內部 steps 陣列的類型和 steps 相同。
• transit_details 包含大眾運輸特定資訊。只有當 travel_mode 設定為 "transit" 時，才會傳回此欄位。請參閱下方的大眾運輸詳細資料。

大眾運輸詳細資料

大眾運輸路線規劃會傳回和其他運輸模式不相關的其他資訊。這些額外屬性會透過 transit_details 物件公開，以 steps[] 陣列中某元素的欄位傳回。您可以從 TransitDetails 物件存取有關大眾運輸站點、大眾運輸路線與大眾運輸公司的其他資訊。

transit_details 物件可能包含下列欄位：

• arrival_stop 與 departure_stop 包含有關這部分行程站點/車站的資訊。站點詳細資料包括：
  • name：大眾運輸車站/站點的名稱，例如「時代廣場」。
  • location：大眾運輸車站/站點的位置 (以一組 lat 與 lng 欄位的形式表示)。
• arrival_time 與 departure_time 包含此行程分段的抵達或出發時間，如下列三個屬性所指定：
  • text：以字串形式指定的時間。時間是以大眾運輸站點的時區顯示。
  • value：以 Unix 時間形式指定的時間，或自 1970 年 1 月 1 日午夜 (UTC) 起算的秒數。
  • time_zone 包含此車站的時區。值就是在 IANA 時區資料庫中所定義的時區名稱，例如，"America/New_York"。
• headsign 指定要在此交通路線行進的方向，如車輛上或出發站點上所標示。這通常是終點車站。
• headway 指定此時從相同站點出發班次間的預期秒數。例如，headway 值為 600，表示萬一您錯過公車，預計還要等待 10 分鐘。
• num_stops 包含此步驟中的站點數，計入抵達站點，但不計入出發站點。例如，您的路線是從 A 站點離開，經過 B 與 C 站點，然後抵達 D 站點，num_stops 將會傳回 3。
• line 包含有關此步驟中所使用大眾運輸路線的資訊，而且可能包括下列屬性：
  • name 包含此大眾運輸路線的完整名稱，例如「285 快速公車」。
  • short_name 包含此大眾運輸路線的簡短名稱。這通常是路線號碼，例如「紅 7」或 "355"。
  • color 包含此大眾運輸路線招牌中常用的色彩。色彩以十六進位字串指定，例如：#FF0033。
  • agencies 包含 TransitAgency 物件陣列，其中各物件會提供路線經營者的相關資訊，包括下列屬性：
    • name 包含大眾運輸公司的名稱。
    • url 包含大眾運輸公司的 URL。
    • phone 包含大眾運輸公司的電話號碼。

    您必須顯示向行程結果提供服務的大眾運輸公司 URL 與名稱。

  • url 包含由大眾運輸公司所提供此大眾運輸路線的 URL。
  • icon 包含與此交通路線關聯的圖示 URL。
  • text_color 包含此交通路線招牌常用的文字色彩。色彩以十六進位字串指定。
  • vehicle 包含此交通路線所使用的車輛類型。這可能包括下列屬性：
    • name 包含此交通路線上的車輛名稱，例如「捷運」。
    • type 包含在此交通路線行駛的車輛類型。如需支援值的完整清單，請參閱車輛類型文件。
    • icon 包含與此車輛類型關聯的圖示 URL。

車輛類型

vehicle.type 屬性可能會傳回下列任一個值：

sensor 參數

Google Maps API 先前要求您包括 sensor 參數，以指出您的應用程式是否使用感應器來判斷使用者的位置。現在已不再需要此參數。