開發人員指南

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 計算的建議路線，且每一配對都由包含 duration 與 distance 值的列組成。

此服務不會傳回詳盡的路線資訊。將想要的單一起點與目的地傳送至 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 選擇傳回的結果，以及結果傳回的順序有小的影響。地理編碼器會根據語言，對縮寫進行不同解讀，例如街道類型的縮寫或同義字，在某語言中有效、但在其他語言中卻不是如此。例如，utca 和 tér 在匈牙利文中是街道的同義字。
• avoid － 引進對路線的限制。有效值是在本文件的限制一節中指定。只能指定一個限制。
• units － 指定以文字表示距離時要使用的單位系統。如需詳細資訊，請參閱本文件的單位系統一節。
• 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 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 － 指定一或多種偏好的大眾運輸模式。只有當 mode 為 transit 時，才能為要求指定此參數。此參數支援下列引數：
  • bus 指出計算的路線應該偏好搭乘公車。
  • subway 指出計算的路線應該偏好搭乘地下鐵。
  • train 指出計算的路線應該偏好搭乘火車。
  • tram 指出計算的路線應該偏好搭乘有軌電車或輕軌。
  • rail 指出計算的路線應該偏好搭乘火車、有軌電車、輕軌及地下鐵。這相當於 transit_mode=train|tram|subway。
• transit_routing_preference － 指定大眾運輸要求的偏好設定。您可以使用此參數，調整傳回的選項，而不是接受 API 選擇的最佳預設路線。只有當 mode 為 transit 時，才能為要求指定此參數。此參數支援下列引數：
  • less_walking 指出計算的路線應該偏好較少步行距離。
  • fewer_transfers 指出計算的路線應該偏好偏好較少轉乘次數。

旅行模式

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

• driving （預設）指出行駛公路網的距離計算結果。
• walking 要求行經（可用）人行道的步行距離計算結果。
• bicycling 要求行經（可用）單車道與偏好街道的單車距離計算結果。
• transit 要求行經（可用）大眾運輸路線的距離計算結果。只有當要求包含 API 金鑰或 Google Maps APIs Premium Plan 用戶端編號時，才可以指定這個值。如果您將模式設定為 transit，您可以選擇性指定 departure_time 或 arrival_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 欄位內顯示的 text。distance 欄位也包含一律以公尺表示的 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 的陣列，每一個都會包含 status、duration 與 distance 元素。

狀態碼

回應物件內的 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：如果有的話，會包含此路線的總票價（總車票成本）。只有大眾運輸要求，並在大眾運輸業者有提供票價資訊時才會傳回此屬性。資訊包括：
  • currency：ISO 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 參數，以指出您的應用程式是否使用感應器來判斷使用者的位置。現在已不再需要此參數。