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에서는 다음과 같은 이유로 와일드 카드 (*) 응답 필드 마스크 사용을 권장하지 않습니다.

  • 필요한 필드만 선택하면 서버에서 계산 주기를 절약할 수 있으므로 지연 시간이 짧은 결과를 반환할 수 있습니다.
  • 프로덕션 작업에 필요한 필드만 선택하면 지연 시간 성능이 안정적으로 유지됩니다. 향후 응답 필드가 추가될 수 있으며 이러한 새 필드에는 추가 계산 시간이 필요할 수 있습니다. 모든 필드를 선택하거나 최상위 수준에서 모든 필드를 선택하면 Google에서 추가하는 새 필드가 응답에 자동으로 포함되므로 성능이 저하될 수 있습니다.
  • 필요한 필드만 선택하면 응답 크기가 작아지므로 네트워크 처리량이 높아집니다.

HTTP 요청

POST https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix

URL은 gRPC 트랜스코딩 구문을 사용합니다.

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

JSON 표현 
{
  "origins": [
    {
      object (RouteMatrixOrigin)
    }
  ],
  "destinations": [
    {
      object (RouteMatrixDestination)
    }
  ],
  "travelMode": enum (RouteTravelMode),
  "routingPreference": enum (RoutingPreference),
  "departureTime": string,
  "arrivalTime": string,
  "languageCode": string,
  "regionCode": string,
  "units": enum (Units),
  "extraComputations": [
    enum (ExtraComputation)
  ],
  "trafficModel": enum (TrafficModel),
  "transitPreferences": {
    object (TransitPreferences)
  }
}
필드
origins[]

object (RouteMatrixOrigin)

필수 항목입니다. 원본 배열로, 응답 행렬의 행을 결정합니다. 출발지 및 도착지의 카디널리티에는 다음과 같은 여러 크기 제한이 적용됩니다.

  • placeId 또는 address로 지정된 출발지 수와 도착지 수의 합계는 50 이하여야 합니다.
  • 출발지 수와 도착지 수의 곱은 어떤 경우에도 625를 초과해서는 안 됩니다.
  • routingPreference가 TRAFFIC_AWARE_OPTIMAL로 설정된 경우 출발지 수 × 목적지 수는 100 이하여야 합니다.
  • travelMode가 TRANSIT로 설정된 경우 출발지 수와 목적지 수의 곱은 100 이하여야 합니다.
destinations[]

object (RouteMatrixDestination)

필수 항목입니다. 대답 행렬의 열을 결정하는 대상 배열입니다.
travelMode

enum (RouteTravelMode)

선택사항입니다. 이동 수단을 지정합니다.
routingPreference

enum (RoutingPreference)

선택사항입니다. 경로를 계산하는 방법을 지정합니다. 서버는 선택한 라우팅 환경설정을 사용하여 경로를 계산하려고 시도합니다. 라우팅 환경설정으로 인해 오류가 발생하거나 지연 시간이 지나치게 길어지면 오류가 반환됩니다. travelMode가 DRIVE 또는 TWO_WHEELER인 경우에만 이 옵션을 지정할 수 있습니다. 그렇지 않으면 요청이 실패합니다.
departureTime

string (Timestamp format)

선택사항입니다. 출발 시간입니다. 이 값을 설정하지 않으면 요청한 시간이 기본값으로 설정됩니다. 참고: RouteTravelMode이 TRANSIT로 설정된 경우에만 과거의 departureTime를 지정할 수 있습니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
arrivalTime

string (Timestamp format)

선택사항입니다. 도착 시간입니다. 참고: RouteTravelMode이 TRANSIT으로 설정된 경우에만 설정할 수 있습니다. departureTime 또는 arrivalTime 중 하나를 지정할 수 있지만 둘 다 지정할 수는 없습니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
languageCode

string

선택사항입니다. BCP-47 언어 코드(예: 'en-US' 또는 'sr-Latn') 자세한 내용은 유니코드 언어 식별자를 참고하세요. 지원되는 언어 목록은 언어 지원을 참고하세요. 이 값을 제공하지 않으면 표시 언어가 첫 번째 출처의 위치에서 추론됩니다.
regionCode

string

선택사항입니다. ccTLD ('최상위 도메인') 2자리 값으로 지정되는 지역 코드입니다. 자세한 내용은 국가 코드 최상위 도메인을 참고하세요.
units

enum (Units)

선택사항입니다. 디스플레이 필드의 측정 단위를 지정합니다.
extraComputations[]

enum (ExtraComputation)

선택사항입니다. 요청을 완료하는 데 사용할 수 있는 추가 계산 목록입니다. 참고: 이러한 추가 계산은 응답에 추가 필드를 반환할 수 있습니다. 이러한 추가 필드는 응답에서 반환되도록 필드 마스크에도 지정해야 합니다.
trafficModel

enum (TrafficModel)

선택사항입니다. 교통 상황에서 시간을 계산할 때 사용할 가정을 지정합니다. 이 설정은 이전 평균을 기반으로 한 예상 이동 시간이 포함된 RouteMatrixElement의 duration 필드에 반환되는 값에 영향을 미칩니다. TrafficModel은(는) RoutingPreference을 TRAFFIC_AWARE_OPTIMAL로, RouteTravelMode을 DRIVE로 설정한 요청에만 사용할 수 있습니다. 트래픽이 요청되고 TrafficModel이 지정되지 않은 경우 기본값은 BEST_GUESS입니다.
transitPreferences

