Distance Matrix 服務

總覽

Google 的 Distance Matrix 服務會使用指定的旅行模式，計算多個起點與目的地之間的旅行距離和行程時間。

此服務不會傳回詳盡的路線資訊。將目標單一起點與目的地傳遞至路線規劃服務，就能夠取得路線資訊，包括折線和文字路線規劃。

使用限制與需求

配額

Distance Matrix 服務具有下列使用限制：

• 每個要求最多能有 25 個起點或 25 個目的地；以及
• 每個要求最多能有 100 個元素 (起點數乘以目的地數)。

要求也會有速率上的限制。如果在某段時間內要求太多元素，將會傳回 OVER_QUERY_LIMIT 回應碼。

顯示 Google 地圖

使用 Distance Matrix 服務也必須關聯 Google 地圖上的資訊顯示。例如，在要求並在地圖上顯示某些目的地之前，先判斷位於指定行車時間之內的起點/目的地組合。禁止在未顯示「Google 地圖」的應用程式中使用該服務。

Distance Matrix 要求

存取 Distance Matrix 服務是非同步的，因為 Google Maps API 需要呼叫外部伺服器。所以，您需要傳遞「回呼」方法，以在要求完成時執行並處理結果。

您必須透過 google.maps.DistanceMatrixService 物件存取程式碼內的 Distance Matrix 服務。DistanceMatrixService.getDistanceMatrix() 方法會初始化對 Distance Matrix 服務的要求，並向它傳遞包含起點、目的地及旅行模式的 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: google.maps.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.
}

檢視範例 (distance-matrix.html)

DistanceMatrixRequest 包含下列欄位：

• origins (必要) - 包含一或多個地址字串和/或 google.maps.LatLng 物件的陣列，用來計算距離與時間點。
• destinations (必要) - 包含一或多個地址字串和/或 google.maps.LatLng 物件的陣列，用來計算距離與時間。
• travelMode (選擇性) - 指定計算路線規劃時要使用的運輸方式。請參閱旅行模式一節。
• transitOptions (選擇性) - 只會套用到 travelMode 為 google.maps.TravelMode.TRANSIT 之要求的選項。大眾運輸選項一節將描述有效的值。
• drivingOptions (選擇性) 指定只會套用到 travelMode 為 google.maps.TravelMode.DRIVING 之要求的值。開車選項一節將描述有效的值。
• unitSystem (選擇性) - 顯示距離時要使用的單位系統。可接受的值包括：
  • google.maps.UnitSystem.METRIC (預設)
  • google.maps.UnitSystem.IMPERIAL
• avoidHighways (選擇性) - 如果為 true，起點與目的地之間的路線將會以優先避開高速公路為前提計算。
• avoidTolls (選擇性) - 如果為 true，兩點之間的路線規劃將會以優先使用不需收費的路線為前提計算。

旅行模式

計算時間和距離時，可以指定要使用哪一種運輸模式。以下是目前支援的旅行模式：

• google.maps.TravelMode.BICYCLING 要求使用單車車道與偏好街道的單車路線規劃 (目前只能在美國和某些加拿大城市使用)。
• google.maps.TravelMode.DRIVING (預設) 指出行駛公路網的標準開車路線規劃。
• google.maps.TravelMode.TRANSIT 要求使用大眾運輸路線的路線規劃。此選項只有在要求包含 API 金鑰時才可以指定。請參閱大眾運輸選項以瞭解此要求類型的可用選項。
• google.maps.TravelMode.WALKING 要求使用人行道的步行路線規劃。

大眾運輸選項

大眾運輸服務目前仍處於「實驗性質」。在這個階段，我們將會對速率採取限制，以避免 API 遭到濫用。我們最後會根據 API 的合理使用狀況，對每個地圖載入的查詢採取總量管制。

Distance Matrix 要求的可用選項會根據不同的旅行模式而改變。如果是大眾運輸要求，就會忽略 avoidHighways 和 avoidTolls 選項。您可以透過 TransitOptions 物件常值指定針對大眾運輸的路線選項。

