구글 지도 Routes API로 Route Token 받는 방법

Google 지도 Routes API의 Compute Routes 메서드는 기본 경로 정보 외에도 routeToken을 반환할 수 있습니다. 이 토큰은 네비게이션 SDK에서 동일 경로를 재사용하거나 세션을 관리할 때 유용합니다. 이 글에서는 routeToken을 요청하는 방법과 예시, 주의사항을 정리합니다.

 

1. Route Token 개요

• routeToken은 Compute Routes 호출 결과에 포함되는 고유 식별자입니다.
• 이 토큰을 사용하면, Navigation SDK(Android/iOS)에서 같은 경로를 그대로 따라갈 수 있습니다.
• 토큰은 동적 도로 상황에 따라 경로가 달라질 수 있으므로, 생성 후 몇 분 내에 사용하는 것을 권장합니다. 
  
  

2. 설정 방법

1. travelMode를 DRIVE로 설정하세요.
2. routingPreference를 TRAFFIC_AWARE 또는 TRAFFIC_AWARE_OPTIMAL로 설정하세요.
3. 요청 경로에 via 방식의 경유지는 포함하지 마세요.
4. 응답에 토큰을 포함시키려면 X-Goog-FieldMask: routes.routeToken 헤더를 추가하세요. 
   
   

3. 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.routeToken,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline' \
  --data-raw '{
    "origin": {
      "location": {
        "latLng": { "latitude": -37.8167, "longitude": 144.9619 }
      }
    },
    "destination": {
      "location": {
        "latLng": { "latitude": -37.8155, "longitude": 144.9663 }
      }
    },
    "routingPreference": "TRAFFIC_AWARE",
    "travelMode": "DRIVE"
  }'

4. 응답 예시

{
  "routes": [
    {
      "routeToken": "CqYB…Xj4",
      "distanceMeters": 650,
      "duration": "420s",
      "polyline": { "encodedPolyline": "abcd…" }
    }
  ]
}

5. 주의사항

• 토큰은 동적 교통 상황에 따라 실제 네비게이션 경로와 약간 다를 수 있습니다.
• 생성된 토큰은 몇 분 내에 사용해야 계획된 경로와의 차이를 최소화할 수 있습니다. 
• via waypoint가 포함된 요청에서는 토큰이 반환되지 않습니다.
  
  

6. 활용 팁

• Android/iOS Navigation SDK에 토큰을 전달해, 서버 호출 수를 줄이고 안정적인 내비게이션을 구현할 수 있습니다.
• 세션 기반 주행 기록 관리나, 경로 수정 후 동일 토큰 재사용에도 유용합니다.
  
  

routeToken을 요청하면, Compute Routes로 생성한 경로를 Navigation SDK에서 그대로 활용할 수 있습니다.