경로 응답 검토

Routes API는 경로를 계산할 때 사용자가 제공하는 경유지 및 구성 매개변수를 입력으로 사용합니다. 그러면 API가 기본 경로와 하나 이상의 대체 경로가 포함된 응답을 반환합니다.

요청한 필드에 따라 응답에는 다양한 유형의 경로 및 기타 데이터가 포함될 수 있습니다.

응답에 이 내용 포함 이 문서 보기
차량의 엔진 유형을 기준으로 한 연비 또는 에너지 효율이 가장 높은 경로입니다. 친환경 경로 구성
대체 경로 최대 3개 대체 경로 요청
전체 경로, 경로의 각 구간, 구간의 각 단계에 대한 다중선입니다. 경로 다중선 요청
운전자 또는 차량이 사용할 수 있는 통행료 할인 또는 통행료를 고려한 예상 통행료입니다. 통행료 계산
언어 코드 및 측정 단위 (야드파운드법 또는 미터법)별로 현지화된 응답입니다. 현지화된 값 요청
탐색 안내의 형식을 HTML 텍스트 문자열로 지정하려면 HTML_FORMATTED_NAVIGATION_INSTRUCTIONS를 extraComputations에 추가합니다. 추가 계산

입력 옵션의 전체 목록은 사용 가능한 경로 옵션 및 요청 본문을 참조하세요.

응답을 사용하여 고객의 요구사항에 적합한 경로를 선택하는 데 필요한 정보를 제공할 수 있습니다.

필드 마스크에 관한 정보

경로를 계산하는 메서드를 호출할 때는 응답에서 반환되기를 원하는 필드를 정의하는 필드 마스크를 지정해야 합니다. 반환되는 필드의 기본 목록은 없습니다. 이 목록을 생략하면 메서드가 오류를 반환합니다.

이 문서의 예시에서는 필드 마스크를 고려하지 않고 전체 응답 객체를 보여줍니다. 프로덕션 환경에서는 필드 마스크에 명시적으로 지정한 필드만 응답에 포함됩니다.

자세한 내용은 반환할 정보 선택을 참고하세요.

저작권 표시 정보

사용자에게 결과를 표시할 때 다음 저작권 표시를 포함해야 합니다.

Powered by Google, ©YEAR Google

예를 들면 다음과 같습니다.

Powered by Google, ©2023 Google

경로, 구간 및 계단 정보

Routes API에서 반환된 응답을 보기 전에 경로를 구성하는 구성요소를 이해해야 합니다.

경로, 구간, 계단입니다.

응답에는 다음과 같은 각 경로 구성요소에 대한 정보가 포함될 수 있습니다.

  • 경로: 출발지 경유지에서 중간 경유지를 지나 목적지 경유지까지의 전체 이동입니다. 경로는 하나 이상의 구간으로 구성됩니다.

  • 구간: 경로의 한 경유지에서 경로의 다음 경유지까지의 경로입니다. 각 구간은 하나 이상의 개별 단계로 구성됩니다.

    경로에는 각 경유지에서 다음 경유지까지의 경로에 대한 별도의 구간이 포함됩니다. 예를 들어 경로에 하나의 출발지 경유지와 단일 목적지 경유지가 포함된 경우 경로에는 단일 구간이 포함됩니다. 출발지와 목적지 뒤의 경로에 경유지를 추가할 때마다(중간 경유지라고 함) API는 별도의 구간을 추가합니다.

    API는 패스 스루 중간 경유지를 위한 구간을 추가하지 않습니다. 예를 들어 출발지 경유지, 통과 중간 경유지, 목적지 경유지가 포함된 경로는 경유지를 통과하면서 출발지에서 목적지까지 하나의 구간만 포함합니다. 통과 경유지에 관한 자세한 내용은 통과 경유지 정의를 참고하세요.

  • 단계: 경로의 구간에 있는 단일 안내입니다. 단계는 경로의 가장 원자적 단위입니다. 예를 들어 단계가 '중앙로에서 좌회전'을 나타낼 수 있습니다.

대답 내용

API 응답을 나타내는 JSON 객체에는 다음과 같은 최상위 속성이 포함됩니다.

  • routes는 경로 유형의 요소 배열입니다. routes 배열에는 API에서 반환하는 경로마다 요소가 하나씩 포함됩니다. 배열에는 최대 5개의 요소, 즉 기본 경로, 친환경 경로, 최대 3개의 대체 경로를 포함할 수 있습니다.

  • geocodingResults: GeocodingResults 유형의 요소 배열 API는 주소 문자열 또는 Plus 코드로 지정한 요청의 모든 위치 (출발지, 목적지 또는 중간 경유지)에 대해 장소 ID 조회를 수행합니다. 이 배열의 각 요소에는 위치에 해당하는 장소 ID가 포함됩니다. 장소 ID 또는 위도/경도 좌표로 지정된 요청의 위치는 포함되지 않습니다. 장소 ID 또는 위도와 경도 좌표를 사용하여 모든 위치를 지정한 경우 이 배열은 제공되지 않습니다.

  • FallbackInfo 유형의 fallbackInfo API가 모든 입력 속성에서 경로를 계산할 수 없는 경우 다른 계산 방법을 사용하는 것으로 대체할 수 있습니다. 대체 모드가 사용되는 경우 이 필드에는 대체 응답에 관한 자세한 정보가 포함됩니다. 그렇지 않으면 이 필드는 설정되지 않습니다.