大眾運輸要求對於時間較為敏感。只能針對未來的時間傳回計算結果。

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

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

這些欄位說明如下：

• arrivalTime (選擇性) 以 Date 物件指定想要的抵達時間。如果已指定抵達時間，則會忽略出發時間。
• departureTime (選擇性) 以 Date 物件指定想要的出發時間。如果已指定 arrivalTime，則會忽略 departureTime。如果沒有指定 departureTime 或 arrivalTime 的值，則會預設為現在 (也就是目前的時間)。
• modes (選擇性) 是包含一或多個 TransitMode 物件常值的陣列。只有要求包括 API 金鑰時，才可以包括此欄位。每個 TransitMode 都指定一種偏好的大眾運輸模式。允許下列值：
  • google.maps.TransitMode.BUS 指出計算的路線應偏好搭乘公車。
  • google.maps.TransitMode.RAIL 指出計算的路線應偏好搭乘火車、捷運、輕軌及地下鐵。
  • google.maps.TransitMode.SUBWAY 指出計算的路線應偏好搭乘地下鐵。
  • google.maps.TransitMode.TRAIN 指出計算的路線應偏好搭乘火車。
  • google.maps.TransitMode.TRAM 指出計算的路線應偏好搭乘捷運或輕軌。
• routingPreference (選擇性) 指定大眾運輸路線的偏好設定。您可以使用此選項，調整傳回的選項，而不是接受 API 選擇的最佳預設路線。只有要求包括 API 金鑰時，才可以指定此欄位。允許下列值：
  • google.maps.TransitRoutePreference.FEWER_TRANSFERS 指出計算的路線應偏好較少的轉乘次數。
  • google.maps.TransitRoutePreference.LESS_WALKING 指出計算的路線應偏好較短的步行距離。

開車選項

您可以透過 DrivingOptions 物件指定開車路線的路線選項。如果您要在 DistanceMatrixRequest 中包含 drivingOptions 欄位，則必須在載入 API 時提供 Google Maps API for Work 用戶端 ID。

DrivingOptions 物件包含下列欄位：

{
  departureTime: Date,
  trafficModel: TrafficModel
}

這些欄位說明如下：

• departureTime (需有此欄位，drivingOptions 物件常值才有效) 以 Date 物件指定想要的出發時間。該值必須設定為目前時間或未來的某個時間。它不能是過去的時間。(API 會將所有的日期轉換為 UTC，以確保跨時區之處理方式的一致性)。針對 Google Maps API for Work 客戶，如果您在要求中包括 departureTime，API 會傳回當時預期路況的最佳路線，並在回應中包括預測的交通時間 (duration_in_traffic)。如果您沒有指定出發時間 (亦即如果沒有在要求中包括 drivingOptions)，則傳回的路線將會是不考量路況下的一般最佳路線。
• trafficModel (選擇性) 指定計算交通時間時要使用的假設。此設定會影響回應中以 duration_in_traffic 欄位傳回的值，包含的值是根據歷史平均值預測的旅行時間。預設為 best_guess。允許下列值：
  • google.maps.TrafficModel.BEST_GUESS (預設) 或 best_guess 字串值指出傳回的 duration_in_traffic 應是考量歷史路況與即時路況下的最佳預估旅行時間。departureTime 越接近現在時間，即時路況就越重要。
  • google.maps.TrafficModel.PESSIMISTIC 或 pessimistic 字串值指出傳回的 duration_in_traffic 通常應該會比實際的旅行時間更長，雖然偶爾在路況特別壅塞的日子還是會超過此值。
  • google.maps.TrafficModel.OPTIMISTIC 或 optimistic 字串值指出傳回的 duration_in_traffic 通常應該會比實際的旅行時間更短，雖然偶爾在路況特別順暢的日子還是會比此值更快。

以下是開車路線的範例 DistanceMatrixRequest，包括出發時間和路況：

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

Distance Matrix 回應

