Routes Preferred API는 현재 일부 고객만 이용할 수 있습니다. 자세한 내용은
영업팀에 문의하세요.
Method: computeRouteMatrix
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
출발지와 목적지 목록을 가져와서 각 출발지와 목적지 조합에 대한 경로 정보가 포함된 스트림을 반환합니다.
참고: 이 메서드를 사용하려면 입력에 응답 필드 마스크를 지정해야 합니다. URL 매개변수 $fields 또는 fields를 사용하거나 HTTP/gRPC 헤더 X-Goog-FieldMask를 사용하여 응답 필드 마스크를 제공할 수 있습니다 (사용 가능한 URL 매개변수 및 헤더 참조). 값은 쉼표로 구분된 필드 경로 목록입니다. 필드 경로를 구성하는 방법에 관한 자세한 문서를 참고하세요.
예를 들어 이 메서드에서
- 사용 가능한 모든 필드의 필드 마스크(수동 검사용):
X-Goog-FieldMask: *
- 경로 시간, 거리, 요소 상태, 조건, 요소 색인의 필드 마스크(프로덕션 설정 예시):
X-Goog-FieldMask:
originIndex,destinationIndex,status,condition,distanceMeters,duration
필드 마스크에 status를 포함해야 합니다. 그렇지 않으면 모든 메시지가 정상적으로 표시됩니다. Google에서는 다음과 같은 이유로 와일드 카드 (*) 응답 필드 마스크를 사용하지 않는 것이 좋습니다.
- 필요한 필드만 선택하면 서버에서 계산 주기를 절약하여 지연 시간을 단축하여 결과를 반환할 수 있습니다.
- 프로덕션 작업에 필요한 필드만 선택하면 안정적인 지연 시간 성능이 보장됩니다. 향후 응답 필드가 추가될 수 있으며, 이러한 새 필드에는 추가 계산 시간이 필요할 수 있습니다. 모든 필드를 선택하거나 최상위 수준에서 모든 필드를 선택하면 추가된 새 필드가 응답에 자동으로 포함되므로 성능이 저하될 수 있습니다.
- 필요한 필드만 선택하면 응답 크기가 작아져 네트워크 처리량이 높아집니다.
HTTP 요청
POST https://routespreferred.googleapis.com/v1alpha:computeRouteMatrix
URL은 gRPC 트랜스코딩 구문을 사용합니다.
요청 본문
요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.
| 필드 |
origins[] |
object (RouteMatrixOrigin)
필수 항목입니다. 응답 매트릭스의 행을 결정하는 출처 배열입니다. 출발지와 목적지의 카디널리티에는 몇 가지 크기 제한이 적용됩니다.
- 요소 수 (출발지 × 목적지)는 어떤 경우에도 625개 이하여야 합니다.
- 라우팅Preference가
TRAFFIC_AWARE_OPTIMAL로 설정된 경우 요소 수 (출발지 × 목적지)는 100개 이하여야 합니다.
placeId로 지정된 경유지 (출발지 + 목적지) 수는 50 이하여야 합니다.
|
destinations[] |
object (RouteMatrixDestination)
필수 항목입니다. 응답 매트릭스의 열을 결정하는 대상 배열입니다.
|
travelMode |
enum (RouteTravelMode)
선택사항입니다. 이동수단을 지정합니다.
|
routingPreference |
enum (RoutingPreference)
선택사항입니다. 경로를 계산하는 방법을 지정합니다. 서버는 선택한 라우팅 환경설정을 사용하여 경로를 계산하려고 시도합니다. 라우팅 환경설정으로 인해 오류가 발생하거나 지연 시간이 너무 길어지면 오류가 반환됩니다. travelMode이 DRIVE 또는 TWO_WHEELER인 경우에만 이 옵션을 지정할 수 있으며, 그렇지 않으면 요청이 실패합니다.
|
departureTime |
string (Timestamp format)
선택사항입니다. 출발 시간입니다. 이 값을 설정하지 않으면 기본적으로 요청한 시간으로 설정됩니다. 이 값을 이미 발생한 시간으로 설정하면 요청이 실패합니다. RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z" 및 "2014-10-02T15:01:23.045123456Z"입니다.
|
응답 본문
성공하면 응답 본문에 RouteMatrixElement 인스턴스의 스트림이 포함됩니다.
승인 범위
다음 OAuth 범위가 필요합니다.
https://www.googleapis.com/auth/maps-platform.routespreferred
자세한 내용은 OAuth 2.0 개요를 참고하세요.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-08-29(UTC)
[null,null,["최종 업데이트: 2025-08-29(UTC)"],[[["\u003cp\u003eTakes a list of origins and destinations, returning route information for each combination.\u003c/p\u003e\n"],["\u003cp\u003eRequires specifying a response field mask for optimized performance and data selection.\u003c/p\u003e\n"],["\u003cp\u003eAccepts parameters for travel mode, routing preference, and departure time.\u003c/p\u003e\n"],["\u003cp\u003eReturns a stream of \u003ccode\u003eRouteMatrixElement\u003c/code\u003e instances containing route details.\u003c/p\u003e\n"],["\u003cp\u003eRequires the \u003ccode\u003ehttps://www.googleapis.com/auth/maps-platform.routespreferred\u003c/code\u003e OAuth scope for authorization.\u003c/p\u003e\n"]]],["This method computes route information for multiple origin-destination pairs. It requires a `POST` request to `computeRouteMatrix` with lists of `origins` and `destinations` in the request body. A field mask must be included to specify which data fields to return, with `status` being critical. Optional parameters include `travelMode`, `routingPreference`, and `departureTime`. The response is a stream of `RouteMatrixElement` instances, and the method requires a specific OAuth scope for authorization.\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/v1alpha: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)."]]