응답의 형식은 다음과 같습니다.

{
  // The routes array.
  "routes": [
    {
      object (Route)
    }
  ],
  // The place ID lookup results.
  "geocodingResults": [
    {
      object (GeocodedWaypoint)
    }
  ],
  // The fallback property.
  "fallbackInfo": {
    object (FallbackInfo)
  }
}

경로 배열 해독

응답에는 routes 배열이 포함되며, 여기서 각 배열 요소는 Route 유형입니다. 각 배열 요소는 출발지에서 목적지까지의 전체 경로를 나타냅니다. API는 항상 기본 경로라고 하는 하나 이상의 경로를 반환합니다.

추가 경로를 요청할 수 있습니다. 친환경 경로를 요청하면 배열에 기본 경로와 친환경 경로라는 두 요소를 포함할 수 있습니다. 또는 요청에서 computeAlternativeRoutes을 true로 설정하여 응답에 대체 경로를 최대 3개까지 추가합니다.

배열의 각 경로는 routeLabels 배열 속성으로 식별됩니다.

값 설명
DEFAULT_ROUTE 기본 경로를 식별합니다.
FUEL_EFFICIENT 친환경 경로를 식별합니다.
DEFAULT_ROUTE_ALTERNATE 대체 경로를 추가합니다.

legs 배열에는 경로의 각 구간에 대한 정의가 포함됩니다. distanceMeters, duration, polyline, 같은 나머지 속성은 경로 전체에 관한 정보를 포함합니다.

{
  "routeLabels": [
    enum (RouteLabel)
  ],
  "legs": [
    {
      object (RouteLeg)
    }
  ],
  "distanceMeters": integer,
  "duration": string,
  "routeLabels": [string],
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "description": string,
  "warnings": [
    string
  ],
  "viewport": {
    object (Viewport)
  },
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  }
  "routeToken": string
}

현재 운전 조건 및 기타 요인으로 인해 기본 경로와 친환경 경로가 동일할 수 있습니다. 이 경우 routeLabels 배열에는 DEFAULT_ROUTE와 FUEL_EFFICIENT라는 라벨이 모두 포함되어 있습니다.

{
  "routes": [
    {
      "routeLabels": [
        "DEFAULT_ROUTE",
        "FUEL_EFFICIENT"
      ],
     …
    }
  ]
}

구간 배열 이해

응답의 각 route에는 legs 배열이 포함되며, 여기서 각 legs 배열 요소는 RouteLeg 유형입니다. 배열의 각 구간은 경로를 따라 한 경유지에서 다음 경유지까지의 경로를 정의합니다. 경로에는 항상 하나 이상의 구간이 포함됩니다.

legs 속성에는 steps 배열의 구간을 따라 각 단계의 정의가 포함되어 있습니다. distanceMeters, duration, polyline와 같은 나머지 속성에는 구간에 대한 정보가 포함됩니다.

{
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "startLocation": {
    object (Location)
  },
  "endLocation": {
    object (Location)
  },
  "steps": [
    {
      object (RouteLegStep)
    }
  ],
  "travelAdvisory": {
    object (RouteLegTravelAdvisory)
  }
}

단계 배열 이해

응답의 각 구간에는 steps 배열이 포함되며, 여기서 각 steps 배열 요소는 RouteLegStep 유형입니다. 단계는 구간을 따라 하나의 명령에 해당합니다. 구간에는 항상 하나 이상의 단계가 포함됩니다.

steps 배열의 각 요소에는 단계 안내를 포함하는 NavigationInstruction 유형의 navigationInstruction 속성이 포함되어 있습니다. 예를 들면 다음과 같습니다.

"navigationInstruction": {
  "maneuver": "TURN_LEFT",
  "instructions": "Turn left toward Frontage Rd"
}

instructions에는 단계에 대한 추가 정보가 포함될 수 있습니다. 예를 들면 다음과 같습니다.

"navigationInstruction": {
  "maneuver": "TURN_SLIGHT_LEFT",
  "instructions": "Slight left (signs for I-90 W/Worcester)nParts of this road may be closed at certain times or days"
}

단계의 나머지 속성은 distanceMeters, duration, polyline와 같은 단계에 대한 정보를 설명합니다.

