구글 지도 Routes API 응답 필드 최적화: 필드 선택(Choose Fields)

Google 지도 Routes API를 사용해 길안내 데이터를 가져올 때, 기본으로 반환되는 필드 목록은 없습니다. 필드 마스크를 지정하지 않으면 API는 오류를 반환하며, 불필요한 데이터를 요청하면 네트워크 비용과 응답 속도가 모두 늘어납니다. 이 글에서는 Choose Fields 문서를 기반으로, 응답 필드를 효율적으로 선택하는 방법을 단계별로 정리합니다.

 

1. 필드 마스크란?

• 필드 마스크(Field Mask)는 응답 메시지에서 어떤 필드를 돌려줄지 콤마로 구분된 경로(path) 목록으로 지정하는 방식입니다.
• 경로는 최상위 메시지 이름에서 시작해 도트(.)로 이어 쓰며, 예를 들어 routes.legs.distanceMeters처럼 표현합니다.

2. 왜 필드 마스크를 사용해야 할까?

1. 오류 방지: 필드 마스크를 지정하지 않으면 API는 기본값이 없어 요청을 거부합니다.
2. 응답 최적화: 필요한 정보만 받아오므로 네트워크 대역폭을 절약하고 응답 시간을 단축할 수 있습니다.

3. 필드 마스크 구성 방법

1. 필요한 정보 파악
   반환받고자 하는 데이터가 어느 객체에 있는지 참조 문서를 확인합니다.
2. 경로(path) 결정
   객체 계층 구조에 맞춰 routes.legs.steps.duration처럼 전체 경로를 작성합니다.
3. 콤마로 결합
   여러 경로를 요청할 때는 routes.distanceMeters,routes.duration처럼 공백 없이 쉼표로 구분합니다.
4. 요청에 포함
   URL 파라미터: ?fields=routes.distanceMeters,routes.duration
   또는 HTTP 헤더: X-Goog-FieldMask: routes.distanceMeters,routes.duration

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.legs.distanceMeters,routes.legs.steps.duration' \
  --data-raw '{
    "origin": {
      "location": { "latLng": { "latitude": 37.419734, "longitude": -122.0827784 } }
    },
    "destination": {
      "location": { "latLng": { "latitude": 37.417670, "longitude": -122.079595 } }
    },
    "travelMode": "DRIVE",
    "routingPreference": "TRAFFIC_AWARE",
    "computeAlternativeRoutes": false
  }'

5. 주의사항 및 팁

• 와일드카드 *: 개발 중에 모든 필드를 확인할 때는 유용하지만, 프로덕션 환경에서는 사용을 자제하세요.
• 필드 참조 문서 활용: Compute Routes 및 Route Matrix의 필드 레퍼런스에서 정확한 경로 이름을 확인하세요.|
  
  

필드 마스크를 활용해 응답에 꼭 필요한 데이터만 요청하면, API 호출 비용과 레이턴시를 크게 개선할 수 있습니다.