구글 지도 Routes API 중간 경유지 설정: Intermediate Waypoints

내비게이션 경로에 단순한 출발지·도착지 외에 여러 중간 경유지(intermediate waypoints)를 추가하면, 픽업·드롭오프나 경유지를 반드시 통과해야 하는 시나리오에 유용합니다. Google 지도 Routes API의 intermediates 배열을 사용하면, 최대 25개의 중간 경유지를 설정하고 각 구간별 정보를 받을 수 있습니다. 

 

1. Intermediate Waypoints란?

• 출발지(origin)와 도착지(destination) 사이에 반드시 경유해야 할 지점을 지정하는 기능입니다.
• 각 경유지마다 새로운 RouteLeg이 생성되어, legs 배열에 순서대로 저장됩니다.
• 최대 25개까지 설정할 수 있으며, 11개 이상(11~25개) 요청 시 더 높은 요율이 적용됩니다. 
• Compute Route Matrix API에서는 지원되지 않습니다.
  
  

2. 요청 구성 방법

Compute Routes 호출 본문에 intermediates 배열을 추가해 중간 경유지를 지정합니다. 다음은 주요 속성입니다. 

• origin: 출발지 좌표 또는 Place ID
• intermediates: 중간 경유지 목록(각 요소는 location 객체와 선택적 via 플래그 포함)
• destination: 도착지 좌표 또는 Place ID
• travelMode, routingPreference, routeModifiers 등 일반 옵션
  
  

3. JSON 요청 예시

{
  "origin": {
    "location": { "latLng": { "latitude": 37.5665, "longitude": 126.9780 } }
  },
  "intermediates": [
    {
      "location": { "latLng": { "latitude": 37.5700, "longitude": 126.9820 } }
    },
    {
      "via": true,
      "location": { "latLng": { "latitude": 37.5750, "longitude": 126.9900 } }
    }
  ],
  "destination": {
    "location": { "latLng": { "latitude": 37.5512, "longitude": 126.9882 } }
  },
  "travelMode": "DRIVE",
  "routingPreference": "TRAFFIC_AWARE"
}

4. curl 요청 예시

curl -X POST 'https://routes.googleapis.com/directions/v2:computeRoutes' \
  -H 'Content-Type: application/json' \
  -H 'X-Goog-Api-Key: YOUR_API_KEY' \
  -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.legs' \
  --data-raw '{
    "origin": {
      "location": { "latLng": { "latitude": 37.5665, "longitude": 126.9780 } }
    },
    "intermediates": [
      { "location": { "latLng": { "latitude": 37.5700, "longitude": 126.9820 } } },
      { "via": true, "location": { "latLng": { "latitude": 37.5750, "longitude": 126.9900 } } }
    ],
    "destination": {
      "location": { "latLng": { "latitude": 37.5512, "longitude": 126.9882 } }
    },
    "travelMode": "DRIVE",
    "routingPreference": "TRAFFIC_AWARE"
  }'

5. 응답 예시

{
  "routes": [
    {
      "distanceMeters": 4200,
      "duration": "900s",
      "legs": [
        {
          "distanceMeters": 800,
          "duration": "180s",
          "startLocation": { "latLng": { "latitude": 37.5665, "longitude": 126.9780 } },
          "endLocation":   { "latLng": { "latitude": 37.5700, "longitude": 126.9820 } }
        },
        {
          "distanceMeters": 1000,
          "duration": "240s",
          "startLocation": { "latLng": { "latitude": 37.5700, "longitude": 126.9820 } },
          "endLocation":   { "latLng": { "latitude": 37.5750, "longitude": 126.9900 } }
        },
        {
          "distanceMeters": 2400,
          "duration": "480s",
          "startLocation": { "latLng": { "latitude": 37.5750, "longitude": 126.9900 } },
          "endLocation":   { "latLng": { "latitude": 37.5512, "longitude": 126.9882 } }
        }
      ]
    }
  ]
}

6. 유의사항 및 팁

• 11개 이상(최대 25개) 경유지를 설정하면 더 높은 요율이 적용됩니다.
• intermediates에 via: true를 설정하면 ‘통과 지점(pass-through)’으로 처리됩니다.
• 중간 경유지마다 새로운 leg이 생성되므로, legs 배열 길이가 경유지 개수+1이 됩니다.
• Compute Route Matrix API는 중간 경유지를 지원하지 않습니다.
  
  

Intermediate Waypoints를 통해 복잡한 픽업/드롭오프 시나리오나 특정 지점을 반드시 통과해야 하는 요구사항을 손쉽게 구현할 수 있습니다.