成功呼叫 Distance Matrix 服務會傳回一個 DistanceMatrixResponse 物件和一個 DistanceMatrixStatus 物件。這些物件會傳遞至您在要求中指定的回呼函式。

DistanceMatrixResponse 物件包含針對每組可計算路線之起點/目的地配對的距離和時間資訊。

{
  "origin_addresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
  "destination_addresses": [ "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"
      }
    } ]
  } ]
}

Distance Matrix 結果

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

• originAddresses 是一個包含在 Distance Matrix 要求的 origins 欄位中傳遞之位置的陣列。地址會以由地理編碼器所格式化的形式傳回。
• destinationAddresses 是一個包含在 destinations 欄位中傳遞之位置的陣列，並且是由地理編碼器所傳回的格式。
• rows 是一個 DistanceMatrixResponseRow 物件的陣列，每一列都對應到一個起點。
• elements 是 rows 的子項，並與每列起點與個別目的地的配對相對應。它們包含每組起點/目的地配對的狀態、時間、距離和票價資訊 (如果有提供的話)。
• 每個 element 包含下列欄位：
  • status：如需可能的狀態碼清單，請參閱狀態碼。
  • duration：於此路線旅行所需花費的時間長度，以秒 (value 欄位) 表示並顯示為 text。文字值的格式會依照要求中指定的 unitSystem 來顯示 (如果沒有提供任何偏好，則使用公制單位)。
  • duration_in_traffic：於此路線旅行並考量目前路況之下，所需花費的時間長度，以秒表示 (value 欄位) 並顯示為 text。文字值的格式會依照要求中指定的 unitSystem 來顯示 (如果沒有提供任何偏好，則使用公制單位)。只有在有路況資料、mode 設為 driving，而且要求中的 distanceMatrixOptions 欄位有包括 departureTime 時，才會對 Google Maps API for Work 客戶傳回 duration_in_traffic。
  • distance：此路線的總距離，以公尺表示 (value) 並顯示為 text。文字值的格式會依照要求中指定的 unitSystem 來顯示 (如果沒有提供任何偏好，則使用公制單位)。
  • fare：包含此路線的總票價 (也就是車票的總花費)。只有大眾運輸要求，並在大眾運輸業者有提供票價資訊時才會傳回此屬性。資訊包括：
    • currency：ISO 4217 貨幣代碼，指出用以表示金額的貨幣。
    • value：總票價金額，以上述貨幣指定。

狀態碼

Distance Matrix 回應包括回應整體的狀態碼，也包括個別元素的狀態。

回應狀態碼

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

• OK - 要求為有效。此狀態即使在所有起點與目的地之間都找不到任何路線的情況下也可以傳回。請參閱元素狀態碼以瞭解元素層級的狀態資訊。
• INVALID_REQUEST - 提供的要求無效。這通常是因為缺少必要的欄位。請參閱上面的支援的欄位清單。
• MAX_ELEMENTS_EXCEEDED - 起點數和目的地數的乘積超過每次查詢限制。
• MAX_DIMENSIONS_EXCEEDED - 您的要求內含超過 25 個起點，或超過 25 個目的地。
• OVER_QUERY_LIMIT - 您的應用程式在允許的期間內要求過多元素。在一段合理的時間之後重新嘗試該要求或許會成功。
• REQUEST_DENIED - 服務拒絕您的網頁使用 Distance Matrix 服務。
• UNKNOWN_ERROR - 由於發生伺服器錯誤，而無法處理 Distance Matrix 要求。重新嘗試該要求或許會成功。

元素狀態碼

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

• NOT_FOUND - 此配對的起點和/或目的地無法進行地理編碼。
• OK - 回應包含有效的結果。
• ZERO_RESULTS - 在起點與目的地之間找不到任何路線。

剖析結果

DistanceMatrixResponse 物件針對個別於要求中傳遞的起點都包含一個 row。每一列都包含一個針對該起點與所提供目的地之配對的 element 欄位。

function callback(response, status) {
  if (status == google.maps.DistanceMatrixStatus.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];
      }
    }
  }
}