您已全部設定完成!

若要開始開發,請參閱我們的開發人員文件

啟用 Google Maps Distance Matrix API

為協助您開始,我們將先引導您使用 Google Developers Console 來執行一些動作:

  1. 建立或選擇專案
  2. 啟用 Google Maps Distance Matrix API
  3. 建立適當的金鑰
繼續

開發人員指南

Google Maps Distance Matrix API 這項服務提供起點與目的地矩陣的旅行距離與時間。

此服務也以用戶端 Google Maps JavaScript API 之一部分的方式提供,或是搭配 Java Client、Python Client、Go Client 與 Node.js Client for Google Maps Services 針對伺服器端使用。注意:無論您使用該服務的方式為何,都適用相同的每日使用限制。每日元素數按照併入用戶端與伺服器端查詢的加總一起計算。

本文件適用於想要在其中一個 Google Maps API 提供的地圖中,計算多點之間的旅行距離與時間的開發人員。它提供使用 API 的簡介和可用參數的參考資料。

簡介

Google Maps Distance Matrix API 傳回的資訊是根據出發地與目的地之間由 Google Maps API 計算的建議路線,且每一配對都由包含 durationdistance 值的列組成。

此服務不會傳回詳盡的路線資訊。將想要的單一起點與目的地傳送至 Google Maps Directions API,就能夠取得路線資訊。

在您開始使用 Distance Matrix API 進行開發之前,請檢閱驗證需求 (您需要 API 金鑰)及 API 使用限制

Distance Matrix 要求

Google Maps Distance Matrix API 要求使用下列格式:

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

outputFormat 可以是下列其中一個值:

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

注意:URL 必須進行適當編碼才能有效,並針對所有 Web 服務限制為 8192 個字元。請在建構 URL 時注意到此限制。請注意,不同的瀏覽器、Proxy 與伺服器可能也會有不同的 URL 字元限制。

HTTPS 或 HTTP

安全性非常重要,因此建議在可以的情況下使用 HTTPS,特別是針對要求中會包括敏感使用者資料(例如使用者的位置)的應用程式。使用 HTTPS 加密可讓您的應用程式更安全,並更能夠抵擋窺探或竄改。

如果無法使用 HTTPS,若要透過 HTTP 存取 Google Maps Distance Matrix API,請使用:

http://maps.googleapis.com/maps/api/distancematrix/outputFormat?parameters

要求參數

有些是必要參數,其他則是選擇性參數。根據 URL 標準,所有參數都使用 & 字元來分隔。

必要參數

  • origins - 計算旅行距離與時間的起點。您可以以地址、緯度/經度座標,或地點 ID 的形式提供一或多個位置(以縱線字元 | 分隔):
    • 如果您傳遞地址,服務會為字串進行地理編碼,然後將它轉換成緯度/經度座標以計算距離。此座標可能與由 Google Maps Geocoding API 傳回的座標不同,例如建築物入口,而不是建築中央。
      origins=Bobcaygeon+ON|24+Sussex+Drive+Ottawa+ON
    • 如果您傳遞緯度/經度座標,系統將會直接使用它們來計算距離。確定緯度與經度值之間沒有空格存在。
      origins=41.43206,-81.38992|-33.86748,151.20699
    • 如果您提供地點 ID,則必須在其前面加上 place_id:。只有在要求包含 API 金鑰或 Google Maps APIs Premium Plan 用戶端編號時,才可以指定地點 ID。您可以從 Google Maps Geocoding API 和 Google Places API (包括地點自動完成)擷取地點 ID。如需「地點自動完成」中的地點 ID 使用範例,請參閱地點自動完成與路線規劃。如需有關地點 ID 的詳細資訊,請參閱地點 ID 總覽
      origins=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE
    • 或者,您可以使用編碼折線演算法來提供編碼座標。如果您有大量起點,這會特別實用,因為使用編碼折線可大幅縮短網址。
      • 編碼折線前面必須加上 enc:,後面接著冒號 (:)。例如:origins=enc:gfo}EtohhU:
      • 您也可以包含以縱線字元 (|) 分隔的多條編碼折線。例如:origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
  • destinations - 一或多個做為計算旅行距離與時間之終點的位置。destinations 參數的可用選項和 origins 參數的可用選項相同,如上所述。
  • key - 您應用程式的 API 金鑰。此金鑰會依配額管理目的識別您的應用程式。瞭解如何取得金鑰

    注意:Google Maps APIs Premium Plan 客戶可以在 Distance Matrix 要求中使用 API 金鑰,或是有效的用戶端編號和數位簽章。如需詳細資訊,請參閱 Premium Plan 客戶的驗證參數

