Route Matrix (beta)

RouteMatrix class

google.maps.routes.RouteMatrix class

RouteMatrix.computeRouteMatrix 為一組起點/目的地組合計算的路線矩陣

撥打 const {RouteMatrix} = await google.maps.importLibrary("routes") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
computeRouteMatrix
computeRouteMatrix(request)
參數： 
傳回值：  Promise<{matrix:RouteMatrix}>
接收起點和目的地清單，並傳回矩陣，其中包含每個起點和目的地組合的路線資訊。

注意：使用這個方法時，您必須設定 ComputeRouteMatrixRequest.fields 屬性，在要求中指定回應欄位遮罩。此值為欄位路徑清單。

例如：
  • 所有可用欄位的欄位遮罩：fields: ['*']
  • 路線層級時間和距離的欄位遮罩：fields: ['durationMillis', 'distanceMeters']

不建議使用萬用字元回應欄位遮罩 fields: ['*']，原因如下：
  • 只選取需要的欄位，有助於伺服器節省運算週期，讓我們以較低的延遲時間將結果傳回給您。
  • 在實際執行作業中只選取所需欄位，可確保延遲效能穩定。我們日後可能會新增更多回應欄位，而這些新欄位可能需要額外的運算時間。如果您選取所有欄位，或是在頂層選取所有欄位，系統可能會自動在回應中加入我們新增的欄位，導致效能降低。
  • 只選取所需欄位可縮減回應大小，因此透過網路載入的速度會更快。
rows
類型：  Array<RouteMatrixRow>
矩陣的列。每一列都對應一個起點，並包含 RouteMatrixItem 陣列，其中每個元素都代表前往目的地的路線。
toJSON
toJSON()
參數：無
傳回值：  Object
轉換為物件。

RouteMatrixRow class

google.maps.routes.RouteMatrixRow class

對應傳遞至 RouteMatrix.computeRouteMatrix 的來源。包含 RouteMatrixItem 清單，每個項目代表前往目的地的路線。

撥打 const {RouteMatrixRow} = await google.maps.importLibrary("routes") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
items
類型：  Array<RouteMatrixItem>
每個目的地的路線資訊。
toJSON
toJSON()
參數：無
傳回值：  Object
轉換為物件。

RouteMatrixItem class

google.maps.routes.RouteMatrixItem class

包含為傳遞至 RouteMatrix.computeRouteMatrix 的起點/目的地組合計算的路線資訊。

撥打 const {RouteMatrixItem} = await google.maps.importLibrary("routes") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
condition
類型：  RouteMatrixItemCondition optional
指出是否找到路線。
distanceMeters
類型：  number optional
路線的移動距離 (以公尺為單位)。
durationMillis
類型：  number optional
導覽路線所需的時間長度 (以毫秒為單位)。如果將 ComputeRouteMatrixRequest.routingPreference 設為 TRAFFIC_UNAWARE，這個值就會與 RouteMatrixItem.staticDurationMillis 相同。如果將 ComputeRouteMatrixRequest.routingPreference 設為 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL，系統會考量路況來計算這個值。

注意：如果時間長度超過 2^53 毫秒，這個值會是 Number.POSITIVE_INFINITY。
error
類型：  RouteMatrixItemError optional
計算路徑時發生的錯誤。
fallbackInfo
類型：  FallbackInfo optional
在某些情況下，如果伺服器無法根據特定起點/目的地組合的偏好設定計算路線，可能會改用其他計算模式。如果使用備援，這個欄位會包含備援回覆的詳細資訊。否則這個欄位不會設定。
localizedValues
類型：  RouteMatrixItemLocalizedValues optional
RouteMatrixItem 屬性的文字表示法。
staticDurationMillis
類型：  number optional
不考量路況的路線行車時間。

注意：如果時間長度超過 2^53 毫秒，這個值會是 Number.POSITIVE_INFINITY。
travelAdvisory
類型：  RouteTravelAdvisory optional
路線的其他資訊。

ComputeRouteMatrixRequest 介面

google.maps.routes.ComputeRouteMatrixRequest 介面

要求路線矩陣。
destinations
目的地陣列，決定回應矩陣的資料欄。以字串形式傳遞的值可以是地址、plus code 或 Place 資源名稱。系統不會考量海拔高度值。
fields
類型：  Iterable<string>
要擷取的欄位集合。為所有欄位指定 ["*"]。
origins
來源陣列，用於決定回應矩陣的資料列。以字串形式傳遞的值可以是地址、plus code 或 Place 資源名稱。系統不會考量海拔高度值。

來源和目的地的基數有幾項大小限制：
arrivalTime optional
類型：  Date optional
抵達時間。

注意：只有在「ComputeRouteMatrixRequest.travelMode」設為「TRANSIT」時，才能設定這項功能。你可以指定 ComputeRouteMatrixRequest.departureTime 或 ComputeRouteMatrixRequest.arrivalTime，但不能同時指定兩者。大眾運輸行程最多可查詢過去 7 天或未來 100 天的行程。
departureTime optional
類型：  Date optional
出發時間。如未設定這個值，系統會預設為您提出要求的時間。

注意：只有在 ComputeRouteMatrixRequest.travelMode 設為 TRANSIT 時，才能指定過去的時間。大眾運輸行程最多可查詢過去 7 天或未來 100 天的行程。
extraComputations optional
可用於完成要求的額外運算清單。

