透過呼叫 computeRouteMatrix 方法 (REST) 或串流 ComputeRouteMatrix 方法 (gRPC),使用 Routes API 計算多個起點和終點的路線距離和持續時間。
假設有起點和目的地清單,此方法會計算路線起點起點,然後計算各起點終點的距離和所需時間。
要求限制
Compute Route Matrix 方法會強制執行下列要求限制:
元素數量 (來源數量 × 目的地數量) 不得超過 625 個。
如果指定
TRAFFIC_AWARE_OPTIMAL
,元素數量不得超過 100。如要進一步瞭解TRAFFIC_AWARE_OPTIMAL
,請參閱「設定品質與延遲」。使用地點 ID 最多可以指定 50 個路線控點 (起點 + 目的地)。
回應錯誤
Compute 路徑矩陣方法的其中一項功能是可以傳回整個回應或個別回應元素。例如,如果要求的格式錯誤 (例如,其從零開始),則整個回應會包含錯誤。
不過,如果錯誤適用於回應中的部分元素(例如路徑無法計算出一個起點和目的地的組合),則只有受錯誤影響的元素會傳回錯誤代碼。
串流結果
ComputeRouteMatrix gRPC 方法會擷取起點和目的地清單,並傳回包含每個起點與目的地組合的路徑資訊。 結果會以串流方式傳回,因此您不必等到系統計算所有可能的路徑組合後,才能開始處理結果。
串流傳回的元素不保證會以任何順序傳回。因此,每個回應元素都包含 origin_index
和 destination_index
。針對要求指定的來源和目的地,路徑起點相當於 origins[origin_index]
為特定元素,且路徑目的地相當於 destinations[destination_index]
。這些陣列沒有任何索引。請務必儲存起點和目的地清單的順序。
計算路線矩陣範例
在 HTTP 要求中使用 computeRouteMatrix 方法,計算路徑矩陣。
HTTP 範例
以下範例顯示 computeRouteMatrix
HTTP 要求。在這個範例中,您將:
指定兩個起點和兩個目的地路線控點的陣列。這個方法會計算從每個起點到各個目的地的路徑,因此回應包含四個路徑。
陣列中,第一個元素位於索引 0,第二個元素為索引 1,依此類推。
加入回應欄位遮罩,以指定要傳回的回應 (REST) 或 ComputeRoutesResponse (gRPC) 欄位。在此範例中,將要求設定為為每個路徑傳回
originIndex
、destinationIndex
、duration
、distanceMeters
、status
和condition
。詳情請參閱「選擇要傳回的欄位」。
curl -X POST -d '{ "origins": [ { "waypoint": { "location": { "latLng": { "latitude": 37.420761, "longitude": -122.081356 } } }, "routeModifiers": { "avoid_ferries": true} }, { "waypoint": { "location": { "latLng": { "latitude": 37.403184, "longitude": -122.097371 } } }, "routeModifiers": { "avoid_ferries": true} } ], "destinations": [ { "waypoint": { "location": { "latLng": { "latitude": 37.420999, "longitude": -122.086894 } } } }, { "waypoint": { "location": { "latLng": { "latitude": 37.383047, "longitude": -122.044651 } } } } ], "travelMode": "DRIVE", "routingPreference": "TRAFFIC_AWARE" }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: originIndex,destinationIndex,duration,distanceMeters,status,condition' \ 'https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix'
這個回應包含四個可能路徑,用於所有起點和目的地路線控點的組合。
使用 originIndex
和 destinationIndex
回應欄位來識別回應中的各個路徑。舉例來說,回應中 originIndex
的 1,對應於要求中 origins
陣列的索引 1 路線計算的路線。
[ { "originIndex": 0, "destinationIndex": 0, "status": {}, "distanceMeters": 822, "duration": "160s", "condition": "ROUTE_EXISTS" }, { "originIndex": 1, "destinationIndex": 0, "status": {}, "distanceMeters": 2919, "duration": "361s", "condition": "ROUTE_EXISTS" }, { "originIndex": 1, "destinationIndex": 1, "status": {}, "distanceMeters": 5598, "duration": "402s", "condition": "ROUTE_EXISTS" }, { "originIndex": 0, "destinationIndex": 1, "status": {}, "distanceMeters": 7259, "duration": "712s", "condition": "ROUTE_EXISTS" } ]
gRPC 範例
如需 gRPC 要求範例,請參閱 gRPC 要求範例中的範例。該頁面的 Java 範例會同時呼叫 Compute 路徑和 Compute 路徑矩陣。