Method: geocode.destinations.searchDestinations

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

HTTP-запрос

POST https://geocode.googleapis.com/v4/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. Запросите основной пункт назначения. Это может быть место, полный адрес или координаты широты и долготы. Некоторые места и адреса с минимальным количеством информации нельзя будет превратить в пункт назначения.

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

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

Точные координаты широты и долготы.

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

Полное текстовое описание или название компонента адреса. Например, компонент адреса для страны Австралия может содержать полное название "Australia".
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, может вести к основному месту.