Method: computeRouteMatrix

擷取起點與目的地清單,並傳回包含每個起點與目的地組合路線資訊的串流。

注意:這個方法需要您在輸入內容中指定回應欄位遮罩。如要提供回應欄位遮罩,您可以使用網址參數 $fieldsfields,或是使用 HTTP/gRPC 標頭 X-Goog-FieldMask (請參閱可用的網址參數和標頭)。值是以逗號分隔的欄位路徑清單。請參閱有關如何建構欄位路徑的詳細說明文件。

例如,在以下方法中:

  • 所有可用欄位的欄位遮罩 (適用於手動檢查):X-Goog-FieldMask: *
  • 路線持續時間、距離、元素狀態、條件,以及元素索引 (產生設定範例) 的欄位遮罩:X-Goog-FieldMask: originIndex,destinationIndex,status,condition,distanceMeters,duration

請務必在欄位遮罩中加入 status,否則所有郵件都能正常顯示。Google 不建議使用萬用字元 (*) 回應欄位遮罩,原因如下:

  • 只選取您需要的欄位有助於我們的伺服器節省運算週期,我們便能縮短傳回結果的延遲時間。
  • 只選取實際工作環境工作中所需的欄位,可確保延遲時間穩定。我們日後可能會新增更多回應欄位,而這些新欄位可能需要額外的運算時間。如果選取所有欄位,或是選取頂層欄位的所有欄位,可能會出現成效降低的情形,這是因為我們新增的所有新欄位都會自動納入回應中。
  • 因此,如果只選取需要的欄位,回應大小會較小,網路處理量也會提高。

HTTP 要求

POST https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix

這個網址使用 gRPC 轉碼語法。

要求主體

要求主體的資料會採用以下結構:

JSON 表示法
{
  "origins": [
    {
      object (RouteMatrixOrigin)
    }
  ],
  "destinations": [
    {
      object (RouteMatrixDestination)
    }
  ],
  "travelMode": enum (RouteTravelMode),
  "routingPreference": enum (RoutingPreference),
  "departureTime": string,
  "arrivalTime": string,
  "languageCode": string,
  "regionCode": string,
  "extraComputations": [
    enum (ExtraComputation)
  ],
  "trafficModel": enum (TrafficModel),
  "transitPreferences": {
    object (TransitPreferences)
  }
}
欄位
origins[]

object (RouteMatrixOrigin)

必要欄位。起點陣列,會決定回應矩陣的資料列。起點和目的地的基數有幾種大小限制:

  • 起點數 + 指定為 placeIdaddress 指定的目的地數量總和,不得超過 50。
  • 起點數量 × 目的地數 (不限) 不得超過 625。
  • 如果 routePreference 設為 TRAFFIC_AWARE_OPTIMAL,出發地數量 × 目的地數不得大於 100。
  • 當 TravelMode 設為 TRANSIT 時,出發地數量 × 目的地數不得大於 100。
destinations[]

object (RouteMatrixDestination)

必要欄位。目的地陣列,會決定回應矩陣的資料欄。

travelMode

enum (RouteTravelMode)

選用設定。指定交通方式。

routingPreference

enum (RoutingPreference)

選用設定。指定路線計算方式。伺服器會嘗試使用所選轉送偏好設定來計算路徑。如果轉送偏好設定產生錯誤或額外的長時間延遲時間,系統會傳回錯誤。您只能在 travelModeDRIVETWO_WHEELER 時指定這個選項,否則要求會失敗。

departureTime

string (Timestamp format)

選用設定。出發時間。如果您沒有設定這個值,這個值會預設為您提出要求的時間。注意:當 RouteTravelMode 設為 TRANSIT 時,您只能指定過去的 departureTime

RFC3339 世界標準時間「Zulu」格式的時間戳記,採用奈秒解析度,且最多 9 個小數位數。範例:"2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

arrivalTime

string (Timestamp format)

選用設定。抵達時間。注意:只有在 RouteTravelMode 設為 TRANSIT 時才能設定。您可以指定 departureTimearrivalTime,但不能同時指定兩者。

RFC3339 世界標準時間「Zulu」格式的時間戳記,採用奈秒解析度,且最多 9 個小數位數。範例:"2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

languageCode

string

選用設定。BCP-47 語言代碼,例如「en-US」或「sr-Latn」。詳情請參閱 Unicode 語言代碼 ID。如需支援的語言清單,請參閱語言支援。如果未提供這個值,系統會根據第一個起點的位置推斷顯示語言。

regionCode

string

選用設定。區碼,指定為 ccTLD (「頂層網域」) 的兩位字元值詳情請參閱國家/地區代碼頂層網域

extraComputations[]

enum (ExtraComputation)

選用設定。額外運算清單,可用於完成要求。注意:這些額外運算可能會在回應中傳回額外的欄位。您必須在欄位遮罩中指定這些額外欄位,才能在回應中傳回。

