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

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

При отправке запроса на геокодирование вы можете использовать маску поля , чтобы указать список полей, которые должны быть возвращены в ответе. Для конечных точек «Геокодирование адреса» , «Геокодирование местоположения» и «Геокодирование места» по умолчанию возвращаются все поля из объекта ответа. Для конечной точки «Поиск пунктов назначения » необходимо указать маску поля в запросе 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 .