距離矩陣服務 (original) (raw)

歐洲經濟區 (EEA) 開發人員

注意：伺服器端程式庫

總覽

Google 的距離矩陣服務會計算在使用特定交通方式的情況下，多個起點與目的地之間的移動距離和旅途所需時間。

這項服務不會傳回詳細的路線資訊。您只要將所需的單一起點與目的地傳遞至路線規劃服務，就可以取得包括折線和文字導航在內的路線資訊。

開始使用

請先在 Google Cloud 控制台中，確認您為 Maps JavaScript API 設定的專案已啟用 Distance Matrix API (舊版)，再使用 Maps JavaScript API 中的距離矩陣服務。

如要查看已啟用的 API 清單，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台。
  2. 按一下「Select a project」(選取專案) 按鈕，選取您為 Maps JavaScript API 設定的專案，然後點選「Open」(開啟)。
  3. 在「資訊主頁」的 API 清單中，找出 **Distance Matrix API (舊版)**。
  4. 如果在清單中看到該 API，表示一切就緒。如果未列出 API，請前往 https://console.cloud.google.com/apis/library/distance-matrix-backend.googleapis.com 啟用 API

定價和政策

定價

如要瞭解 JavaScript 距離矩陣服務的價格和使用政策，請參閱 Distance Matrix API (舊版) 的「用量與計費」一文。

注意：傳送至距離矩陣服務的每筆查詢都有可用元素數量上限，其中「起點」數量乘以「目的地」數量就等於元素數量。

政策

使用距離矩陣服務時，必須遵守 Distance Matrix API (舊版) 的既定政策。

Distance Matrix 要求

Google Maps API 必須呼叫外部伺服器，因此距離矩陣服務是以非同步的方式存取。基於這個理由，您必須傳遞在完成要求後執行的「回呼」方法，才能處理結果。

您可以透過 google.maps.DistanceMatrixService 建構函式物件，在程式碼內存取距離矩陣服務。DistanceMatrixService.getDistanceMatrix() 方法會向距離矩陣服務發出要求，並將含有起點、目的地和交通方式的 DistanceMatrixRequest 物件常值，以及收到回應後要執行的回呼方法傳遞至該服務。

var origin1 = new google.maps.LatLng(55.930385, -3.118425); var origin2 = 'Greenwich, England'; var destinationA = 'Stockholm, Sweden'; var destinationB = new google.maps.LatLng(50.087692, 14.421150);

var service = new google.maps.DistanceMatrixService(); service.getDistanceMatrix( { origins: [origin1, origin2], destinations: [destinationA, destinationB], travelMode: 'DRIVING', transitOptions: TransitOptions, drivingOptions: DrivingOptions, unitSystem: UnitSystem, avoidHighways: Boolean, avoidTolls: Boolean, }, callback);

function callback(response, status) { // See Parsing the Results for // the basics of a callback function. }

查看範例

DistanceMatrixRequest 包含下列欄位：

交通方式

計算時間和距離時，您可以指定要使用的交通方式。目前支援下列交通方式︰

大眾運輸選項

大眾運輸服務目前處於「實驗」階段。在這個階段中，我們會實施頻率限制來防止 API 遭到濫用。我們最終會根據 API 的公平使用原則，設定每次地圖上傳的總查詢次數上限。

距離矩陣要求的可用選項會因交通方式而異。在大眾運輸要求中，系統會略過 avoidHighways 和 avoidTolls 選項。您可以透過 TransitOptions 物件常值，指定大眾運輸專屬的路線選項。

大眾運輸要求具有時效性。系統只會傳回未來時間的計算結果。

TransitOptions 物件常值包含下列欄位：

{ arrivalTime: Date, departureTime: Date, modes: [transitMode1, transitMode2] routingPreference: TransitRoutePreference }

這些欄位的說明如下：

行車選項

請使用 drivingOptions 物件來指定出發時間，以便根據預期的路況計算前往目的地的最佳路線。此外，您也可以指定系統是否要根據歷來路況和即時車流量，保守、大膽或精準預估交通時間。

drivingOptions 物件包含下列欄位：

{ departureTime: Date, trafficModel: TrafficModel }

這些欄位的說明如下：

以下是行車路線的 DistanceMatrixRequest 範例，包括出發時間和車流量模型：

{ origins: [{lat: 55.93, lng: -3.118}, 'Greenwich, England'], destinations: ['Stockholm, Sweden', {lat: 50.087, lng: 14.421}], travelMode: 'DRIVING', drivingOptions: { departureTime: new Date(Date.now() + N), // for the time N milliseconds from now. trafficModel: 'optimistic' } }

距離矩陣回應

如果距離矩陣服務呼叫成功，就會傳回 DistanceMatrixResponse 和 DistanceMatrixStatus 物件，這些物件會傳遞至要求中指定的回呼函式。

DistanceMatrixResponse 物件會針對可計算路線的每個起點/目的地組合，提供距離和所需時間資訊。

{ "originAddresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ], "destinationAddresses": [ "Stockholm County, Sweden", "Dlouhá 609/2, 110 00 Praha-Staré Město, Česká republika" ], "rows": [ { "elements": [ { "status": "OK", "duration": { "value": 70778, "text": "19 hours 40 mins" }, "distance": { "value": 1887508, "text": "1173 mi" } }, { "status": "OK", "duration": { "value": 44476, "text": "12 hours 21 mins" }, "distance": { "value": 1262780, "text": "785 mi" } } ] }, { "elements": [ { "status": "OK", "duration": { "value": 96000, "text": "1 day 3 hours" }, "distance": { "value": 2566737, "text": "1595 mi" } }, { "status": "OK", "duration": { "value": 69698, "text": "19 hours 22 mins" }, "distance": { "value": 1942009, "text": "1207 mi" } } ] } ] }

距離矩陣結果

以下說明回應中支援的欄位。

狀態碼

距離矩陣回應包含整個回應的狀態碼，以及各項元素的狀態。

回應狀態碼

適用於 DistanceMatrixResponse 的狀態碼會在 DistanceMatrixStatus 物件中傳遞，其中包括：

元素狀態碼

下列狀態碼適用於特定的 DistanceMatrixElement物件：

剖析結果

DistanceMatrixResponse 物件中包含的 row 會各自對應到要求中傳遞的各個起點，而每一列包含的 element 欄位，又會對應到該起點與所提供目的地的每個組合。

function callback(response, status) { if (status == 'OK') { var origins = response.originAddresses; var destinations = response.destinationAddresses;

for (var i = 0; i < origins.length; i++) {
  var results = response.rows[i].elements;
  for (var j = 0; j < results.length; j++) {
    var element = results[j];
    var distance = element.distance.text;
    var duration = element.duration.text;
    var from = origins[i];
    var to = destinations[j];
  }
}

} }