下列範例使用緯度/經度座標來指定目的地座標:

https://maps.googleapis.com/maps/api/distancematrix/json?units=imperial&origins=40.6655101,-73.89188969999998&destinations=40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626%7C40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626&key=YOUR_API_KEY

下列範例使用編碼折線來示範同樣的要求:

https://maps.googleapis.com/maps/api/distancematrix/json?units=imperial&origins=40.6655101,-73.89188969999998&destinations=enc:_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV:&key=YOUR_API_KEY

選擇性參數

  • mode (預設為 driving) - 指定計算距離時要使用的運輸模式。有效值與其他要求詳細資料是在本文件的旅行模式一節中指定。
  • language - 傳回結果時所使用的語言。
    • 請參閱支援的語言清單。Google 經常更新支援的語言,因此這份清單可能並不詳盡。
    • 如果未提供 language,API 會嘗試使用 Accept-Language 標頭中指定的偏好語言,或傳送要求時來源網域的當地語言。
    • API 會盡可能提供使用者和當地人都看得懂的街道地址。為達成此目標,它會以當地語言傳回街道地址,視需要翻譯為使用者看得懂的文字,遵守偏好語言設定。所有其他地址都會以偏好語言傳回。從第一個地址元件選擇語言後,所有的地址元件都會以相同語言傳回。
    • 如果偏好語言中沒有某名稱,API 會使用最接近的名稱。
    • 偏好語言會對 API 選擇傳回的結果,以及結果傳回的順序有小的影響。地理編碼器會根據語言,對縮寫進行不同解讀,例如街道類型的縮寫或同義字,在某語言中有效、但在其他語言中卻不是如此。例如,utcatér 在匈牙利文中是街道的同義字。
  • avoid - 引進對路線的限制。有效值是在本文件的限制一節中指定。只能指定一個限制。
  • units - 指定以文字表示距離時要使用的單位系統。如需詳細資訊,請參閱本文件的單位系統一節。
  • arrival_time - 指定大眾運輸要求指定想要的抵達時間(秒),自 1970 年 1 月 1 日午夜 (UTC) 起算。您可以指定 departure_timearrival_time,但不得同時指定兩者。請注意,arrival_time 必須指定為整數。
  • departure_time - 想要的出發時間。您能以整數值(秒)來指定時間,自 1970 年 1 月 1 日午夜 (UTC) 起算。或者,您可以將值指定為 now,以將出發時間設定為目前的時間(最接近的秒)。出發時間可在兩種情況下指定:
    • 針對旅行模式為大眾運輸的要求:您可以選擇性指定 departure_timearrival_time。如果未指定任一時間,departure_time 會預設為現在(也就是將出發時間預設為目前時間)。
    • 針對旅行模式為開車的要求:您可以指定 departure_time 接收路線與考量路況的行程時間(回應欄位:duration_in_traffic)。只有要求包含有效的 API 金鑰,或有效的 Google Maps APIs Premium Plan 用戶端 ID 與簽章時,才能使用此選項。departure_time 必須設定為目前時間或未來的某個時間。它不能是過去的時間。

      注意:mode=driving 時,指定 departure_time 的 Distance Matrix 要求會受到每個要求最多 100 個元素的限制。「起點」數量乘以「目的地」數量即是元素數量。

  • traffic_model (預設為 best_guess) - 指定計算旅行時間時要使用的假設。此設定會影響回應中以 duration_in_traffic 欄位傳回的值,包含的值是根據歷史平均值預測的旅行時間。只有當要求包含 API 金鑰或 Google Maps APIs Premium Plan 用戶端編號,且只有當旅行模式為 driving,還有要求包含 departure_time 時,才可以針對要求指定 traffic_model 參數。此參數可用的值為:
    • best_guess (預設)指出傳回的 duration_in_traffic 應該是考量歷史路況與即時路況下的最佳預估旅行時間。departure_time 越接近現在,即時路況就越重要。
    • pessimistic 指出傳回的 duration_in_traffic 應該比過去大部分的實際旅行時間更久,雖然偶有路況特別壅塞而超過此值的日子。
    • optimistic 指出傳回的 duration_in_traffic 應該比過去大部分的實際旅行時間更短,雖然偶有路況特別順暢而比此值更快的日子。
  • transit_mode - 指定一或多種偏好的大眾運輸模式。只有當 modetransit 時,才能為要求指定此參數。此參數支援下列引數:
    • bus 指出計算的路線應該偏好搭乘公車。
    • subway 指出計算的路線應該偏好搭乘地下鐵。
    • train 指出計算的路線應該偏好搭乘火車。
    • tram 指出計算的路線應該偏好搭乘有軌電車或輕軌。
    • rail 指出計算的路線應該偏好搭乘火車、有軌電車、輕軌及地下鐵。這相當於 transit_mode=train|tram|subway
  • transit_routing_preference - 指定大眾運輸要求的偏好設定。您可以使用此參數,調整傳回的選項,而不是接受 API 選擇的最佳預設路線。只有當 modetransit 時,才能為要求指定此參數。此參數支援下列引數:
    • less_walking 指出計算的路線應該偏好較少步行距離。
    • fewer_transfers 指出計算的路線應該偏好偏好較少轉乘次數。

