Выберите поля для возврата

Разработчики из Европейской экономической зоны (ЕЭЗ)

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

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

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

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

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