Google Maps API Web Services - Directions API

這個服務通常是設計來計算靜態 (已知) 地址的導航，以便在地圖上放置應用程式內容，而「不是」用來即時回應如使用者輸入等作業。使用 HTTP 要求來計算位置之間的導航，可以文字字串 (例如，「Chicago, IL」或「Darwin, NSW, Australia」)或經度/緯度座標來指定導航的起點、目的地與路點。Directions API 可使用一系列路點傳回多個部分的導航。



計算導航這項工作不僅費時且需要耗用大量資源。如果可以，請事先計算已知的地址 (使用此處描述的服務)，並將算出的結果儲存在您個人設計的暫時快取中。

注意︰使用 Google Directions API 不需要 Maps API 金鑰！

使用限制

Google Directions API 有查詢限制，每天只能發出 2500 個導航要求。進行個別導航要求時，每個要求最多可包含 8 個中繼路點。 Google Maps Premier 客戶每天最多可查詢 100,000 個導航要求，而每個要求中最多可包含 23 個路點。

導航要求

Directions API 要求必須使用下列其中一種格式：

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

其中 output 可為下列任一個值︰

• json (建議使用) 表示輸出格式為 JavaScript 物件註解 (JSON)
• xml 表示輸出格式為 XML

要求參數

有些參數為必要，而有些參數則為選用。跟網址的標準一樣，這裡的所有參數都會以 & 字元分隔。參數清單和其可能的值列舉如下。

Directions API 使用下列網址參數來定義導航要求︰

• origin (必要) — 您要計算導航的地址或經/緯度文字值。*
• destination (必要) — 您要計算導航的地址或經/緯度文字值。*
• mode (選用，預設為 driving) — 指定計算導航時要使用的交通模式。有效值指定於「交通模式」中。
• waypoints (選用) 指定路點陣列。路點會透過讓路線行經指定位置來修改路線。路點可以指定為經/緯度座標或可進行地理編碼的地址。(如需路點的進一步資訊，請參閱「在路線上使用路點」)。
  
• alternatives (選用)，設為 true 時，表示「導航」服務可在回應中提供一個以上的替代路線。請注意，提供替代路線可能會延長伺服器的回應時間。
• avoid (選用) 表示計算的路線應避開指定的功能。目前這個參數支援下列兩個引數︰
  
  • tolls 表示計算的路線應避開收費道路/橋。
  • highways 表示計算的路線應避開高速公路。
  (如需詳細資訊，請參閱下方的「路線限制」)。
• language (選用)：結果傳回時使用的語言。請參閱「支援的網域語言清單」。請注意，我們經常更新支援的語言，因此這份清單可能會有遺漏。如果 language 不受支援，「導航」服務會嘗試使用瀏覽器的預設語言。您也可以使用 http://map.google.com 的本地化網域來明確調整結果。如需詳細資訊，請參閱「區域自訂調整」。
• sensor (必要) — 指出導航要求的來源裝置是否附有位置感應器。這個值必須是 true 或 false。

* 注意︰您可以在多個參數中傳送地址或經/緯度座標。如果您傳送的地址是字串，「導航」服務會對該字串進行地理編碼並轉換為經緯度座標來計算導航。

交通模式

當您計算導航時，您可以指定要使用哪一種運輸系統 mode。根據預設，導航會以 driving 導航來計算。目前支援的交通模式有下列幾種︰

• driving (預設) 表示使用道路網的標準行車導航。
• walking 要求使用人行道及行人徒步路徑 (如果有的話) 的步行導航。
• bicycling 要求使用單車道及專用道路 (目前只適用於美國) 的單車導航。

注意︰步行和單車導航有時可能無法明確地提供人行道或單車道指示，所以這些導航會在傳回的結果中傳回 warnings 以供您向使用者顯示。

使用路線上的路點

使用 Directions API 計算路線時，您必須同時指定「路點」。路點可讓您計算繞道其他位置的路線，因此傳回的路線會通過指定的路點。waypoints 參數會指定路點，路點是由一個以上的地址或位置組成，並以管道字元 | 隔開。例如...

http://maps.google.com/maps/api/directions/json?origin=Boston,MA&destination=Concord,MA&waypoints=Charlestown,MA|Lexington,MA&sensor=false

或者您也可以選擇將 optimize:true 傳送到 waypoints 做為第一個引數，如此一來，「導航」服務就可以以更有效率的順序來重新安排路點，讓路線最佳化。這些順序會傳回到 routes 物件的 waypoint_order 欄位中。waypoint_order 欄位會傳回以零為基準的值。例如...

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

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

限制

導航的計算方式必須遵守某些限制︰使用 avoid 參數可指定限制，另外，其中會有一個引數指定要避開的限制。目前支援的限制有兩個︰

• avoid=tolls
• avoid=highways

注意︰增加限制並不代表包含限制地圖項的路線就會被排除，只是會將結果儘量調整到較偏好的路線。

區域自訂調整

您也可以使用預設的 http://maps.google.com/ 網域之外的其他網域，來讓「導航」服務只傳回特定區域的結果。您可以使用任何網域，只要該網域中的主要「Google 地圖」應用程式已啟用行車導航。

