使用 Routes API 呼叫 computeRouteMatrix 方法 (REST) 或串流 ComputeRouteMatrix 方法 (gRPC),來計算多個起點和目的地的路線距離與所需時間。
此方法會擷取起點和目的地清單時,會計算從每個起點開始,並結束於每個目的地之間的距離與所需時間。
取得大眾運輸路線矩陣
您也可以計算大眾運輸的路線矩陣。如需範例,請參閱「取得大眾運輸的路線矩陣」一文。
要求限制
Compute Route Matrix 方法會針對使用地址或 placeID 的路線控點以及元素,強制執行下列要求限制。元素是路線矩陣中每個起點和目的地之間的路徑,因此元素數量是目的地「times」的次數。舉例來說,如果您有 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。