距離矩陣服務

總覽

Google 的距離矩陣服務會根據指定的交通方式,計算多個起點和終點之間的移動距離和所需時間。

這項服務不會傳回詳細的路線資訊。將想要的單一目的地和目的地傳遞至路線規劃服務,即可取得折線資訊 (包括折線和文字路線)。

開始

使用 Maps JavaScript API 的距離矩陣服務時,請先確認 Google Cloud Console 已啟用的 Distance Matrix API,與您為 Maps JavaScript API 相同的專案已啟用。

查看已啟用的 API 清單:

  1. 前往 Google Cloud Console
  2. 按一下「選取專案」按鈕,然後選取您為 Maps JavaScript API 設定的專案,然後按一下「開啟」
  3. 資訊主頁的 API 清單中,尋找 Distance Matrix API
  4. 如果清單中有這個 API,表示您已完成所有設定。如果 API 未列出 API,請啟用該 API:
    1. 選取頁面頂端的「ENABLE API」,即可顯示「Library」(資料庫) 分頁標籤。或者,從左側選單中選取 [程式庫]
    2. 搜尋「Distance Matrix API」,然後從結果清單中選取 API。
    3. 選取「啟用」。程序完成後,Distance Matrix API 會顯示在資訊主頁的 API 清單中。

價格與政策

定價

新版即付即用定價方案已於 2018 年 7 月 16 日生效,適用於地圖介面集、路徑介面集和地點介面集。如要進一步瞭解 JavaScript Distance Matrix 服務的新定價和用量限制,請參閱 Distance Matrix API 的用量和計費

注意:傳送到距離矩陣服務的每個查詢都受到允許元素的數量限制,其中「origins」數量乘以「destinations」數量會定義元素數量。

頻率限制

請留意其他要求的頻率限制:

無論有多少使用者共用同一個專案,系統都會對每位使用者工作階段套用頻率限制。首次載入 API 時,系統會分配元素的初始配額。這個配額用盡後,API 則會每秒對額外的要求執行頻率限制。如果在特定時間範圍內發出太多要求,API 會傳回 OVER_QUERY_LIMIT 回應代碼。

個別工作階段頻率限制可避免在用戶端要求中使用用戶端服務。對於批次要求,請使用 Distance Matrix API 網路服務

政策

距離矩陣服務的使用方式必須符合 Distance Matrix API 所述的政策

距離矩陣要求

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 包含下列欄位:

  • origins (必要):這個陣列包含一或多個地址字串、google.maps.LatLng 物件或 Place 物件,以便計算距離和時間。
  • destinations (必要):這個陣列包含一或多個地址字串、google.maps.LatLng 物件或 Place 物件,以便計算距離和時間。
  • travelMode (選用) — 計算路線時使用的交通模式。請參閱交通方式一節。
  • transitOptions (選用) - 僅適用於 travelModeTRANSIT 的要求的選項。如需有效值的說明,請參閱大眾運輸選項一節。
  • drivingOptions (選用) 可指定僅適用於 travelModeDRIVING 的要求。如需有效值的說明,請參閱駕駛選項一節。
  • unitSystem (選用):顯示距離時使用的單位系統。接受的值如下:
    • google.maps.UnitSystem.METRIC (預設)
    • google.maps.UnitSystem.IMPERIAL
  • avoidHighways (選用) — 如果設為 true,系統會計算起點和目的地之間的路徑,盡可能避開高速公路。
  • avoidTolls (選用) — 如果設為 true,系統會盡可能使用非收費路段計算路線之間的路線。

交通模式

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

  • BICYCLING 會要求提供單車路線 (由單車和道路提供) 的行車路線 (目前僅有美國和部分加拿大城市)。
  • DRIVING (預設) 表示使用道路網路的標準行車路線。
  • TRANSIT 要求使用大眾運輸路線規劃路線。只有在要求包含 API 金鑰時,才能指定這個選項。請參閱大眾運輸選項一節,瞭解這類要求的可用選項。
  • WALKING 要求使用人行道與步行道取得步行路線 (如果有的話)。

大眾運輸選項

大眾運輸服務目前處於「實驗」階段。在這個階段,我們將實施頻率限制,以免 API 遭到濫用。最終,我們會根據 API 的合理使用原則,針對每次地圖載入作業強制執行總查詢上限。

距離矩陣要求的可用選項會因交通模式而異。在大眾運輸要求中,系統會忽略 avoidHighwaysavoidTolls 選項。您可以透過 TransitOptions 物件常值,指定大眾運輸專屬的轉送選項。

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

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

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

這些欄位的說明如下:

  • arrivalTime (選用) 會將所需的抵達時間指定為 Date 物件。如未指定抵達時間,系統會忽略出發時間。
  • departureTime (選用) 將所需的出發時間指定為 Date 物件。如果指定 arrivalTime,系統會忽略 departureTime。如未指定 departureTimearrivalTime 的值,則預設為現在 (也就是目前時間)。
  • modes (選用) 陣列包含一或多個 TransitMode 物件常值。要求必須含有 API 金鑰,才能加入這個欄位。每個 TransitMode 都會指定偏好的交通方式。可使用的值如下:
    • BUS 表示計算的路線最好使用公車行駛。
    • RAIL 表示計算的路線最好是火車、電車、輕軌和地鐵。
    • SUBWAY 表示計算的路線最好使用地鐵行駛。
    • TRAIN 表示計算的路線最好使用火車行駛。
    • TRAM 表示計算的路線偏好電車和輕軌電車。
  • routingPreference (選用) 指定大眾運輸路線的偏好設定。使用這個選項時,您可以自訂傳回的選項,而不是接受 API 選擇的預設最佳路徑。只有在要求含有 API 金鑰時,才能指定這個欄位。可使用的值如下:
    • FEWER_TRANSFERS 表示計算的路線應視為有限的轉乘次數。
    • LESS_WALKING 表示計算的路線偏好步行距離。