舉例

http://maps.google.es/maps/api/directions/json?origin=Toledo&destination=Madrid&sensor=false (會找到，因為都是西班牙的城市)
http://maps.google.com/maps/api/directions/json?origin=Toledo&destination=Madrid&sensor=false (找不到，因為「Toledo」會被解讀為美國俄亥俄州的城市)

導航回應

JSON 輸出 / XML 輸出

你可以看這裡

導航回應元素

導航回應包含兩個根元素︰

1. "status" 包含要求的中繼資料。
• OK 表示回應包含有效的 result。
• NOT_FOUND 表示在要求的起點、目的地或路點指定的位置中，至少有一個位置無法進行地理編碼。
• ZERO_RESULTS 表示系統在起點和目的地之間找不到路線。
• MAX_WAYPOINTS_EXCEEDED 表示要求中提供了太多的 waypoints。允許的 waypoints 上限為 8，且包含起點和目的地 ( Google Maps Premier 客戶的要求最多可包含 23 個路點)。
• INVALID_REQUEST 表示提供的要求無效。
• OVER_QUERY_LIMIT 表示服務在允許的時間內已從您的應用程式接收到太多要求。
• REQUEST_DENIED 表示服務拒絕您的應用程式使用導航服務。
• UNKNOWN_ERROR 表示伺服器發生錯誤，無法處理導航要求。如果您再試一次，可能會成功進行要求。
2. "routes" 包含一個由起點到目的地的路線陣列。包含巢狀航段和步驟。即使服務並未傳回任何結果 (例如起點和/或目的地不存在時)，它還是會傳回一個空的 routes 陣列 (XML 回應是由零或更多的 元素組成)。路線也包含版權，所以您必須在顯示路線資訊時同時顯示警告來提醒使用者。routes 欄位裡的每個路線可能包含下列欄位︰
• summary 包含路線的簡短文字說明，適用於命名路線和區分替代路線。
• legs[] 包含一個陣列，其中包含指定路線中兩個位置之間路線的航段相關資訊。每指定一個路點或目的地時，就會有一個不同的航段 (如果路線沒有路點，則 legs 陣列中只會包含一個航段)。每個航段包含一系列的 steps。每個航段可能包含下列欄位︰
• steps[] 包含一個步驟陣列，指出旅途中航段每個不同的步驟資訊。步驟是導航路線中最小的組成單位，不僅描述指示，同時也包含距離和期間資訊。
• html_instructions 包含此步驟的格式化指示，以 HTML 文字字串表示。
• distance 包含此步驟到下個步驟所涵蓋的距離。如果沒有距離資訊，則不必定義這個欄位。
• duration 包含執行這個步驟直到下個步驟通常所需的時間。如果沒有時間資訊，則不必定義這個欄位。
• start_location 包含此步驟起點的位置，以一組 lat 和 lng 欄位表示。
• end_location 包含此步驟起點的位置，以一組 lat 和 lng 欄位表示。
• distance 表示這個航段所涵蓋的總距離(如果距離未知，這些欄位可能不會出現)，欄位中包含下列元素︰
• value 表示距離 (單位為公尺)
• text 中的距離表示法為人類可讀的格式，顯示單位與起點使用的單位相同，且使用的語言與要求的指定語言相同。(例如在美國境內，起點會使用英哩和英呎為單位)。請注意，不管顯示的文字使用何種單位系統，distance.value 欄位中永遠包含一個以公尺表示的值。
• duration 表示這段旅程的總期間(如果期間未知，這些欄位可能不會出現)，欄位中包含下列元素︰
• value 表示期間 (單位為秒)
• text 包含期間 (人類可讀的表示法)。
• start_location 包含這個航段的起點經度/緯度座標。由於 Directions API 會使用離起點和終點處最接近的交通選項 (通常是道路) 來計算位置之間的導航，因此 start_location 可能和這個航段的起點不同 (例如某一道路不位於起點附近)。
• end_location 包含這個航段的指定目的地經度/緯度座標。由於 Directions API 會使用離起點和終點處最接近的交通選項 (通常是道路) 來計算位置之間的路線，end_location 可能和這個航段的目的地不同 (例如某一道路不位於目的地附近)。
• start_address 包含人類可讀格式的地址 (通常是街道地址)，代表這個航段的 start_location。
• end_addresss 包含人類可讀格式的地址 (通常是街道地址)，代表這個航段的 end_location。
• waypoint_order 包含一個陣列，指定計算的路線中任何路點的順序。如果傳送 optimize:true 到要求的 waypoints 參數中 ，這些路點可能會重新排序。
• overview_path 包含一個物件，其中存放了一個已編碼的 points 和 levels 陣列，用來代表結果導航的概略 (順暢) 路徑。
• copyrights 包含這個路線中要顯示的版權文字。您必須自行處理並顯示這項資訊。
• warnings[] 包含一個警告陣列，以在顯示這些導航時同時顯示。您必須自行處理並顯示這些警告。

範例

可以看這裡。


--
詳情請參閱 這裡