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,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "place": string,
  "addressQuery": {
    object (SearchDestinationsRequest.AddressQuery)
  },
  "locationQuery": {
    object (SearchDestinationsRequest.LocationQuery)
  }
  // End of mutually exclusive fields.
}
Поля
travelModes[]

enum (NavigationPoint.TravelMode)

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

string

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

string

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

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

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

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

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "address": {
    object (PostalAddress)
  },
  "addressQuery": string
  // End of mutually exclusive fields.
}
Поля
Запрос адреса. Ниже приведен список взаимоисключающих полей. В ответе будет задано не более одного из следующих полей:
address

object (PostalAddress)

Почтовый адрес в формате почтового адреса.
addressQuery

string

Почтовый адрес, записанный в одну строку.
Конец взаимоисключающих полей.

SearchDestinationsRequest.LocationQuery

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

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

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

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "location": {
    object (LatLng)
  }
  // End of mutually exclusive fields.
}
Поля
placeFilter

object (SearchDestinationsRequest.LocationQuery.PlaceFilter)

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

Понятное человеку описание места. Пример: "Выход B", "Макдоналдс".
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

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

Эти значения взяты из таблицы типов адресов и их компонентов, которая используется в Places API: https://developers.google.com/maps/documentation/places/web-service/place-types#address-types.
languageCode

string

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

Ориентир

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

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

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "place": {
    object (PlaceView)
  }
  // End of mutually exclusive fields.
}
Поля
relationalDescription

object (LocalizedText)

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

enum (Landmark.Tag)

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

number

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

number

Только для вывода. Расстояние пешком от ориентира до пункта назначения в метрах.
ориентир; Ниже приведен список взаимоисключающих полей. В ответе будет задано не более одного из следующих полей:
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-представление 
{
  "displayName": {
    object (LocalizedText)
  },
  "location": {
    object (LatLng)
  },
  "tags": [
    enum (Entrance.Tag)
  ],
  "place": string
}
Поля
displayName

object (LocalizedText)

Понятное название, например "Выход B", "Южный вход", "Вход с 5-й авеню".
location

object (LatLng)

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

enum (Entrance.Tag)

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

string

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

Entrance.Tag

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

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

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

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

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

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