旅行模式

您可以指定要用來計算距離的運輸方式 mode。根據預設,會以開車模式計算距離。以下是支援的旅行模式:

  • driving (預設)指出行駛公路網的距離計算結果。
  • walking 要求行經(可用)人行道的步行距離計算結果。
  • bicycling 要求行經(可用)單車道與偏好街道的單車距離計算結果。
  • transit 要求行經(可用)大眾運輸路線的距離計算結果。只有當要求包含 API 金鑰或 Google Maps APIs Premium Plan 用戶端編號時,才可以指定這個值。如果您將模式設定為 transit,您可以選擇性指定 departure_timearrival_time。如果未指定任一時間,departure_time 會預設為現在(也就是將出發時間預設為目前時間)。您也可以選擇性包括 transit_mode 和/或 transit_routing_preference

* 注意:步行與單車路線中的人行道或單車道有時候並不明顯,因此這些回應在您必須向使用者顯示的傳回結果中將會傳回 warnings

限制

距離可以根據特定限制來計算。使用 avoid 參數來指出限制,而該參數的引數可以指出要避開的限制。以下是支援的限制:

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

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

單位系統

Distance Matrix 結果會在 distance 欄位內包含 text,以指出計算路線的距離。要使用的單位系統可指定如下:

  • units=metric (預設)傳回以公里與公尺表示的距離。
  • units=imperial 傳回以英里與英尺表示的距離。

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

Distance Matrix 回應

回應 Google Maps Distance Matrix API 查詢時,會依照 URL 要求路徑內 output 旗標所指示的格式傳回。

以下所示的兩個 HTTP 要求範例,要求從加拿大溫哥華和從美國華盛頓西雅圖,前往美國舊金山和前往加拿大維多利亞的距離與旅行時間。

此要求示範如何使用 JSON output 旗標:

