반환할 필드 선택

유럽 경제 지역 (EEA) 개발자

지오코딩 요청을 할 때 필드 마스크를 사용하여 응답에서 반환할 필드의 목록을 지정할 수 있습니다. 주소 지오코딩, 위치 지오코딩, 장소 지오코딩 엔드포인트의 경우 응답 객체의 모든 필드가 기본적으로 반환됩니다. 여행지 검색 엔드포인트의 경우 API 요청에 필드 마스크를 지정해야 합니다.

필드 마스크를 사용하여 불필요한 데이터의 요청을 방지하면 응답 지연 시간을 줄일 수 있습니다.

응답 필드 마스크 정의

응답 필드 마스크는 공백이 없는 쉼표로 구분된 경로 목록으로, 각 경로는 응답 객체의 고유한 필드를 지정합니다. 경로는 최상위 응답 필드에서 시작하며 점으로 구분된 경로를 사용하여 지정된 필드로 이동합니다.

URL 매개변수 $fields 또는 fields를 사용하거나 HTTP 또는 gRPC 헤더 X-Goog-FieldMask를 사용하여 응답 필드 마스크를 요청에 전달합니다.

필드 마스크 예시

다음은 정방향 지오코딩 요청의 전체 응답입니다.

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
    ...
}

다음 형식으로 응답 필드의 계층 구조를 사용하여 필드 마스크를 구성합니다.

topLevelField[.secondLevelField][.thirdLevelField][...]

예를 들어 응답에서 placeId 필드만 반환하려면 다음 필드 마스크를 사용하세요.

curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
"https://"geocode.googleapis.com/v4beta/"geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

이제 응답은 다음과 같습니다.

{
  "results": [
    {
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE"
    }
  ]
}

viewport 필드를 반환하려면 필드 마스크는 다음과 같습니다.

-H 'X-Goog-FieldMask: results.viewport'

이제 응답은 다음과 같습니다.

{
  "results": [
    {
      "viewport": {
        "low": {
          "latitude": 37.420654569708496,
          "longitude": -122.08547618029148
        },
        "high": {
          "latitude": 37.423352530291496,
          "longitude": -122.0827782197085
        }
      }
    }
  ]
}

두 항목을 모두 반품하려면 다음 단계를 따르세요.

-H 'X-Goog-FieldMask: results.placeId,results.viewport'

이제 응답은 다음과 같습니다.

{
  "results": [
    {
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "viewport": {
        "low": {
          "latitude": 37.420654569708496,
          "longitude": -122.08547618029148
        },
        "high": {
          "latitude": 37.423352530291496,
          "longitude": -122.0827782197085
        }
      }
    }
  ]
}

gRPC 필드 마스크

gRPC의 경우 응답 필드 마스크가 포함된 변수를 설정합니다. 그런 다음 해당 변수를 요청에 전달할 수 있습니다.

const (
  fieldMask = "results.placeId,results.viewport"
)

필드 경로 고려사항

응답에 필요한 필드만 포함하여 필요한 필드만 반환합니다.

  • 처리 시간을 줄여 결과가 더 낮은 지연 시간으로 반환됩니다.
  • 안정적인 지연 시간 성능을 보장합니다. 모든 필드를 선택하거나 최상위 수준에서 모든 필드를 선택하면 새 필드가 추가된 후 응답에 자동으로 포함될 때 성능이 저하될 수 있습니다.
  • 응답 크기가 작아지므로 네트워크 처리량이 높아집니다.

필드 마스크 구성에 관한 자세한 내용은 field_mask.proto를 참고하세요.