Google 地圖平台即將推出新版地圖樣式。新版地圖樣式內建全新的預設調色盤，並且提升地圖體驗、改善服務的可用性。所有地圖樣式都將於 2025 年 3 月自動更新。請參閱「Google 地圖平台新版地圖樣式」一文，進一步瞭解適用範圍及如何提早啟用。

本頁面由 Cloud Translation API 翻譯而成。

Distance Matrix

DistanceMatrixService 類別

google.maps.DistanceMatrixService 類別

計算多個起點與目的地之間距離的服務。

呼叫 const {DistanceMatrixService} = await google.maps.importLibrary("routes") 即可存取。請參閱 Maps JavaScript API 中的程式庫。

建構函式
`DistanceMatrixService`	`DistanceMatrixService()` 參數：無建立 `DistanceMatrixService` 的新例項，將距離矩陣查詢傳送至 Google 伺服器。

方法
`getDistanceMatrix`	`getDistanceMatrix(request[, callback])` 參數： `request`：`DistanceMatrixRequest` `callback`：`function(DistanceMatrixResponse optional, DistanceMatrixStatus): void optional` 傳回值： `Promise<DistanceMatrixResponse>` 提出距離矩陣要求。

DistanceMatrixRequest 介面

google.maps.DistanceMatrixRequest 介面

DistanceMatrixService 傳送的距離矩陣查詢，內含起點和目的地位置陣列，以及多種計算指標選項。

屬性
`destinations`	類型： `Array<string\|LatLng\|LatLngLiteral\|Place>` 包含計算到該目的地地址字串的 `LatLng` 或 `Place` 物件陣列，用來計算距離和時間。這是必填欄位。
`origins`	類型： `Array<string\|LatLng\|LatLngLiteral\|Place>` 包含起點地址字串或 `LatLng` 或 `Place` 物件的陣列，可用於計算由該地出發的距離與時間。這是必填欄位。
`travelMode`	類型： `TravelMode` 要求的路線類型。這是必填欄位。
`avoidFerries optional`	類型： `boolean optional` 如果設為 `true`，則指示距離矩陣服務盡量避開渡輪。選用。
`avoidHighways optional`	類型： `boolean optional` 如果設為 `true`，則指示距離矩陣服務盡量避開高速公路。選用。
`avoidTolls optional`	類型： `boolean optional` 如果設為 `true`，則指示距離矩陣服務盡量避開收費路段。選用。
`drivingOptions optional`	類型： `DrivingOptions optional` 僅適用於 `travelMode` 為 `DRIVING` 的要求。這個物件不會影響其他交通方式。
`language optional`	類型： `string optional` 結果傳回該語言的語言 ID (可能的話)。請參閱支援語言清單。
`region optional`	類型： `string optional` 用於地理編碼要求自訂調整的區域代碼。區碼接受 ccTLD (「頂層網域」) 的兩位字元值多數 ccTLD 代碼與 ISO 3166-1 代碼相同，只有少數例外。舉例來說，英國的 ccTLD 是「uk」(`.co.uk`)，但 ISO 3166-1 代碼卻是「gb」(正式的國名是「大不列顛暨北愛爾蘭聯合王國」)。
`transitOptions optional`	類型： `TransitOptions optional` 這項設定僅適用於 `travelMode` 為 TRANSIT 的要求。這個物件不會影響其他交通方式。
`unitSystem optional`	類型： `UnitSystem optional` 顯示距離時使用的常用單位系統。選用，預設為公制。

DistanceMatrixResponse 介面

google.maps.DistanceMatrixResponse 介面

DistanceMatrixService 要求的回應，其中包含格式化的出發地和目的地地址，以及一系列 DistanceMatrixResponseRow (每個對應的起點地址)。

屬性
`destinationAddresses`	類型： `Array<string>` 格式化的目的地地址。
`originAddresses`	類型： `Array<string>` 格式化的起點地址。
`rows`	類型： `Array<DistanceMatrixResponseRow>` 對應至起點地址的矩陣列。

DistanceMatrixResponseRow 介面

google.maps.DistanceMatrixResponseRow 介面

DistanceMatrixService 要求的回應資料列，由 DistanceMatrixResponseElement 的序列組成，每個對應的目的地地址各一個。

屬性
`elements`	類型： `Array<DistanceMatrixResponseElement>` 對應目的地地址的列元素。

DistanceMatrixResponseElement 介面

google.maps.DistanceMatrixResponseElement 介面

回應 DistanceMatrixService 要求的單一元素，其中包含從某個起點到某個目的地的時間長度與距離。

屬性
`distance`	類型： `Distance` 此起點與目的地對組之間的距離。因為距離不明，這個屬性可能未定義。
`duration`	類型： `Duration` 此起點與目的地對組的期間。因為期間不明，這個屬性可能未定義。
`duration_in_traffic`	類型： `Duration` 此起點與目的地對組的時間長度 (取決於 `trafficModel` 屬性指定的路況)。這個屬性可能是 `undefined`，因為時間長度不明。只有在提出要求時定義 `drivingOptions` 時，才能使用付費方案客戶。
`fare`	類型： `TransitFare` 此起點與目的地對組的總車資。僅適用於大眾運輸要求。
`status`	類型： `DistanceMatrixElementStatus` 此特定起點與目的地對組的狀態。

DistanceMatrixStatus 常數

google.maps.DistanceMatrixStatus 常數

完成距離矩陣要求後，通常由 DistanceMatrixService 傳回與要求相關的頂層狀態。您可以採用值或常數名稱來指定這些參數。例如 'OK' 或 google.maps.DistanceMatrixStatus.OK。

呼叫 const {DistanceMatrixStatus} = await google.maps.importLibrary("routes") 即可存取。請參閱 Maps JavaScript API 中的程式庫。

常數
`INVALID_REQUEST`	提供的要求無效。
`MAX_DIMENSIONS_EXCEEDED`	該要求包含超過 25 個起點，或超過 25 個目的地。
`MAX_ELEMENTS_EXCEEDED`	起點與目的地的乘積超出每項查詢的限制。
`OK`	回應包含有效的結果。
`OVER_QUERY_LIMIT`	在允許的時段內要求了過多的元素。請稍後再試一次，要求應會成功。
`REQUEST_DENIED`	服務拒絕您的網頁使用距離矩陣服務。
`UNKNOWN_ERROR`	伺服器發生錯誤，無法處理距離矩陣要求。如果您再試一次，可能會成功進行要求。

DistanceMatrixElementStatus 常數

google.maps.DistanceMatrixElementStatus 常數

在完成距離矩陣要求後，DistanceMatrixService 會傳回特定起點與目的地對組的元素層級狀態。這些值會指定為字串，例如 'OK'。

呼叫 const {DistanceMatrixElementStatus} = await google.maps.importLibrary("routes") 即可存取。請參閱 Maps JavaScript API 中的程式庫。

常數
`NOT_FOUND`	此起點和/或目的地對組不可進行地理編碼。
`OK`	回應包含有效的結果。
`ZERO_RESULTS`	在起點和目的地之間找不到路線。