Method: geocode.destinations.searchDestinations

Этот метод выполняет поиск целевых страниц и возвращает их список.

HTTP-запрос

POST https://geocode.googleapis.com/v4beta/geocode/destinations

URL имеет синтаксис gRPC Transcoding.

Тело запроса

Ниже приведена структура данных в теле запроса.

JSON-представление 
{
  "travelModes": [
    enum (NavigationPoint.TravelMode)
  ],
  "languageCode": string,
  "regionCode": string,

  // Union field primary_query can be only one of the following:
  "place": string,
  "addressQuery": {
    object (SearchDestinationsRequest.AddressQuery)
  },
  "locationQuery": {
    object (SearchDestinationsRequest.LocationQuery)
  }
  // End of list of possible types for union field primary_query.
}
Поля
travelModes[]

enum (NavigationPoint.TravelMode)

Необязательное поле. Способы передвижения, для которых нужно отфильтровать точки навигации. Это влияет на поле navigationPoints, возвращаемое в ответе. Если значение не указано, возвращаются точки навигации для всех способов передвижения.
languageCode

string

Необязательное поле. Язык, на котором должны быть возвращены результаты.
regionCode

string

Необязательное поле. Код региона. Код региона, указываемый как двухсимвольное значение национального домена верхнего уровня (ccTLD). Параметр влияет на результаты в соответствии с действующим законодательством. Этот параметр также влияет на результаты работы сервиса, но не ограничивает их полностью.

Объединенное поле primary_query. Запросите основной пункт назначения. Это может быть место, полный адрес или координаты LatLng. Некоторые места и адреса с минимальным количеством информации нельзя будет превратить в пункт назначения.

Целевые страницы создаются на основе указанного основного запроса.

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

string

Название ресурса места в формате places/{placeId}.
addressQuery

object (SearchDestinationsRequest.AddressQuery)

Почтовый адрес.
locationQuery

object (SearchDestinationsRequest.LocationQuery)

Точное местоположение.

Тело ответа

Сообщение с ответом для DestinationService.SearchDestinations.

Ниже приведена структура данных в ответе, полученном на запрос.

JSON-представление 
{
  "destinations": [
    {
      object (Destination)
    }
  ]
}
Поля
destinations[]

object (Destination)

Список пунктов назначения.

Если по основному запросу можно однозначно определить основную точку назначения, сервис возвращает один результат. В противном случае сервис может вернуть несколько результатов для уточнения или не вернуть ни одного.

Области авторизации

Требует одной из следующих областей применения OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/maps-platform.geocode
  • https://www.googleapis.com/auth/maps-platform.destinations

SearchDestinationsRequest.AddressQuery

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

JSON-представление 
{

  // Union field kind can be only one of the following:
  "address": {
    object (PostalAddress)
  },
  "addressQuery": string
  // End of list of possible types for union field kind.
}
Поля
Объединенное поле kind. Запрос адреса. kind может иметь одно из следующих значений:
address

object (PostalAddress)

Почтовый адрес.
addressQuery

string

Почтовый адрес, отформатированный в одну строку.

SearchDestinationsRequest.LocationQuery

Запрос местоположения для определения ближайшего основного пункта назначения.

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

JSON-представление 
{
  "placeFilter": {
    object (SearchDestinationsRequest.LocationQuery.PlaceFilter)
  },

  // Union field kind can be only one of the following:
  "location": {
    object (LatLng)
  }
  // End of list of possible types for union field kind.
}
Поля
placeFilter

object (SearchDestinationsRequest.LocationQuery.PlaceFilter)

Необязательное поле. Фильтры, которые нужно применить к целевым кандидатам.
Объединенное поле kind. Запрос местоположения. kind может иметь одно из следующих значений:
location

object (LatLng)

Точное местоположение LatLng.

SearchDestinationsRequest.LocationQuery.PlaceFilter

Фильтры, которые нужно применить к кандидатам на целевом ресурсе.

JSON-представление 
{
  "structureType": enum (PlaceView.StructureType),
  "addressability": enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)
}
Поля
structureType

enum (PlaceView.StructureType)

Необязательное поле. Если указано, то у всех пунктов назначения гарантированно будет основное место с этим типом структуры. В результате некоторые пункты назначения могут быть отфильтрованы, а другие – уточнены.

Например, если указано GROUNDS, у всех возвращенных пунктов назначения будет основное место с типом структуры GROUNDS. В результате некоторые пункты назначения, не относящиеся к территории, могут быть отфильтрованы, а другие – укрупнены до уровня территории.