trafficModel

enum (TrafficModel)

選用設定。指定計算交通時間時要採用的假設。這項設定會影響 RouteMatrixElement 中時間長度欄位傳回的值,其中包含根據歷來平均值預估的交通時間。從 RoutingPreference 飛往 TRAFFIC_AWARE_OPTIMAL,將 RouteTravelMode 重新命名為 DRIVE。如要求流量,但未指定 TrafficModel,則預設值為 BEST_GUESS

transitPreferences

object (TransitPreferences)

選用設定。指定會影響 TRANSIT 路線傳迴路線的偏好設定。注意:只有在 RouteTravelMode 設為 TRANSIT 時,您才能指定 transitPreferences

回應主體

包含針對 v2.computeRouteMatrix API 中的起點/目的地組合運算的路徑資訊。這個 proto 可串流至用戶端。

如果成功,回應主體即會包含具有以下結構的資料:

JSON 表示法
{
  "status": {
    object (Status)
  },
  "condition": enum (RouteMatrixElementCondition),
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  },
  "fallbackInfo": {
    object (FallbackInfo)
  },
  "localizedValues": {
    object (LocalizedValues)
  },
  "originIndex": integer,
  "destinationIndex": integer
}
欄位
status

object (Status)

這個元素的錯誤狀態碼。

condition

enum (RouteMatrixElementCondition)

用於指出是否已找到路線。與狀態無關。

distanceMeters

integer

路線的移動距離 (以公尺為單位)。

duration

string (Duration format)

導航路線所需的時間。如果將 routingPreference 設為 TRAFFIC_UNAWARE,則這個值與 staticDuration 相同。如果您將 routingPreference 設為 TRAFFIC_AWARETRAFFIC_AWARE_OPTIMAL,這個值會將路況納入考量。

持續時間以秒為單位,最多 9 個小數位數,結尾為「s」,例如:"3.5s"

staticDuration

string (Duration format)

行經路線時未將路況納入考量。

持續時間以秒為單位,最多 9 個小數位數,結尾為「s」,例如:"3.5s"

travelAdvisory

object (RouteTravelAdvisory)

路線的其他資訊。例如:限制資訊和收費資訊

fallbackInfo

object (FallbackInfo)

在某些情況下,當伺服器無法根據此特定起點/目的地組合的指定偏好設定計算路線時,可能會改回採用其他計算模式。如果您使用備用模式,這個欄位會包含備用回應的詳細資訊。否則就不會設定這個欄位。

localizedValues

object (LocalizedValues)

RouteMatrixElement 屬性的文字表示法。

originIndex

integer

要求中的來源,從零開始。

destinationIndex

integer

要求中的目的地索引 (從零開始)。

RouteMatrixOrigin

ComputeRouteMatrixRequest 的單一來源

JSON 表示法
{
  "waypoint": {
    object (Waypoint)
  },
  "routeModifiers": {
    object (RouteModifiers)
  }
}
欄位
waypoint

object (Waypoint)

必要欄位。起點路線控點

routeModifiers

object (RouteModifiers)

選用設定。每條路徑的修飾符

RouteMatrixDestination

ComputeRouteMatrixRequest 的單一目的地

JSON 表示法
{
  "waypoint": {
    object (Waypoint)
  }
}
欄位
waypoint

object (Waypoint)

必要欄位。目的地路線控點

ExtraComputation

完成要求時要執行的額外運算。

列舉
EXTRA_COMPUTATION_UNSPECIFIED 未使用。包含這個值的要求將會失敗。
TOLLS 矩陣元素的收費資訊。

RouteMatrixElementCondition

傳回的路線狀況。

列舉
ROUTE_MATRIX_ELEMENT_CONDITION_UNSPECIFIED 只有在元素的 status 不適用時才能使用。
ROUTE_EXISTS 系統已找到路徑,並已填入該元素的對應資訊。
ROUTE_NOT_FOUND 找不到路線。對於包含路線資訊 (例如 distanceMetersduration) 的欄位,系統不會在元素中填入值。

LocalizedValues

特定屬性的文字表示法。

JSON 表示法
{
  "distance": {
    object (LocalizedText)
  },
  "duration": {
    object (LocalizedText)
  },
  "staticDuration": {
    object (LocalizedText)
  },
  "transitFare": {
    object (LocalizedText)
  }
}
欄位
distance

object (LocalizedText)

以文字表示的旅程距離。

duration

object (LocalizedText)

將交通狀況納入考量的文字格式時,以文字形式表示的持續時間。注意:如未要求流量資訊,這個值會與 staticDuration 值相同。

staticDuration

object (LocalizedText)

以文字格式表示的持續時間,未將路況納入考量。

transitFare

object (LocalizedText)

以文字呈現的大眾運輸車資。