Как выбрать поля для возврата

При отправке запроса на геокодирование вы можете использовать маску поля, чтобы указать список полей, которые должны возвращаться в ответе. Маски полей помогают сократить задержку ответа, поскольку вы не запрашиваете ненужные данные.

Для базовых методов геокодирования (геокодирование адреса, геокодирование местоположения и геокодирование места) по умолчанию возвращаются все поля в объекте ответа, в отличие от поиска пунктов назначения, где требуется указать маску поля. Хотя маска поля не требуется для базовых методов, мы настоятельно рекомендуем использовать ее, чтобы сократить задержку ответа.

Как определить маску поля ответа

Маска поля ответа – это список путей, разделенных запятыми без пробелов, где каждый путь указывает на уникальное поле в объекте ответа. Путь начинается с поля ответа верхнего уровня и использует разделенный точками путь к указанному полю.

Передайте маску поля ответа в запрос, используя параметр 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][...]

Маски полей для поиска пунктов назначения

При вызове SearchDestinations укажите нужные атрибуты пункта назначения, например сведения об основном месте, входах, точках навигации, контурах зданий (displayPolygon) и ориентирах.

curl -X POST -d '{"addressQuery": {"addressQuery": "1600 Amphitheatre Pkwy, Mountain View, CA"}}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: destinations.primary.displayName,destinations.primary.displayPolygon,destinations.entrances,destinations.navigationPoints,destinations.landmarks' \
-H "X-Goog-Api-Key: API_KEY" \
https://geocode.googleapis.com/v4/geocode/destinations

Маски полей для основного геокодирования

Например, чтобы в ответе GeocodeAddress возвращалось только поле 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/v4/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.