구글 지도 Routes API 응답 이해하기: Route Response 분석

Google 지도 Routes API로 경로를 계산하면, 단순히 distance와 duration만 돌려받는 것이 아닙니다. 반환된 응답(JSON)을 올바르게 파싱해야만, 경로 선(polyline), 각 구간(leg)·단계(step) 정보, 위치 보정 결과, 그리고 예외 처리 정보까지 활용할 수 있죠. 이 글에서는 Understand Route Response 문서를 바탕으로, 응답 구조를 단계별로 해석하는 방법을 알아봅니다.

1. 응답 전체 구조

Compute Routes 호출 응답은 다음과 같은 최상위 객체 형태로 구성됩니다:

{
  "routes": [ /* Route 객체 배열 */ ],
  "geocodingResults": [ /* GeocodedWaypoint 객체 배열 */ ],
  "fallbackInfo": { /* FallbackInfo 객체 */ }
}

• routes: 계산된 경로(Route) 객체들의 배열
• geocodingResults: Place ID나 주소를 좌표로 변환한 결과
• fallbackInfo: 경로 계산에 문제가 있을 때 제공되는 대체 정보

2. routes 배열 해석하기

routes 배열의 각 요소는 Route 타입이며, 출발지에서 도착지까지의 전체 경로를 나타냅니다. 기본 호출 시 하나의 경로만 반환되며, computeAlternativeRoutes 옵션에 따라 최대 3개의 대체 경로가 포함될 수 있습니다.

• routeLabels: 경로 종류 식별용 태그 (예: DEFAULT_ROUTE)
• distanceMeters: 총 이동 거리 (미터 단위)
• duration: 총 소요 시간 (ISO 8601 문자열)
• polyline.encodedPolyline: 인코딩된 경로 선

3. legs 배열 이해하기

각 Route 객체 내의 legs 배열은 RouteLeg 타입의 요소들이며, 출발지 → 경유지 → 도착지로 나뉜 구간을 의미합니다. 경유지를 지정하지 않으면 하나의 leg만 반환됩니다.

• distanceMeters, duration, polyline: 해당 구간의 거리·시간·폴리라인
• startLocation, endLocation: 구간의 시작·끝 좌표
• startWaypointIndex, endWaypointIndex: 요청의 waypoint 배열 인덱스

4. steps 배열 해석하기

각 RouteLeg 내부의 steps 배열은 RouteLegStep 타입의 요소들이며, 개별 내비게이션 지시(예: “우회전”) 하나하나를 나타냅니다.

• polyline.encodedPolyline: 이 단계의 경로 선
• distanceMeters, duration: 이 단계의 거리·시간
• navigationInstruction.text: 사용자에게 보여줄 내비게이션 지시문

5. geocodingResults 살펴보기

Place ID나 주소 문자열을 위도·경도로 변환한 결과는 geocodingResults 배열에 GeocodedWaypoint 객체로 제공됩니다. 각 객체의 placeId와 location.latLng를 활용해 정확한 좌표를 얻을 수 있습니다.

6. fallbackInfo 활용하기

응답에 fallbackInfo가 포함되었다면, API가 일부 옵션을 무시하고 대체 경로를 계산했음을 의미합니다. 예를 들어 실시간 교통 정보를 반영하지 못했을 때 이 정보를 기반으로 예외 처리 로직을 구현할 수 있습니다.

7. 전체 응답 예시

{
  "routes": [
    {
      "routeLabels": ["DEFAULT_ROUTE"],
      "distanceMeters": 772,
      "duration": "165s",
      "polyline": { "encodedPolyline": "ipkcFfichVnP@j@BLoFVwM{E?" },
      "legs": [
        {
          "distanceMeters": 772,
          "duration": "165s",
          "polyline": { "encodedPolyline": "ipkcFfichVnP@j@BLoF" },
          "steps": [
            {
              "distanceMeters": 200,
              "duration": "45s",
              "polyline": { "encodedPolyline": "ipkcFfichVnP@" },
              "navigationInstruction": { "text": "출발지에서 직진하세요." }
            }
            /* ... 추가 단계 ... */
          ]
        }
      ]
    }
  ],
  "geocodingResults": [
    {
      "placeId": "ChIJN1t_tDeuEmsRUsoyG83frY4",
      "location": { "latLng": { "latitude": 37.4197, "longitude": -122.0828 } }
    }
  ],
  "fallbackInfo": {
    "status": "TRAFFIC_UNAVAILABLE",
    "location": { "latLng": { "latitude": 37.4197, "longitude": -122.0828 } }
  }
}

8. 활용 팁

• 지도에 경로 표시: encodedPolyline을 디코딩해 지도에 선으로 그리기
• 내비게이션 안내: navigationInstruction.text로 길 안내 문구 표시
• 예외 처리: fallbackInfo 유무에 따라 재요청 또는 사용자 알림 로직 구현
• 응답 최적화: X-Goog-FieldMask 헤더로 필요한 필드만 요청해 응답 크기 최소화
  
  

Compute Routes 응답을 제대로 이해하면, 단순 거리·시간 계산을 넘어 상세한 구간별 지시와 예외 상황까지 처리할 수 있습니다.