https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver+BC|Seattle&destinations=San+Francisco|Victoria+BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY

此要求示範如何使用 XML output 旗標:

https://maps.googleapis.com/maps/api/distancematrix/xml?origins=Vancouver+BC|Seattle&destinations=San+Francisco|Vancouver+BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY

此要求將會傳回四個元素 - 兩個起點乘以兩個目的地。

溫哥華前往舊金山 溫哥華前往維多利亞
西雅圖前往舊金山 西雅圖前往維多利亞

結果會分列傳回,每一列都包含一個起點配上一個目的地。

嘗試一下!按一下這裡以瀏覽器中傳送範例要求。(如果系統提示您選擇要用以開啟檔案的應用程式,您可以選擇您的瀏覽器或喜愛的文字編輯器)。

按下面的分頁可查看範例 JSON 與 XML 回應。

JSON
{
  "status": "OK",
  "origin_addresses": [ "Vancouver, BC, Canada", "Seattle, État de Washington, États-Unis" ],
  "destination_addresses": [ "San Francisco, Californie, États-Unis", "Victoria, BC, Canada" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 340110,
        "text": "3 jours 22 heures"
      },
      "distance": {
        "value": 1734542,
        "text": "1 735 km"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 24487,
        "text": "6 heures 48 minutes"
      },
      "distance": {
        "value": 129324,
        "text": "129 km"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 288834,
        "text": "3 jours 8 heures"
      },
      "distance": {
        "value": 1489604,
        "text": "1 490 km"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 14388,
        "text": "4 heures 0 minutes"
      },
      "distance": {
        "value": 135822,
        "text": "136 km"
      }
    } ]
  } ]
}

請注意,如果要擷取這些結果中的值,通常需要「剖析」結果。剖析 JSON 相對容易。如需一些建議的設計模式,請參閱剖析 JSON

XML
<?xml version="1.0" encoding="UTF-8"?>
<DistanceMatrixResponse>
 <status>OK</status>
 <origin_address>Vancouver, BC, Canada</origin_address>
 <origin_address>Seattle, État de Washington, États-Unis</origin_address>
 <destination_address>San Francisco, Californie, États-Unis</destination_address>
 <destination_address>Victoria, BC, Canada</destination_address>
 <row>
  <element>
   <status>OK</status>
   <duration>
    <value>340110</value>
    <text>3 jours 22 heures</text>
   </duration>
   <distance>
    <value>1734542</value>
    <text>1 735 km</text>
   </distance>
  </element>
  <element>
   <status>OK</status>
   <duration>
    <value>24487</value>
    <text>6 heures 48 minutes</text>
   </duration>
   <distance>
    <value>129324</value>
    <text>129 km</text>
   </distance>
  </element>
 </row>
 <row>
  <element>
   <status>OK</status>
   <duration>
    <value>288834</value>
    <text>3 jours 8 heures</text>
   </duration>
   <distance>
    <value>1489604</value>
    <text>1 490 km</text>
   </distance>
  </element>
  <element>
   <status>OK</status>
   <duration>
    <value>14388</value>
    <text>4 heures 0 minutes</text>
   </duration>
   <distance>
    <value>135822</value>
    <text>136 km</text>
   </distance>
  </element>
 </row>
</DistanceMatrixResponse>

除非您的服務因某種理由而要求使用 xml,否則建議您使用 json 做為偏好的輸出旗標。處理 XML 樹狀結構時必須謹慎小心,如此您才能參照正確的節點和元素。如需一些適用於輸出處理的建議設計模式,請參閱使用 XPath 剖析 XML

本文件的剩餘部分將會使用 JSON 語法。

Distance Matrix 回應元素