注意：這些額外運算可能會在回應中傳回額外欄位。這些額外欄位也必須在 ComputeRouteMatrixRequest.fields 中指定，才能在回應中傳回。
language optional
類型：  string optional
BCP-47 語言代碼，例如「en-US」或「sr-Latn」。詳情請參閱「Unicode 語言代碼」。如需支援的語言清單，請參閱「語言支援」一文。如果未提供這個值，系統會根據 Google Maps JavaScript API 本地化設定推斷語言。否則，系統會根據第一個來源的位置推斷語言。
region optional
類型：  string optional
區碼，指定為 ccTLD (「頂層網域」) 的兩位字元值。詳情請參閱「國家/地區代碼頂層網域」。如果未提供這個值，系統會根據 Google Maps JavaScript API 的本地化設定推斷區域。否則，系統會根據第一個來源的位置推斷地區。
routingPreference optional
類型：  RoutingPreference optional
指定如何計算路線矩陣。伺服器會嘗試使用所選路徑偏好設定計算路徑矩陣。如果路由偏好設定導致錯誤或延遲時間過長，系統會傳回錯誤。只有在 ComputeRouteMatrixRequest.travelMode 為 DRIVING 或 TWO_WHEELER 時，才能指定這個選項，否則要求會失敗。
trafficModel optional
類型：  TrafficModel optional
指定計算交通時間時要採用的假設。這項設定會影響 RouteMatrixItem.durationMillis 傳回的值，其中包含根據歷來平均值預估的交通時間。ComputeRouteMatrixRequest.trafficModel 僅適用於將 ComputeRouteMatrixRequest.routingPreference 設為 TRAFFIC_AWARE_OPTIMAL，並將 ComputeRouteMatrixRequest.travelMode 設為 DRIVING 的要求。預設值為 BEST_GUESS。
transitPreference optional
類型：  TransitPreference optional
指定偏好設定，影響 TRANSIT 路線傳回的路線。

注意：只有在 ComputeRouteMatrixRequest.travelMode 設為 TRANSIT 時才能指定。
travelMode optional
類型：  TravelMode optional
指定交通方式。
units optional
類型：  UnitSystem optional
指定顯示欄位的測量單位。如未提供這個值，系統會根據第一個來源的位置推斷顯示單位。

ComputeRouteMatrixExtraComputation 常數

google.maps.routes.ComputeRouteMatrixExtraComputation 常數

為 RouteMatrix.computeRouteMatrix 要求執行的額外運算。

撥打 const {ComputeRouteMatrixExtraComputation} = await google.maps.importLibrary("routes") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
TOLLS 矩陣項目的收費資訊。

RouteMatrixItemCondition 常數

google.maps.routes.RouteMatrixItemCondition 常數

特定出發地/目的地組合的路線狀況。

撥打 const {RouteMatrixItemCondition} = await google.maps.importLibrary("routes") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
ROUTE_EXISTS 系統找到路線。
ROUTE_NOT_FOUND 找不到路線。

RouteMatrixItemError class

google.maps.routes.RouteMatrixItemError class

特定來源/目的地配對的 RouteMatrix.computeRouteMatrix 期間發生錯誤。

這個類別會擴充 Error。

撥打 const {RouteMatrixItemError} = await google.maps.importLibrary("routes") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
toJSON
toJSON()
參數：無
傳回值：  Object
轉換為物件。

RouteMatrixItemLocalizedValues class

google.maps.routes.RouteMatrixItemLocalizedValues class

RouteMatrixItem 的文字表示法。

撥打 const {RouteMatrixItemLocalizedValues} = await google.maps.importLibrary("routes") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。
distance
類型：  string optional
以文字形式顯示路徑矩陣項目的行車距離。
distanceLanguage
類型：  string optional
距離文字的 BCP-47 語言代碼，例如「en-US」或「sr-Latn」。

詳情請參閱 http://www.unicode.org/reports/tr35/#Unicode_locale_identifier。
duration
類型：  string optional
以文字形式表示的時長，並根據查詢區域進行本地化。考量路況。

注意：如果您未要求提供流量資訊，這個值會與 RouteMatrixItemLocalizedValues.staticDuration 的值相同。
durationLanguage
類型：  string optional
時長文字的 BCP-47 語言代碼，例如「en-US」或「sr-Latn」。

詳情請參閱 http://www.unicode.org/reports/tr35/#Unicode_locale_identifier。
staticDuration
類型：  string optional
以文字形式表示的時長，未考量流量狀況。
staticDurationLanguage
類型：  string optional
靜態時間長度文字的 BCP-47 語言代碼，例如「en-US」或「sr-Latn」。
transitFare
類型：  string optional
以文字形式表示的大眾運輸票價。
transitFareLanguage
類型：  string optional
大眾運輸票價文字的 BCP-47 語言代碼，例如「en-US」或「sr-Latn」。

詳情請參閱 http://www.unicode.org/reports/tr35/#Unicode_locale_identifier。
toJSON
toJSON()
參數：無
傳回值：  Object
轉換為物件。

RouteMatrixOrigin 介面

google.maps.routes.RouteMatrixOrigin 介面

ComputeRouteMatrixRequest 的單一來源。
waypoint
來源位置。以字串形式傳遞的值可以是地址或加號代碼。系統不會考量海拔高度值。
routeModifiers optional
類型：  RouteModifiers optional
以這個地點為起點的每條路線的修飾符。