呼叫 computeRouteMatrix 方法 (REST) 或串流 ComputeRouteMatrix 方法 (gRPC),即可使用 Routes API 計算多個起點與目的地的路線距離和持續時間。
此方法會根據起點與目的地清單,計算路線從每個起點開始,並在每個目的地結束的距離和所需時間。
取得大眾運輸路線矩陣
您也可以計算大眾運輸上的路徑矩陣。如需範例,請參閱取得大眾運輸路線矩陣。
要求限制
Compute Route Matrix 方法會針對使用 address 或 placeID 的路線控點以及元素強制執行下列要求限制。元素是路線矩陣中每個起點和目的地之間的路徑,因此元素數量是指目的地的起點「時間」。舉例來說,如果您有 10 個起點和 10 個目的地,那麼有 100 個元素:
非
TRANSIT
路徑的路徑數量不得超過 625 個。如果您指定
TRANSIT
路徑,元素數量不得超過 100 個。如果指定
TRAFFIC_AWARE_OPTIMAL
,元素數量不得超過 100 個。如要進一步瞭解TRAFFIC_AWARE_OPTIMAL
,請參閱指定如何納入流量資料,以及是否要納入流量資料。如果您使用地址或地點 ID 指定出發地或目的地,則最多僅能指定 50 個起點。
回應錯誤
Compute Route Matrix 方法的其中一項功能,是可針對整個回應或個別回應元素傳回錯誤。舉例來說,如果要求格式錯誤 (例如有零個來源),則完整回應會包含錯誤。
但是,如果錯誤適用於回應中的部分元素 (例如無法針對一種起點與目的地的組合計算路徑),則只有受錯誤影響的元素會傳回錯誤代碼。
gRPC 串流結果
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 Routes 和 Compute Route Matrix。