Distance Matrix 回應包含下列根元素:

  • status 包含與要求相關的中繼資料。請參閱下方的狀態碼
  • origin_addresses 包含由 API 傳回且源自您原始要求的地址陣列。這些都是透過地理編碼器格式化,並根據隨著要求傳送的 language 參數當地語系化。
  • destination_addresses 包含由 API 傳回且源自您原始要求的地址陣列。如同 origin_addresses,這些會在適當時當地語系化。
  • rows 包含 elements 的陣列,每一個都會包含 statusdurationdistance 元素。

狀態碼

回應物件內的 status 欄位包含要求的狀態,並且可能包含實用的偵錯資訊。Distance Matrix API 會傳回當中包含一般要求資訊的頂層狀態欄位,還有各元素欄位的狀態欄位,提供特定起點與目的地組合的相關資訊。

頂層狀態碼
  • OK 指出回應包含有效的 result
  • INVALID_REQUEST 指出提供的要求無效。
  • MAX_ELEMENTS_EXCEEDED 指出起點數和目的地數的乘積超過每次查詢的限制
  • OVER_QUERY_LIMIT 指出服務在允許的期間內從您應用程式接收到過多要求。
  • REQUEST_DENIED 指出服務拒絕使用您應用程式提供的 Distance Matrix 服務。
  • UNKNOWN_ERROR 指出由於發生伺服器錯誤,而無法處理 Distance Matrix 要求。重新嘗試該要求或許會成功。
元素層級狀態碼
  • OK 指出回應包含有效的 result
  • NOT_FOUND 指出此組合的起點和/或目的地無法進行地理編碼。
  • ZERO_RESULTS 指出無法在起點與目的地之間找到任何路線。

錯誤訊息

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

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

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

各列會根據要求中的 origin 參數值排序。每列都有對應的起點,而各列內的每個 element 會對應到與起點組合的 destination 值。

每個 row 陣列都包含一或多個 element 項目,內含單一起點與目的地組合的相關資訊。

元素

各組起點與目的地組合的相關資訊會以 element 項目傳回。element 包含下列欄位:

  • status:如需可能的狀態碼清單,請參閱狀態碼
  • duration:於此路線旅行所需花費的時間長度,以秒(value 欄位)表示並顯示為 text。要呈現的文字是根據查詢的 language 參數當地語系化。
  • duration_in_traffic:根據目前與歷史路況,於此路線行進時花費的時間長度。如需您可以用來要求傳回 optimistic、pessimistic 或 best-guess estimate 等值的選項,請參閱 traffic_model 要求參數。時間長度是以秒(value 欄位)表示並顯示為 text。要呈現的文字是根據查詢的 language 參數當地語系化。只有在符合下列所有情況時,才會傳回旅行時間長度:

    • 要求包括 departure_time 參數。
    • 要求包括有效的 API 金鑰,或有效的 Google Maps APIs Premium Plan 用戶端 ID 與簽章。
    • 可為要求的路線提供路況。
    • mode 參數是設定為 driving
  • distance:此路線的總距離,以公尺表示 (value) 並顯示為 text。文字值會使用以原始要求的 unit 參數或起點地區指定的單位系統。
  • fare:如果有的話,會包含此路線的總票價(總車票成本)。只有大眾運輸要求,並在大眾運輸業者有提供票價資訊時才會傳回此屬性。資訊包括:
    • currencyISO 4217 貨幣代碼,指出用以表示金額的貨幣。
    • value:總票價金額,以上述貨幣指定。
    • text:以所要求語言格式表示的總票價金額。

以下是含有票價資訊的 element 範例:

{
  "status": "OK",
  "duration": {
    "value": 340110,
    "text": "3 jours 22 heures"
  },
  "distance": {
    "value": 1734542,
    "text": "1 735 km"
  }
  "fare" : {
    "currency" : "USD",
    "value" : 6,
    "text" : "$6.00"
  },
}

sensor 參數

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

傳送您對下列選項的寶貴意見...

這個網頁
Google Maps Distance Matrix API
Google Maps Distance Matrix API
需要協助嗎?請前往我們的支援網頁