駕駛選項

請使用 drivingOptions 物件來指定出發時間,以便根據預期的流量條件計算前往目的地的最佳路線。您也可以指定要根據歷來流量條件和即時流量,預估預估交通時間是否精準、最理想,或是最接近預估時間。

drivingOptions 物件包含下列欄位:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

這些欄位的說明如下:

  • departureTime (drivingOptions 物件常值有效時) 可將所需的出發時間指定為 Date 物件。這個值必須設為目前時間,也可設為未來的時間,不得設為過去的日期。(API 會將所有日期轉換為世界標準時間,確保所有時區均能妥善處理)。如果您在要求中加入 departureTime,API 會根據當下預期的路況條件傳回最佳路徑,並在回應中納入預測的流量 (duration_in_traffic)。如未指定出發時間 (也就是如果要求不包含 drivingOptions),則傳回的路徑通常是一般最佳路線,而未將流量條件納入考量。

    注意:如未指定出發時間,路線和所需時間的選擇是以道路網路和平均所需時間依路況而異。特定道路的結果可能會隨道路網路的變化、平均路況條件以及服務的分散式性質而改變。此外,結果可能隨時處於近乎同等路徑之間,或頻率不一。

  • trafficModel (選用) 指定在計算流量時要使用的假設。這項設定會影響回應中 duration_in_traffic 欄位傳回的值,其中包含根據歷來平均值估算出的流量時間。預設為 best_guess。可使用的值如下:
    • bestguess (預設) 表示傳回的 duration_in_traffic 應為最佳交通時間預估,因為系統會參考歷來車流量狀況和即時路況。departureTime 目前越接近即時流量,
    • pessimistic 表示傳回的 duration_in_traffic 大部分天數都應比實際交通時間長,但在某些情況下,路況不良的路況不佳時可能會超過這個值。
    • optimistic 表示傳回的 duration_in_traffic 多數日期都應比實際交通時間短,不過偶爾路況特別良好的路況可能會比這個值更快。

以下是行車路線的 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'
  }
}

距離矩BC回應

成功呼叫距離矩陣服務會傳回 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"
      }
    } ]
  } ]
}

距離矩陣結果

以下是回應中所支援的欄位。

  • originAddresses 是一個陣列,其中包含在距離矩陣要求的 origins 欄位中傳遞的位置。地址會在 Geocoder 格式化地址時傳回。
  • destinationAddresses 是一個陣列,其中包含 destinations 欄位傳遞的位置,以地理編碼器傳回的格式。
  • rowsDistanceMatrixResponseRow 物件的陣列,每列對應一個來源。
  • elementsrows 的子項,會對應資料列的來源與每個目的地的配對。其中包含每個出發地/目的地組合的狀態、時間長度、距離和票價資訊 (如果有的話)。
  • 每個 element 都包含下列欄位:
    • status:如需可能的狀態碼清單,請參閱狀態碼
    • duration:行駛這個路線所需的時間,以秒為單位 (value 欄位) 和 text。文字值的格式取決於要求中指定的 unitSystem (如未提供偏好設定,則以指標為單位)。
    • duration_in_traffic:規劃這條路線所需的時間長度,以目前路況 (以 value 欄位表示) 和 text 表示。文字值的格式取決於要求中指定的 unitSystem (如未提供偏好設定,則以指標為單位)。「duration_in_traffic」只會傳回可提供路況資料的 Google 地圖平台付費方案客戶、mode 設為 driving,且系統會將 departureTime 包含在要求中的 distanceMatrixOptions 欄位中。
    • distance:這個路徑的總距離,以公尺 (value) 和 text 表示。文字要求的格式取決於要求中指定的 unitSystem (如未提供偏好設定,則以指標為準)。
    • fare:包含這個航線的總票價 (也就是車票總費用)。這個屬性僅適用於大眾運輸要求,以及含有票價資訊的大眾運輸服務供應商。這類資訊包括:
      • currencyISO 4217 貨幣代碼,代表金額使用的貨幣。
      • value:總票價金額,以上方指定的貨幣為單位。

狀態碼

距離矩陣回應包含整個回應的狀態碼,以及每個元素的狀態。

回應狀態碼

套用至 DistanceMatrixResponse 的狀態碼會傳遞到 DistanceMatrixStatus 物件中,包括:

  • OK:要求有效。即使在任何來源和目的地之間找不到任何路徑,系統仍可能傳回這個狀態。如要瞭解元素層級的狀態,請參閱元素狀態碼
  • INVALID_REQUEST:提供的要求無效。這通常是缺少必要欄位所致。請參閱上方的支援欄位清單
  • MAX_ELEMENTS_EXCEEDED:來源和目的地的產品超過「每個查詢的限制」
  • MAX_DIMENSIONS_EXCEEDED:您的要求中包含超過 25 個來源,或超過 25 個目的地。
  • OVER_QUERY_LIMIT:您的應用程式在允許的時間範圍內要求過多元素。請過一段時間後再試一次。
  • REQUEST_DENIED — 服務已拒絕您的網頁使用距離矩陣服務。
  • UNKNOWN_ERROR — 伺服器發生錯誤,因此無法處理距離矩陣要求。如果您再試一次,要求可能會成功。

元素狀態碼

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

  • NOT_FOUND — 無法對這個配對的來源和/或目的地進行地理編碼。
  • OK:回應包含有效的結果。
  • ZERO_RESULTS — 無法找到起點和目的地之間的路線。

剖析結果

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];
      }
    }
  }
}