object (TransitPreferences)

선택사항입니다. TRANSIT 경로에 반환되는 경로에 영향을 미치는 환경설정을 지정합니다. 참고: RouteTravelMode이 TRANSIT로 설정된 경우에만 transitPreferences를 지정할 수 있습니다.

응답 본문

v2.computeRouteMatrix API에서 출발지/목적지 쌍에 대해 계산된 경로 정보를 포함합니다. 이 프로토는 클라이언트로 스트리밍될 수 있습니다.

성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.

JSON 표현 
{
  "status": {
    object (Status)
  },
  "condition": enum (RouteMatrixElementCondition),
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  },
  "fallbackInfo": {
    object (FallbackInfo)
  },
  "localizedValues": {
    object (LocalizedValues)
  },
  "originIndex": integer,
  "destinationIndex": integer
}
필드
status

object (Status)

이 요소의 오류 상태 코드입니다.
condition

enum (RouteMatrixElementCondition)

경로를 찾았는지 여부를 나타냅니다. 상태와 관계없이
distanceMeters

integer

경로의 이동 거리(미터)입니다.
duration

string (Duration format)

경로를 탐색하는 데 필요한 시간입니다. routingPreference을 TRAFFIC_UNAWARE로 설정하면 이 값은 staticDuration와 동일합니다. routingPreference을 TRAFFIC_AWARE 또는 TRAFFIC_AWARE_OPTIMAL로 설정하면 교통 상황을 고려하여 이 값이 계산됩니다.

소수점 아래가 최대 9자리까지이고 's'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"입니다.
staticDuration

string (Duration format)

교통상황을 고려하지 않고 경로를 이동하는 데 걸리는 시간입니다.

소수점 아래가 최대 9자리까지이고 's'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"입니다.
travelAdvisory

object (RouteTravelAdvisory)

경로에 대한 추가 정보입니다. 예: 제한 정보 및 통행료 정보
fallbackInfo

object (FallbackInfo)

서버가 특정 출발지/도착지 쌍에 대해 지정된 환경설정으로 경로를 계산할 수 없는 경우 다른 계산 모드를 사용하는 것으로 대체될 수 있습니다. 대체 모드가 사용되면 이 필드에는 대체 응답에 관한 자세한 정보가 포함됩니다. 그렇지 않으면 이 필드는 설정되지 않습니다.
localizedValues

object (LocalizedValues)

RouteMatrixElement의 속성을 텍스트로 표현한 것입니다.
originIndex

integer

요청에서 0부터 시작하는 출처의 색인입니다.
destinationIndex

integer

요청의 대상에서 0부터 시작하는 색인입니다.

RouteMatrixOrigin

ComputeRouteMatrixRequest의 단일 원본

JSON 표현 
{
  "waypoint": {
    object (Waypoint)
  },
  "routeModifiers": {
    object (RouteModifiers)
  }
}
필드
waypoint

object (Waypoint)

필수 항목입니다. 출발지 경유지
routeModifiers

object (RouteModifiers)

선택사항입니다. 이를 원점으로 사용하는 모든 경로의 수정자

RouteMatrixDestination

ComputeRouteMatrixRequest의 단일 대상

JSON 표현 
{
  "waypoint": {
    object (Waypoint)
  }
}
필드
waypoint

object (Waypoint)

필수 항목입니다. 대상 경유지

ExtraComputation

요청을 완료하는 동안 실행할 추가 계산입니다.

열거형
EXTRA_COMPUTATION_UNSPECIFIED 사용되지 않음. 이 값이 포함된 요청은 실패합니다.
TOLLS 매트릭스 요소의 통행료 정보입니다.

RouteMatrixElementCondition

반환되는 경로의 조건입니다.

열거형
ROUTE_MATRIX_ELEMENT_CONDITION_UNSPECIFIED 요소의 status가 OK가 아닌 경우에만 사용됩니다.
ROUTE_EXISTS 경로가 발견되었으며 요소에 해당하는 정보가 입력되었습니다.
ROUTE_NOT_FOUND 경로를 찾을 수 없습니다. distanceMeters 또는 duration과 같은 경로 정보가 포함된 필드는 요소에 입력되지 않습니다.

LocalizedValues

특정 속성의 텍스트 표현입니다.

JSON 표현 
{
  "distance": {
    object (LocalizedText)
  },
  "duration": {
    object (LocalizedText)
  },
  "staticDuration": {
    object (LocalizedText)
  },
  "transitFare": {
    object (LocalizedText)
  }
}
필드
distance

object (LocalizedText)

이동 거리를 텍스트 형식으로 나타냅니다.
duration

object (LocalizedText)

교통 상황을 고려하여 텍스트 형식으로 표현된 시간입니다. 참고: 교통 정보가 요청되지 않은 경우 이 값은 staticDuration과 동일한 값입니다.
staticDuration

object (LocalizedText)

트래픽 조건을 고려하지 않고 텍스트 형식으로 표현된 기간입니다.
transitFare

object (LocalizedText)

텍스트 형식으로 표시된 대중교통 요금입니다.