구글 지도 Compute Route Matrix에서 로컬라이즈 값 요청하기: Localized Values

다수의 출발지(origins)와 도착지(destinations) 조합에 대한 거리 및 소요 시간 행렬을 계산할 때, 결과를 사용자의 언어와 친숙한 단위(미터/피트, 분/시간)로 바로 표시할 수 있다면 UX가 한층 향상됩니다. Compute Route Matrix의 Localized Values 기능을 활용하면, distanceMeters와 duration 필드에 대해 번역된 text 값을 함께 받을 수 있습니다.

 

1. Localized Values란?

• 응답 객체에 localizedValues 맵이 추가되어, 각 distanceMeters와 duration 요소마다 로컬 언어 텍스트와 단위를 함께 포함합니다.
• Compute Route Matrix는 기본적으로 en-US 언어와 METRIC 단위를 사용하지만, 요청 시 languageCode와 units를 지정하여 변경할 수 있습니다.
• 지정하지 않으면 API가 호출자의 위치를 기반으로 언어와 단위를 추론합니다.
  
  

2. 요청 방법

1. X-Goog-FieldMask 헤더 또는 ?fields= URL 파라미터에 elements.localizedValues를 포함합니다.
2. JSON 본문에 필요 시 languageCode (예: "ko")와 units (예: "IMPERIAL" 또는 "METRIC")를 지정합니다.
3. 지정하지 않으면 Compute Route Matrix가 기본값(en-US/METRIC)을 사용하거나, 출발지 위치를 기반으로 추론합니다.
   
   

3. curl 요청 예시

curl -X POST 'https://routes.googleapis.com/v2:computeRouteMatrix?fields=originIndex,destinationIndex,elements(distanceMeters,duration,localizedValues)' \
  -H 'Content-Type: application/json' \
  -H 'X-Goog-Api-Key: YOUR_API_KEY' \
  --data-raw '{
    "origins": [
      { "waypoint": { "location": { "latLng": { "latitude": 37.5665, "longitude": 126.9780 } } } }
    ],
    "destinations": [
      { "waypoint": { "location": { "latLng": { "latitude": 37.5512, "longitude": 126.9882 } } } }
    ],
    "travelMode": "DRIVE",
    "languageCode": "ko",
    "units": "METRIC"
  }'

4. 응답 예시

[
  {
    "originIndex": 0,
    "destinationIndex": 0,
    "distanceMeters": 1534,
    "duration": "420s",
    "localizedValues": {
      "distance": { "text": "1.5km" },
      "duration": { "text": "7분" }
    }
  }
]

5. 활용 팁 및 주의사항

• 다국어 웹·앱에서 별도의 클라이언트 사이드 포맷팅 없이 응답된 localizedValues를 바로 UI에 표시할 수 있습니다.
• languageCode를 지정하면 기본 추론 대신 원하는 언어로 고정할 수 있습니다.
• Matrix 호출 시 필드 마스크를 꼭 포함해 elements.localizedValues를 요청하세요.
  
  
  

Compute Route Matrix의 Localized Values 기능을 통해, 복수 경로의 거리·시간 데이터를 다양한 언어와 단위로 손쉽게 전달할 수 있습니다.