구글 지도 Routes API 로컬라이즈 값 요청하기: Localized Values

다국적 서비스를 제공할 때, 거리나 소요 시간을 사용자의 언어와 로컬 단위로 표시하면 UX가 크게 향상됩니다. Google 지도 Routes API의 Localized Values 기능을 활용하면, `distance`, `duration`, `staticDuration` 필드에 대해 번역된 텍스트를 함께 받을 수 있습니다.

 

1. Localized Values란?

• 응답 메시지에 추가되는 `localizedValues` 객체로, 거리 및 시간, 단위 시스템(METRIC/IMPERIAL)에 대한 로컬라이즈된 텍스트를 제공합니다.
• 언어(`languageCode`)와 단위(`units`)를 직접 지정하거나, API가 요청 위치를 기반으로 추론하도록 할 수 있습니다.
• ComputeRoutes는 출발지 waypoint를, ComputeRouteMatrix는 기본값인 `en-US`와 METRIC 단위를 사용해 추론합니다. 
  
  

2. 요청 방법

1. 필드 마스크에 routes.localizedValues를 포함합니다.
2. 원하는 경우, JSON 본문에 languageCode와 units를 지정합니다. 예: "languageCode": "de", "units": "IMPERIAL".
3. 지정하지 않으면 API가 ComputeRoutes는 출발지 기반 추론, ComputeRouteMatrix는 `en-US`/METRIC을 기본으로 사용합니다. 
   
   

3. 예시 요청

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.localizedValues' \
  --data-raw '{
    "origin": {
      "location": { "latLng": { "latitude": 37.7873146, "longitude": -122.4159327 } }
    },
    "destination": {
      "location": { "latLng": { "latitude": 37.7621008, "longitude": -122.4382503 } }
    },
    "travelMode": "DRIVE",
    "computeAlternativeRoutes": true,
    "languageCode": "de",
    "units": "METRIC"
  }'

4. 예시 응답

{
  "localizedValues": {
    "distance": {
      "text": "15,5 km"
    },
    "duration": {
      "text": "16 Minuten"
    },
    "staticDuration": {
      "text": "16 Minuten"
    }
  }
}

5. 언어 및 단위 추론

• ComputeRoutes 호출 시 languageCode 또는 units를 생략하면, API가 출발지 위치를 기반으로 언어와 단위를 추론합니다.
• ComputeRouteMatrix 호출은 기본값으로 `en-US` 언어와 METRIC 단위를 사용합니다.
  
  

Localized Values 기능을 적용하면, 전 세계 사용자에게 거리와 시간을 친숙한 형식으로 제공할 수 있습니다.