Ещё одно применение этого поля – упрощение извлечения многоугольников, представляющих здания. Например, если указано значение BUILDING, то основной многоугольник будет относиться к зданию в указанном местоположении.
addressability

enum (SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability)

Необязательное поле. Если указано, возвращаются только пункты назначения, соответствующие критериям адресности.

PlaceView.StructureType

Тип строения, которое представляет это место.

Перечисления
STRUCTURE_TYPE_UNSPECIFIED Не используется.
POINT Точка.
SECTION Часть здания.
BUILDING Здание.
GROUNDS Большая территория, на которой обычно расположено несколько зданий, например университетский кампус, жилой комплекс или торговый центр.

SearchDestinationsRequest.LocationQuery.PlaceFilter.Addressability

Определяет параметры фильтрации по адресу. В будущем могут быть добавлены новые значения.

Перечисления
ADDRESSABILITY_UNSPECIFIED Если не указано иное, сервис выберет подходящее значение по умолчанию.
ANY Адресуемость не является критерием фильтрации. Целевые страницы возвращаются независимо от их доступности.
PRIMARY Все возвращенные пункты назначения будут иметь основное место с адресом на уровне улицы или названием.
WEAK Все возвращенные пункты назначения будут содержать либо основное место, либо дополнительный пункт назначения с адресом или названием улицы.

Место назначения

Пункт назначения. в том числе основное место, связанные места, входы и точки навигации.

JSON-представление 
{
  "primary": {
    object (PlaceView)
  },
  "containingPlaces": [
    {
      object (PlaceView)
    }
  ],
  "subDestinations": [
    {
      object (PlaceView)
    }
  ],
  "landmarks": [
    {
      object (Landmark)
    }
  ],
  "entrances": [
    {
      object (Entrance)
    }
  ],
  "navigationPoints": [
    {
      object (NavigationPoint)
    }
  ]
}
Поля
primary

object (PlaceView)

Основное место, определяемое параметром primary_query в запросе.
containingPlaces[]

object (PlaceView)

Менее точные места, в которые входит основное место. Например, жилой комплекс, в котором находится это здание.
subDestinations[]

object (PlaceView)

Более точные подпункты назначения основного места. Например, помещения в здании.

Примечание. По сравнению с объектом SubDestination, возвращаемым Places API, этот список дополнительных пунктов назначения более полный, и каждый пункт содержит больше информации.
landmarks[]

object (Landmark)

Ориентиры, которые можно использовать, чтобы сообщить, где находится пункт назначения, или помочь с прибытием.
entrances[]

object (Entrance)

Входы в это место.
navigationPoints[]

object (NavigationPoint)

Точки навигации для этого пункта назначения.

PlaceView

Представляет собой представление места в Places API. Также в нем приводится дополнительная информация о пунктах назначения, например тип структуры и многоугольник показа.

В некоторых случаях ответ PlaceView с тем же идентификатором места может отличаться от того, что возвращает Places API для полей types и displayName.

JSON-представление 
{
  "place": string,
  "placeId": string,
  "displayName": {
    object (LocalizedText)
  },
  "primaryType": string,
  "types": [
    string
  ],
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "structureType": enum (PlaceView.StructureType),
  "location": {
    object (LatLng)
  },
  "displayPolygon": {
    object
  },
  "addressComponents": [
    {
      object (PlaceView.AddressComponent)
    }
  ]
}
Поля
place

string

Название ресурса места в формате places/{placeId}. Используется для поиска места.
placeId

string

Уникальный идентификатор места.
displayName

object (LocalizedText)

Описание места, удобное для восприятия человеком. Примеры: "Выход Б", "McDonalds".
primaryType

string

Основной тип места. Список возможных значений приведен на странице https://developers.google.com/maps/documentation/places/web-service/place-types.

Примечание. Это поле заполняется не всегда. В таких случаях вам может понадобиться поле types.
types[]

string

Все типы, связанные с этим местом. Список возможных значений приведен на странице https://developers.google.com/maps/documentation/places/web-service/place-types.
formattedAddress

string

Адрес в одну строку.
postalAddress

object (PostalAddress)

Структурированный адрес.
structureType

enum (PlaceView.StructureType)

Тип структуры, соответствующий этому месту.
location

object (LatLng)

Местоположение этого места. Для мест с многоугольниками отображения это может быть хорошим местом для размещения маркера на карте.
displayPolygon

object (Struct format)

Контур многоугольника места в формате GeoJSON, соответствующем RFC 7946: https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6.

