구글 지도 Routes API 경로 매트릭스 반환 필드 선택 방법

Compute Route Matrix 메서드는 여러 출발지와 도착지 조합에 대한 거리 및 소요 시간을 한 번에 계산해주지만, 반환되는 기본 필드 목록이 없기 때문에 반드시 필드 마스크를 지정해야 합니다. 지정하지 않으면 오류가 발생하며, 불필요한 데이터를 요청하면 네트워크 대역폭과 응답 시간이 증가합니다.

 

1. 필드 마스크란?

응답 필드 마스크는 응답 메시지에서 반환받을 필드를 “쉼표로 구분된 경로(path) 목록”으로 지정하는 방식입니다. 경로는 최상위 응답 오브젝트(Compute Route Matrix의 경우, 응답 본문)에 해당하며, 도트(.)로 중첩 필드를 연결해 표현합니다.

 

2. 왜 필드 마스크를 사용해야 하나?

• 필드 마스크를 지정하지 않으면 API가 오류(INVALID_ARGUMENT)를 반환합니다.
• 필요한 정보만 반환받아 응답 크기와 지연 시간을 줄이고, 불필요한 비용이 청구되는 것을 방지할 수 있습니다.

 

3. Compute Route Matrix 필드 마스크 구성 방법

1. 필요한 정보 파악
   반환받고자 하는 데이터(예: 출발지 인덱스, 도착지 인덱스, 거리, 시간 등)를 결정합니다.
2. 필드 경로 확인
   공식 문서의 Route Matrix 참조에서 각 필드의 경로 이름(originIndex, destinationIndex, distanceMeters, duration, status 등)을 확인합니다.
3. 콤마로 결합
   예를 들어, “originIndex”, “destinationIndex”, “distanceMeters”, “duration”을 요청하려면 originIndex,destinationIndex,distanceMeters,duration 로 쉼표 없이 결합합니다.
4. 요청에 포함
   - URL 매개변수: ?fields=originIndex,destinationIndex,distanceMeters,duration
   - 또는 HTTP 헤더: X-Goog-FieldMask: originIndex,destinationIndex,distanceMeters,duration

 

4. curl 요청 예시

curl -X POST \
  'https://routes.googleapis.com/v2:computeRouteMatrix' \
  -H 'Content-Type: application/json' \
  -H 'X-Goog-Api-Key: YOUR_API_KEY' \
  -H 'X-Goog-FieldMask: originIndex,destinationIndex,distanceMeters,duration,status' \
  --data-raw '{
    "origins": [
      { "waypoint": { "location": { "latLng": { "latitude": 37.7749, "longitude": -122.4194 } } } },
      { "waypoint": { "placeId": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ" } }
    ],
    "destinations": [
      { "waypoint": { "location": { "latLng": { "latitude": 37.8044, "longitude": -122.2712 } } } },
      { "waypoint": { "placeId": "ChIJIQBpAG2ahYAR_6128GcTUEo" } }
    ],
    "travelMode": "DRIVE",
    "routingPreference": "TRAFFIC_AWARE"
  }'

5. 와일드카드(*) 사용 주의사항

• 필드 마스크에 *를 사용하면 모든 필드를 요청할 수 있으나, 프로덕션 환경에서는 지양하세요.
• 전체 필드를 요청하면 비용과 응답 시간이 예측 불가능하게 증가할 수 있습니다.
• 필요한 필드만 선택해 사용함으로써 안정적인 성능과 비용 효율을 확보하세요.

 

Compute Route Matrix 호출 시 originIndex, destinationIndex, distanceMeters, duration 등 필수 필드를 명확히 지정하는 필드 마스크를 사용하면 오류를 방지하고 응답 크기와 비용을 크게 절감할 수 있습니다.