您已全部設定完成!

若要開始開發,請參閱我們的開發人員文件

啟用 Google Maps JavaScript API

為協助您開始,我們將先引導您使用「Google 開發人員控制台」來執行一些動作:

  1. 建立或選擇專案
  2. 啟用 Google Maps JavaScript API 與相關服務
  3. 建立適當的金鑰
繼續

Distance Matrix 服務

總覽

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

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

開始使用

使用 Google Maps JavaScript API 中的距離矩陣服務之前,請先確定已在 Google API Console (您針對 Google Maps JavaScript API 設定的相同專案中)中啟用 Google Maps Distance Matrix API。

檢視已啟用的 API 清單:

  1. 前往 Google API Console
  2. 按一下 [Select a project] 按鈕,選取您針對 Google Maps JavaScript API 設定的相同專案,然後按一下 [Open]
  3. 對於 [Dashboard] 上的 API 清單,請搜尋 Google Maps Distance Matrix API
  4. 如果您在該清單中看到 API,表示您已設定好。如果列出該 API,請將它啟用:
    1. 在頁面頂端,選取 [ENABLE API] 以顯示 [Library] 標籤。或者,從左側選單,選取 [Library]
    2. 搜尋 Google Maps Distance Matrix API,然後從結果清單中選取它。
    3. 選取 [ENABLE]。當此程序完成時,Google Maps Distance Matrix API 會出現在 [Dashboard] 上的 API 清單中。

使用限制與政策

配額

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

注意:傳送至距離矩陣服務之每個查詢受允許元素數目的限定,「起點」數目乘以「目的地」的數目限定元素數目。

搭配「標準方案」使用距離矩陣服務

  • 每天可以有 2,500 個免費元素(用戶端與伺服器端查詢合計); 啟用計費功能要存取更高的每日配額,我們便會以每 1000 個額外元素 $0.50 美元向您收費,而每天的元素數目上限則為 100,000 個。
  • 每個要求最多能有 25 個起點或 25 個目的地。
  • 每個要求最多能有 100 個元素。
  • 每秒最多能有 100 個元素,併入用戶端與伺服器端查詢的加總一起計算。

搭配「進階方案」使用距離矩陣服務

  • 每 24 小時 100,000 個元素的共用每日免費配額;額外要求根據年度購買 Maps APIs Credits 的量執行。
  • 每個要求最多能有 25 個起點或 25 個目的地。
  • 每個要求最多能有 625 個元素。注意:當 mode=driving 限制為每個要求能有100 個元素時,要求會使用選擇性參數 departure_time
  • 每個專案每秒 無限制 個用戶端元素。注意,伺服器端 API 限制為每秒 1,000 個元素。

速率限制適用於每個使用者工作階段,無論有幾個使用者共用相同的專案都是一樣。

每個工作階段的速率限制可防止針對批次要求使用用戶端服務。對於批次要求,請使用 Google Maps Distance Matrix API Web 服務

政策

使用距離矩陣服務時必須符合 Google Maps Distance Matrix API 政策

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: '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 物件或 google.maps.Place 物件的陣列,用來計算距離與時間。
  • destinations (必要) - 包含一或多個地址字串、google.maps.LatLng 物件或 google.maps.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 的合理使用狀況,對每個地圖載入的查詢採取總量管制。

Distance Matrix 要求的可用選項會根據不同的旅行模式而改變。如果是大眾運輸要求,就會忽略 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 物件指定開車路線的路線選項。如果您要在 DistanceMatrixRequest 中包含 drivingOptions 欄位,則必須在載入 API 時提供 Google Maps APIs Premium Plan 用戶端 ID

DrivingOptions 物件包含下列欄位:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

這些欄位說明如下:

  • departureTime (需有此欄位,drivingOptions 物件常值才有效) 以 Date 物件指定想要的出發時間。該值必須設定為目前時間或未來的某個時間。它不能是過去的時間。(API 會將所有的日期轉換為 UTC,以確保跨時區之處理方式的一致性)。針對 Google Maps APIs Premium Plan 客戶,如果您在要求中包括 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'
  }
}

Distance Matrix 回應

成功呼叫 Distance Matrix 服務會傳回一個 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"
      }
    } ]
  } ]
}

Distance Matrix 結果

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

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

傳送您對下列選項的寶貴意見...

這個網頁
Google Maps JavaScript API
Google Maps JavaScript API
需要協助嗎?請前往我們的支援網頁