{
  "distanceMeters": integer,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "startLocation": {
    object (Location)
  },
  "endLocation": {
    object (Location)
  },
  "navigationInstruction": {
    object (NavigationInstruction)
  }
}

단계 안내의 언어 지정

API는 기본 언어를 보면서 필요한 경우 사용자가 읽을 수 있는 스크립트로 음역한 경로 정보를 현지 언어로 반환합니다. 주소 구성요소는 모두 동일한 언어로 반환됩니다.

  • 요청의 languageCode 매개변수를 사용하여 지원되는 언어 목록에서 경로 언어를 명시적으로 설정합니다. Google은 지원되는 언어를 자주 업데이트하므로 이 목록은 완전하지 않을 수 있습니다.

  • 지정된 언어로 이름을 사용할 수 없는 경우 API는 가장 가까운 일치 항목을 사용합니다.

  • 지정된 언어는 API가 반환하도록 선택한 결과 집합과 반환되는 순서에 영향을 줄 수 있습니다. 지오코더는 언어에 따라 약어를 다르게 해석합니다(예: 거리 유형의 약어 또는 한 언어에서는 유효하지만 다른 언어에서는 유효하지 않을 수 있는 동의어). 예를 들어 utca와 tér는 헝가리어로 거리의 동의어입니다.

GeocodingResults 배열 이해

요청의 모든 위치 (출발지, 목적지 또는 중간 경유지)가 주소 문자열 또는 Plus 코드로 지정된 경우 API는 상응하는 장소 ID가 있는 가장 관련성 높은 위치를 찾으려고 시도합니다. geocodingResults 배열의 각 요소에는 위치를 장소 ID로 포함하는 placeID 필드와 위치 유형을 지정하는 type 필드(예: street_address, premise, airport)가 포함됩니다.

geocodingResults 배열에는 3개의 필드가 포함됩니다.

  • origin: 주소 문자열 또는 Plus 코드로 지정된 경우 출발지의 장소 ID입니다. 그렇지 않으면 이 필드는 응답에서 생략됩니다.

  • destination: 주소 문자열 또는 Plus 코드로 지정된 경우 목적지의 장소 ID입니다. 그렇지 않으면 이 필드는 응답에서 생략됩니다.

  • intermediates: 주소 문자열 또는 Plus 코드로 지정된 중간 경유지의 장소 ID가 포함된 배열 장소 ID 또는 위도와 경도 좌표를 사용하여 중간 경유지를 지정하면 응답에서 생략됩니다. 응답의 intermediateWaypointRequestIndex 속성을 사용하여 요청의 중간 경유지가 응답의 장소 ID에 해당하는지 확인합니다.

"geocodingResults": {
    "origin": {
        "geocoderStatus": {},
        "type": [
             enum (Type)
        ],
        "placeId": string
    },
    "destination": {
        "geocoderStatus": {},
        "type": [
            enum (Type)
        ],
        "placeId": string
    },
    "intermediates": [
        {
            "geocoderStatus": {},
            "intermediateWaypointRequestIndex": integer,
            "type": [
                enum (Type)
            ],
            "placeId": string
        },
        {
           "geocoderStatus": {},
           "intermediateWaypointRequestIndex": integer,
            "type": [
                enum (Type)
            ],
            "placeId": string
        }
    ]
}

현지화된 응답 값 이해

현지화된 응답 값은 반환된 매개변수 값에 대해 현지화된 텍스트를 제공하는 추가 응답 필드입니다. 이동 시간, 거리 및 단위 체계 (미터법 또는 인치법)에 관해 현지화된 텍스트가 제공됩니다. 필드 마스크를 사용하여 현지화된 값을 요청하고 언어 및 단위 체계를 지정하거나 API에서 유추한 값을 사용할 수 있습니다. 자세한 내용은 LocalizedValues를 참고하세요.

예를 들어 독일어 (de)와 야드파운드법의 언어 코드를 지정하면 distanceMeters 값이 49889.7이지만 거리 측정값을 독일어 및 야드파운드법 단위로 제공하는 현지화된 텍스트도 '31 Meile'로 표시합니다.

다음은 현지화된 값에 표시되는 내용의 예입니다.

{ "localized_values":
  {
    "distance": { "text": "31,0 Meile/n" },
    "duration": { "text": 38 Minuten}.
    "static_duration": { "text": 36 Minuten}.
  }
}

언어 또는 단위 체계를 지정하지 않으면 API는 다음과 같이 언어와 단위를 유추합니다.

  • ComputeRoutes 메서드는 출발지 경유지로부터의 위치 및 거리 단위를 추론합니다. 따라서 미국의 라우팅 요청의 경우 API는 en-US 언어와 IMPERIAL 단위를 유추합니다.
  • ComputeRouteMatrix 메서드의 기본값은 'en-US' 언어 및 METRIC 단위입니다.