Routes Preferred API 目前僅適用於特定客戶。如需瞭解詳情，請
聯絡銷售人員。
Method: computeRouteMatrix
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
會接收起點和目的地清單，並傳回包含起點和目的地組合路線資訊的串流。
注意：這個方法需要您在輸入中指定回應欄位遮罩。如要提供回應欄位遮罩，您可以使用網址參數 $fields 或 fields，或使用 HTTP/gRPC 標頭 X-Goog-FieldMask (請參閱可用的網址參數和標頭)。值是以半形逗號分隔的欄位路徑清單。請參閱這份詳細說明，瞭解如何建構欄位路徑。
舉例來說，在這個方法中：
- 所有可用欄位的欄位遮罩 (用於手動檢查)：
X-Goog-FieldMask: *
- 路線時間長度、距離、元素狀態、條件和元素索引的欄位遮罩 (正式版設定範例)：
X-Goog-FieldMask:
originIndex,destinationIndex,status,condition,distanceMeters,duration
請務必在欄位遮罩中加入 status，否則所有訊息都會顯示為 OK。Google 不建議您使用萬用字元 (*) 回應欄位遮罩，原因如下：
- 只選取您需要的欄位有助於我們的伺服器節省運算週期，讓我們以更短的延遲時間將結果傳回給您。
- 只選取實際工作中所需的欄位，即可確保延遲時間穩定。我們日後可能會新增更多回應欄位，且這些新欄位可能需要額外的計算時間。如果您選取所有欄位，或是選取頂層的所有欄位，則可能會出現成效降低的情況，因為我們新增的所有欄位都會自動納入回應中。
- 只選取所需欄位，可縮小回應大小，進而提高網路傳輸量。
HTTP 要求
POST https://routespreferred.googleapis.com/v1:computeRouteMatrix
這個網址使用 gRPC 轉碼語法。
要求主體
要求主體的資料會採用以下結構：
| 欄位 |
origins[] |
object (RouteMatrixOrigin)
必要欄位。來源陣列，用於決定回應矩陣的資料列。以下幾項大小限制適用於起點和目的地的基數：
- 無論如何，元素 (起點 × 目的地) 數量不得超過 625 個。
- 如果將 routePreference 設為
TRAFFIC_AWARE_OPTIMAL，元素 (起點 × 目的地) 數不得超過 100。
- 以
placeId 指定的路線控點 (出發地 + 目的地) 數量不得超過 50 個。
|
destinations[] |
object (RouteMatrixDestination)
必要欄位。目的地陣列，用於決定回應矩陣的資料欄。
|
travelMode |
enum (RouteTravelMode)
選用設定。指定交通方式，
|
routingPreference |
enum (RoutingPreference)
選用設定。指定如何計算路徑。伺服器會嘗試使用所選的路由偏好設定來計算路徑。如果轉送偏好設定導致錯誤或過長延遲，則會傳回錯誤。只有在 travelMode 為 DRIVE 或 TWO_WHEELER 時，才能指定這個選項，否則要求會失敗。
|
departureTime |
string (Timestamp format)
選用設定。出發時間。如未設定這個值，系統會使用您提出要求的時間。如果將這個值設為已經發生的時間，要求就會失敗。 RFC3339 世界標準時間「Zulu」格式的時間戳記，精確度達奈秒單位，最多九個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
|
回應主體
如果成功，回應主體會包含 RouteMatrixElement 例項的串流。
授權範圍
需要下列 OAuth 範圍：
https://www.googleapis.com/auth/maps-platform.routespreferred
詳情請參閱 OAuth 2.0 總覽。
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-08-29 (世界標準時間)。
[null,null,["上次更新時間：2025-08-29 (世界標準時間)。"],[[["\u003cp\u003eTakes in origin and destination lists, returning route information for each combination.\u003c/p\u003e\n"],["\u003cp\u003eRequires a response field mask using \u003ccode\u003e$fields\u003c/code\u003e, \u003ccode\u003efields\u003c/code\u003e, or \u003ccode\u003eX-Goog-FieldMask\u003c/code\u003e for optimized results.\u003c/p\u003e\n"],["\u003cp\u003eMust include \u003ccode\u003estatus\u003c/code\u003e in the field mask to identify unsuccessful route calculations.\u003c/p\u003e\n"],["\u003cp\u003eLimits the number of elements to 625 or 100 if \u003ccode\u003eroutingPreference\u003c/code\u003e is \u003ccode\u003eTRAFFIC_AWARE_OPTIMAL\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eAuthorize the request with the \u003ccode\u003ehttps://www.googleapis.com/auth/maps-platform.routespreferred\u003c/code\u003e OAuth scope.\u003c/p\u003e\n"]]],[],null,["# Method: computeRouteMatrix\n\n- [HTTP request](#body.HTTP_TEMPLATE)\n- [Request body](#body.request_body)\n - [JSON representation](#body.request_body.SCHEMA_REPRESENTATION)\n- [Response body](#body.response_body)\n- [Authorization scopes](#body.aspect)\n\nTakes in a list of origins and destinations and returns a stream containing route information for each combination of origin and destination.\n\n**NOTE:** This method requires that you specify a response field mask in the input. You can provide the response field mask by using the URL parameter `$fields` or `fields`, or by using the HTTP/gRPC header `X-Goog-FieldMask` (see the [available URL parameters and headers](https://cloud.google.com/apis/docs/system-parameters). The value is a comma separated list of field paths. See this detailed documentation about [how to construct the field paths](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/field_mask.proto).\n\nFor example, in this method:\n\n- Field mask of all available fields (for manual inspection): `X-Goog-FieldMask: *`\n- Field mask of route durations, distances, element status, condition, and element indices (an example production setup): `X-Goog-FieldMask:\n originIndex,destinationIndex,status,condition,distanceMeters,duration`\n\nIt is critical that you include `status` in your field mask as otherwise all messages will appear to be OK. Google discourages the use of the wildcard (`*`) response field mask, because:\n\n- Selecting only the fields that you need helps our server save computation cycles, allowing us to return the result to you with a lower latency.\n- Selecting only the fields that you need in your production job ensures stable latency performance. We might add more response fields in the future, and those new fields might require extra computation time. If you select all fields, or if you select all fields at the top level, then you might experience performance degradation because any new field we add will be automatically included in the response.\n- Selecting only the fields that you need results in a smaller response size, and thus higher network throughput.\n\n### HTTP request\n\n`POST https://routespreferred.googleapis.com/v1:computeRouteMatrix`\n\nThe URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.\n\n### Request body\n\nThe request body contains data with the following structure:\n\n| JSON representation |\n|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ``` { \"origins\": [ { object (/maps/documentation/routes_preferred/reference/rest/Shared.Types/ComputeRouteMatrixRequest#RouteMatrixOrigin) } ], \"destinations\": [ { object (/maps/documentation/routes_preferred/reference/rest/Shared.Types/ComputeRouteMatrixRequest#RouteMatrixDestination) } ], \"travelMode\": enum (/maps/documentation/routes_preferred/reference/rest/Shared.Types/RouteTravelMode), \"routingPreference\": enum (/maps/documentation/routes_preferred/reference/rest/Shared.Types/RoutingPreference), \"departureTime\": string } ``` |\n\n| Fields ||\n|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `origins[]` | `object (`[RouteMatrixOrigin](/maps/documentation/routes_preferred/reference/rest/Shared.Types/ComputeRouteMatrixRequest#RouteMatrixOrigin)`)` Required. Array of origins, which determines the rows of the response matrix. Several size restrictions apply to the cardinality of origins and destinations: - The number of elements (origins × destinations) must be no greater than 625 in any case. - The number of elements (origins × destinations) must be no greater than 100 if routingPreference is set to `TRAFFIC_AWARE_OPTIMAL`. - The number of waypoints (origins + destinations) specified as `placeId` must be no greater than 50. |\n| `destinations[]` | `object (`[RouteMatrixDestination](/maps/documentation/routes_preferred/reference/rest/Shared.Types/ComputeRouteMatrixRequest#RouteMatrixDestination)`)` Required. Array of destinations, which determines the columns of the response matrix. |\n| `travel``Mode` | `enum (`[RouteTravelMode](/maps/documentation/routes_preferred/reference/rest/Shared.Types/RouteTravelMode)`)` Optional. Specifies the mode of transportation. |\n| `routing``Preference` | `enum (`[RoutingPreference](/maps/documentation/routes_preferred/reference/rest/Shared.Types/RoutingPreference)`)` Optional. Specifies how to compute the route. The server attempts to use the selected routing preference to compute the route. If the routing preference results in an error or an extra long latency, an error is returned. You can specify this option only when the `travelMode` is `DRIVE` or `TWO_WHEELER`, otherwise the request fails. |\n| `departure``Time` | `string (`[Timestamp](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp)` format)` Optional. The departure time. If you don't set this value, this defaults to the time that you made the request. If you set this value to a time that has already occurred, the request fails. A timestamp in RFC3339 UTC \"Zulu\" format, with nanosecond resolution and up to nine fractional digits. Examples: `\"2014-10-02T15:01:23Z\"` and `\"2014-10-02T15:01:23.045123456Z\"`. |\n\n### Response body\n\nIf successful, the response body contains a stream of [RouteMatrixElement](/maps/documentation/routes_preferred/reference/rest/Shared.Types/RouteMatrixElement) instances.\n\n### Authorization scopes\n\nRequires the following OAuth scope:\n\n- `https://www.googleapis.com/auth/maps-platform.routespreferred`\n\nFor more information, see the [OAuth 2.0 Overview](https://developers.google.com/identity/protocols/OAuth2)."]]
