- HTTP 要求
- 要求主體
- 回應主體
- RouteMatrixOrigin
- RouteMatrixDestination
- ExtraComputation
- RouteMatrixElementCondition
- LocalizedValues
取得起點和目的地清單,並傳回一個串流,其中包含每個起點和目的地組合的路線資訊。
注意:這種方法需要在輸入中指定回應欄位遮罩。如要提供回應欄位遮罩,您可以使用網址參數 $fields
或 fields
,或是使用 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 ( |
欄位 | |
---|---|
origins[] |
必要欄位。來源陣列,用來決定回應矩陣的資料列。出發地和目的地的基數有幾種大小限制:
|
destinations[] |
必要欄位。目的地陣列,用於決定回應矩陣的資料欄。 |
travelMode |
選用設定。指定交通方式。 |
routingPreference |
選用設定。指定路線的計算方式。伺服器會嘗試使用所選的轉送偏好設定計算路徑。如果轉送偏好設定導致錯誤或多餘的延遲時間,系統會傳回錯誤。只有在 |
departureTime |
選用設定。出發時間。如果不設定這個值,這個值就會預設為您提出要求的時間。注意:當 採用 RFC3339 世界標準時間「Zulu」格式的時間戳記,採用奈秒解析度和最多九個小數位數。範例: |
arrivalTime |
選用設定。抵達時間。注意:只有在 採用 RFC3339 世界標準時間「Zulu」格式的時間戳記,採用奈秒解析度和最多九個小數位數。範例: |
languageCode |
選用設定。BCP-47 語言代碼,例如「en-US」或「sr-Latn」。詳情請參閱「萬國碼 (Unicode) 語言代碼 ID」。如需支援的語言清單,請參閱「語言支援」一文。如未提供這個值,系統會從第一個來源的位置推測顯示語言。 |
regionCode |
選用設定。區碼,指定為 ccTLD (「頂層網域」) 的兩位字元值詳情請參閱國家/地區代碼頂層網域。 |
units |
選用設定。為顯示欄位指定測量單位。 |
extraComputations[] |
選用設定。可用來完成要求的額外運算清單。注意:這些額外運算可能會在回應中傳回額外欄位。您也必須在欄位遮罩中指定這些額外欄位,才能在回應中傳回。 |
trafficModel |
選用設定。指定計算交通時間時要採用的假設。這項設定會影響 |
transitPreferences |
選用設定。指定會影響 |
回應主體
包含在 v2.computeRouteMatrix API 中針對起點/目的地組合計算出的路線資訊。這個原型可以串流至用戶端。
如果成功,回應主體即會包含具有以下結構的資料:
JSON 表示法 |
---|
{ "status": { object ( |
欄位 | |
---|---|
status |
此元素的錯誤狀態碼。 |
condition |
指出系統是否找到路線。與狀態無關。 |
distanceMeters |
路線的移動距離 (以公尺為單位)。 |
duration |
導航路線所需的時間。如果將 時間長度以秒為單位,最多可有 9 個小數位數,並結尾為「 |
staticDuration |
行經路線所需的時間 (不考量路況)。 時間長度以秒為單位,最多可有 9 個小數位數,並結尾為「 |
travelAdvisory |
路線的其他資訊。例如:限制資訊和收費資訊 |
fallbackInfo |
在某些情況下,當伺服器無法按照此特定起點/目的地組合的指定偏好設定計算路徑時,可能會改回使用不同的計算模式。使用備用模式時,這個欄位會包含備用回應的詳細資訊。否則,系統不會設定這個欄位。 |
localizedValues |
|
originIndex |
要求中來源的從零開始索引。 |
destinationIndex |
要求中的目的地索引 (從零開始)。 |
RouteMatrixOrigin
ComputeRouteMatrixRequest 的單一來源
JSON 表示法 |
---|
{ "waypoint": { object ( |
欄位 | |
---|---|
waypoint |
必要欄位。原始路線控點 |
routeModifiers |
選用設定。所有以此做為起點的路線的修飾符 |
RouteMatrixDestination
ComputeRouteMatrixRequest 的單一目的地
JSON 表示法 |
---|
{
"waypoint": {
object ( |
欄位 | |
---|---|
waypoint |
必要欄位。目的地路線控點 |
ExtraComputation
完成要求時要執行的額外運算作業。
列舉 | |
---|---|
EXTRA_COMPUTATION_UNSPECIFIED |
未使用。含有這個值的要求會失敗。 |
TOLLS |
矩陣元素的過渡資訊。 |
RouteMatrixElementCondition
傳迴路徑的條件。
列舉 | |
---|---|
ROUTE_MATRIX_ELEMENT_CONDITION_UNSPECIFIED |
只有在元素的 status 無效時使用。 |
ROUTE_EXISTS |
已找到路徑,且已填入 元素的對應資訊。 |
ROUTE_NOT_FOUND |
找不到路線。元素中不會填入包含路線資訊的欄位 (例如 distanceMeters 或 duration )。 |
LocalizedValues
特定屬性的文字表示法。
JSON 表示法 |
---|
{ "distance": { object ( |
欄位 | |
---|---|
distance |
行走距離,以文字格式表示。 |
duration |
流量條件以文字格式表示。注意:如果未要求流量資訊,這個值會與 staticDuration 相同。 |
staticDuration |
以文字形式表示的時長,不會將路況納入考量。 |
transitFare |
大眾運輸票價會以文字形式表示。 |