Примечание. Формат RFC 7946 поддерживает MultiPolygon, поэтому один объект displayPolygon может представлять несколько многоугольников.
addressComponents[]

object (PlaceView.AddressComponent)

Повторяющиеся компоненты для каждого уровня населенного пункта.

PlaceView.AddressComponent

Структурированные компоненты, из которых состоит отформатированный адрес (если эта информация доступна).

JSON-представление 
{
  "longText": string,
  "shortText": string,
  "types": [
    string
  ],
  "languageCode": string
}
Поля
longText

string

Полное текстовое описание или название компонента адреса. Например, компонент адреса для страны Австралия может содержать длинное название "Австралия".
shortText

string

Сокращенное текстовое название компонента адреса (если есть). Например, компонент адреса для Австралии может иметь сокращенное название "AU".
types[]

string

Массив, указывающий тип или типы компонента адреса.

Подробную информацию можно найти на странице https://developers.google.com/maps/documentation/geocoding/requests-geocoding#Types.
languageCode

string

Язык, используемый для форматирования этого компонента, в нотации CLDR.

Ориентир

Ориентиры помогают понять, где находится пункт назначения, и добраться до него.

JSON-представление 
{
  "relationalDescription": {
    object (LocalizedText)
  },
  "tags": [
    enum (Landmark.Tag)
  ],
  "straightLineDistanceMeters": number,
  "travelDistanceMeters": number,

  // Union field landmark can be only one of the following:
  "place": {
    object (PlaceView)
  }
  // End of list of possible types for union field landmark.
}
Поля
relationalDescription

object (LocalizedText)

Человекочитаемое описание того, как пункт назначения связан с ориентиром. Например, "Рядом с Эмпайр-стейт-билдинг" или "Напротив Белого дома".
tags[]

enum (Landmark.Tag)

Теги, описывающие, как ориентир может использоваться в контексте пункта назначения.
straightLineDistanceMeters

number

Используется только для вывода. Расстояние по прямой от ориентира до пункта назначения в метрах.
travelDistanceMeters

number

Только для вывода. Расстояние пешком от ориентира до пункта назначения в метрах.
Объединенное поле landmark. Ориентир. landmark может иметь одно из следующих значений:
place

object (PlaceView)

Место, где находится достопримечательность.

Landmark.Tag

Список всех возможных тегов, описывающих, как достопримечательность может использоваться в контексте пункта назначения.

Если в адресе есть теги ADDRESS и ARRIVAL, значит ориентир находится рядом с пунктом назначения и хорошо известен местным жителям.

Перечисления
TAG_UNSPECIFIED Не используется.
ADDRESS Место, известное в регионе, которое можно использовать для определения приблизительного местоположения пункта назначения. Обычно в пределах нескольких сотен метров от пункта назначения. Они похожи на ориентиры, возвращаемые функцией дескрипторов адресов Geocoding API: https://developers.google.com/maps/documentation/geocoding/address-descriptors/requests-address-descriptors.
ARRIVAL Место, которое можно использовать в качестве ориентира. Полезно для навигации, когда вы находитесь рядом с пунктом назначения. Например, это может быть место, расположенное напротив пункта назначения. Ориентир с этим тегом обычно находится ближе к пункту назначения, чем ориентиры с тегом ADDRESS.

Вход

Вход – это пара координат широты и долготы, определяющая местоположение точки входа и выхода из места.

JSON-представление 
{
  "location": {
    object (LatLng)
  },
  "tags": [
    enum (Entrance.Tag)
  ],
  "place": string
}
Поля
location

object (LatLng)

Местоположение входа.
tags[]

enum (Entrance.Tag)

Список тегов, описывающих вход.
place

string

Объект, на котором физически расположен вход, в формате places/{placeId}.

Entrance.Tag

Характеристики, описывающие вход.

Перечисления
TAG_UNSPECIFIED Не используется.
PREFERRED

Вероятно, через этот вход можно попасть в основное место, указанное в ответе. У места может быть несколько предпочтительных входов. Если у входа нет такого тега, значит он находится в том же здании, что и основное место, но не обязательно ведет к нему.

Например, если основное место – это ресторан в торговом центре, то входы со статусом PREFERRED будут вести в сам ресторан, а остальные – в другие части здания, например в другие рестораны.

Если основное место – это здание, то входы PREFERRED будут вести в "основную" часть здания. Например, в торговом центре входы PREFERRED будут вести в главный холл, а вход, ведущий только в магазин сбоку здания, не будет входом PREFERRED.

Примечание. Вход PREFERRED может не вести в основное место, а вход без значка PREFERRED может вести в основное место.