구글 지도 Routes API Compute Route Matrix 응답 이해하기: Route Matrix Response

Compute Route Matrix 메서드는 여러 출발지(origins)와 도착지(destinations) 조합에 대한 거리 및 소요 시간을 한 번에 계산해 줍니다. 반환된 응답은 배열 형태의 RouteMatrixElement 객체들로 구성되며, 각 요소는 단일 출발지-도착지 경로를 나타냅니다. 이 글에서는 응답 구조 및 주요 필드를 예시와 함께 살펴보겠습니다.

 

1. 응답 전체 구조

Compute Route Matrix의 응답은 JSON 배열 형태입니다. 배열의 각 원소(RouteMatrixElement)는 다음과 같은 프로퍼티를 포함합니다:

• originIndex: 요청한 origins 배열에서 이 경로의 출발지 인덱스 (0 기반)
• destinationIndex: 요청한 destinations 배열에서 이 경로의 도착지 인덱스 (0 기반)
• status: 이 요소가 정상 계산되었는지 여부 (예: “OK” 또는 오류 코드)
• distanceMeters: 경로 거리(미터)
• duration: 실시간 교통을 반영한 소요 시간(ISO 8601 형식 문자열)
• staticDuration: 과거(히스토리) 교통 정보만 반영한 소요 시간(ISO 8601 형식 문자열)
• travelAdvisory: 톨 요금, 연료 소비, 대중교통 요금 등의 추가 정보 객체 (옵션)

2. 요소 식별하기

응답 배열의 각 요소는 originIndex와 destinationIndex로 어떤 출발지와 도착지 조합인지 명확히 식별할 수 있습니다. 예를 들어, "originIndex": 1, "destinationIndex": 0 은 요청 배열의 두 번째 출발지에서 첫 번째 도착지로 계산된 경로를 의미합니다.

3. 오류 처리

Compute Route Matrix는 전체 요청 오류(예: origins 또는 destinations 미존재)와 개별 요소 오류를 구분하여 반환합니다. - 전체 요청이 잘못된 경우 응답 전체가 오류를 포함합니다. - 일부 요소만 계산 실패하면 해당 요소의 status 필드에 오류 코드를 표시합니다.

4. JSON 응답 예시

[
  {
    "originIndex": 0,
    "destinationIndex": 0,
    "status": "OK",
    "distanceMeters": 13200,
    "duration": "900s",
    "staticDuration": "870s"
  },
  {
    "originIndex": 0,
    "destinationIndex": 1,
    "status": "OK",
    "distanceMeters": 15400,
    "duration": "1020s",
    "staticDuration": "980s"
  },
  {
    "originIndex": 1,
    "destinationIndex": 0,
    "status": "OK",
    "distanceMeters": 12800,
    "duration": "870s",
    "staticDuration": "840s"
  },
  {
    "originIndex": 1,
    "destinationIndex": 1,
    "status": "OK",
    "distanceMeters": 15050,
    "duration": "980s",
    "staticDuration": "950s"
  }
]

5. 필드 마스크와 스트리밍

Compute Route Matrix 호출 시에는 반드시 X-Goog-FieldMask 또는 ?fields= URL 파라미터로 반환할 필드를 지정해야 합니다. 예를 들어: X-Goog-FieldMask: originIndex,destinationIndex,distanceMeters,duration,status 또한 gRPC 스트리밍 호출을 사용하면, 전체 매트릭스 계산 완료를 기다리지 않고 개별 요소들을 순차적으로 처리해 응답 지연을 줄일 수 있습니다.

6. 활용 팁

• 택시·배차 서비스: 가장 가까운 차량을 빠르게 찾기 위한 거리/시간 매트릭스 계산
• 물류·배송 최적화: 다중 배송지 간 소요 시간 행렬을 기반으로 최적 경로 계획
• 근접 검색: 사용자 위치에서 여러 POI까지의 거리·시간을 일괄 조회
  
  

Compute Route Matrix의 응답 구조를 이해하면, 여러 출발지-도착지 조합에 대한 거리·시간 정보를 한 번에 효율적으로 처리할 수 있습니다.