구글 지도 Routes API 위치 접근 설정 가이드: Location Modifiers

단순히 출발지(origin)와 도착지(destination)만 지정해도 경로 계산은 가능하지만, 픽업·드롭오프 상황에서는 차량이 웨이포인트에 접근하는 방향과 도로 측면까지 제어할 필요가 있습니다. Google 지도 Routes API의 Location Modifiers 기능을 사용하면, 각 웨이포인트별로 heading과 side_of_road 파라미터를 지정해 차량이 원하는 방향으로 도착하도록 설정할 수 있습니다.

 

1. Location Modifiers란?

• 웨이포인트(출발지·중간 경유지·도착지)에 도달할 때 차량의 진행 방향(heading) 또는 도로 측면(side_of_road)을 지정하는 옵션입니다.
• 정확한 위치 접근을 보장해, 택시 호출·배송 픽업·드롭오프 같은 상황에서 유용합니다.
  
  

2. 지원되는 파라미터

2-1. heading

• 0~359 범위의 정수로, 0은 북쪽, 90은 동쪽, 180은 남쪽, 270은 서쪽을 의미합니다.
• 해당 웨이포인트에 접근할 때 차량이 바라볼 방향을 지정합니다.
• 적용 대상: DRIVE, TWO_WHEELER 모드의 웨이포인트에서만 사용 가능합니다.

2-2. side_of_road

• true로 설정하면, API가 웨이포인트가 위치한 도로의 동일한 측면(진행 방향 왼쪽/오른쪽)에서 접근하도록 경로를 계산합니다.
• 도로 건너편 하차 문제를 방지해, 사용자가 대기 중인 쪽으로 정확하게 진입할 수 있습니다.
• 적용 대상: DRIVE 모드의 웨이포인트에서만 사용 가능합니다.
  
  

3. JSON 요청 예시

{
  "origin": {
    "location": {
      "latLng": { "latitude": 37.419734, "longitude": -122.0827784 }
    },
    "heading": 90
  },
  "destination": {
    "location": {
      "latLng": { "latitude": 37.417670, "longitude": -122.079595 }
    },
    "sideOfRoad": true
  },
  "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.polyline, routes.distanceMeters, routes.duration' \
  --data-raw '{
    "origin": {
      "location": {
        "latLng": { "latitude": 37.419734, "longitude": -122.0827784 }
      },
      "heading": 90
    },
    "destination": {
      "location": {
        "latLng": { "latitude": 37.417670, "longitude": -122.079595 }
      },
      "sideOfRoad": true
    },
    "travelMode": "DRIVE",
    "routingPreference": "TRAFFIC_AWARE"
  }'

5. 응답 활용 팁

• 지도 시각화: `routes.polyline.encodedPolyline`을 디코딩해, 지정한 heading·side_of_road 설정이 반영된 경로를 확인해 보세요.
• 택시·배달 앱 연동: 호출 수락 후, 차량이 사용자 측면으로 안전하게 접근하도록 UI에 방향 지시를 함께 제공할 수 있습니다.
• 요금 최적화: 불필요한 회차나 도로 변경 없이, 첫 시도에 정확히 접근해 비효율을 줄입니다.
  
  

6. 주의사항

• heading과 side_of_road는 동일 웨이포인트에 동시에 사용할 수 없습니다.
• Location Modifiers를 사용하는 요청은 표준 요청보다 높은 요율로 청구될 수 있으니, 사용 빈도를 고려하세요.
• 지원 모드 외(WALK, TRANSIT, BICYCLE)에서 설정 시 무시됩니다.
  
  

Location Modifiers를 활용하면 픽업·드롭오프 시 차량이 정확한 방향과 측면에서 접근하도록 경로를 제어할 수 있습니다.