구글 지도 Routes API Compute Route Matrix: 다중 출발지-도착지 경로 매트릭스 계산

하나의 경로 대신, 여러 출발지(origins)와 도착지(destinations) 조합에 대한 거리 및 소요 시간을 한 번에 계산해야 할 때가 있습니다. Google 지도 Routes API의 Compute Route Matrix 메서드를 사용하면, 최대 625개의 경로 요소(elements)를 포함하는 행렬(matrix) 형태로 결과를 받아올 수 있습니다. 이 글에서는 요청 구성부터 응답 처리, 활용 사례까지 단계별로 살펴보겠습니다.

 

1. Compute Route Matrix란?

• 여러 출발지와 여러 도착지 조합(origin × destination)에 대해 각 경로의 거리(distance)와 소요 시간(duration)을 계산합니다.
• elements 수(출발지 수 × 도착지 수)가 625를 초과하면 오류가 발생합니다(비-TRANSIT 경로 기준). 
• REST와 gRPC 스트리밍 방식 모두 지원하며, 스트리밍은 개별 요소를 순차적으로 처리할 수 있어 대기 시간을 줄여줍니다.
  
  

2. REST 요청 구성

1. HTTP 메서드: POST
2. 엔드포인트:

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

3. 필수 헤더:
   • Content-Type: application/json
   • X-Goog-Api-Key: YOUR_API_KEY
4. 요청 본문:

   {
     "origins": [
       { "waypoint": { "location": { "latLng": { "latitude": 37.7749, "longitude": -122.4194 } } } },
       { "waypoint": { "placeId": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ" } }
     ],
     "destinations": [
       { "waypoint": { "location": { "latLng": { "latitude": 37.8044, "longitude": -122.2712 } } } },
       { "waypoint": { "placeId": "ChIJIQBpAG2ahYAR_6128GcTUEo" } }
     ],
     "travelMode": "DRIVE",
     "routingPreference": "TRAFFIC_AWARE"
   }

3. 요청 제한 및 오류 처리

• elements(출발지×도착지) 수는 비-TRANSIT 모드에서 최대 625까지 지원합니다.
• 잘못된 전체 요청(예: origins 또는 destinations가 비어 있음)은 전체 오류를 반환합니다.
• 일부 요소(route)만 계산 실패한 경우, 해당 요소에만 오류 코드가 포함된 채 개별 응답에 반환됩니다.
  
  

4. curl 요청 예시

curl -X POST \
  'https://routes.googleapis.com/v2:computeRouteMatrix' \
  -H 'Content-Type: application/json' \
  -H 'X-Goog-Api-Key: YOUR_API_KEY' \
  --data-raw '{
    "origins": [
      { "waypoint": { "location": { "latLng": { "latitude": 37.7749, "longitude": -122.4194 } } } },
      { "waypoint": { "placeId": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ" } }
    ],
    "destinations": [
      { "waypoint": { "location": { "latLng": { "latitude": 37.8044, "longitude": -122.2712 } } } },
      { "waypoint": { "placeId": "ChIJIQBpAG2ahYAR_6128GcTUEo" } }
    ],
    "travelMode": "DRIVE",
    "routingPreference": "TRAFFIC_AWARE"
  }'

5. 응답 예시

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

• originIndex와 destinationIndex는 각 요소가 어떤 출발지·도착지를 나타내는지 매핑합니다.
• distanceMeters와 duration 배열은 순서대로 계산된 값을 제공합니다.
• status 배열은 각 요소의 성공 여부(OK 또는 오류 코드)를 나타냅니다.
  
  

6. 활용 사례

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

Compute Route Matrix는 다중 출발지·도착지 시나리오에서 효율적으로 거리와 소요 시간을 일괄 계산할 수 있는 강력한 기능입니다. 요청 제한을 준수하고, 응답의 인덱스 매핑 방식을 이해하면 다양한 서비스에 손쉽게 통합할 수 있습니다.