Method: geocode.destinations.searchDestinations

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

HTTP-запрос

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

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

Тело запроса

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

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

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

enum (SearchDestinationsRequest.Effort)

Необязательное поле. Уровень усилий, запрошенный клиентом.

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

SearchDestinationsRequest.Effort

Уровень усилий, выделенных на разрешение целевых страниц.

Перечисления
EFFORT_UNSPECIFIED Значение по умолчанию.
LOW Оптимизирована для максимально быстрого ответа. Выполняет прямой поиск пункта назначения без расширенного обхода иерархии или сложного устранения неоднозначности места.
MEDIUM Баланс между скоростью и точностью. Большинство запросов возвращаются со стандартной низкой задержкой. Для неоднозначных запросов, сайтов с несколькими зданиями или сложных местоположений сервис применяет дополнительную обработку для разрешения пунктов назначения и иерархического контекста с ограниченной задержкой, которая может занять до нескольких секунд. Рекомендуется для интерактивных рабочих процессов, в которых пользователи могут подождать некоторое время.
HIGH Повышает точность и полноту определения пункта назначения для сложных, неформальных или обширных локаций (например, крупных кампусов или жилых комплексов). Время ответа может быть значительно больше. Рекомендуется для фоновых, пакетных, диспетчерских или логистических рабочих процессов предварительной маршрутизации.

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

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

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

object (PlaceView)

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

object (PlaceView)

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

object (PlaceView)

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

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

object (Landmark)

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

object (Entrance)

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

object (NavigationPoint)

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

object (Destination.ParkingOptions)

Варианты парковки в этом пункте назначения.
arrivalSummary

object (Destination.ArrivalSummary)

Сводка о прибытии в пункт назначения, созданная ИИ.

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,
  "streetViewThumbnail": {
    object (StreetViewThumbnail)
  },
  "streetViewAnnotation": {
    object (ImageAnnotation)
  }
}
Поля
displayName

object (LocalizedText)

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

object (LatLng)

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

enum (Entrance.Tag)

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

string

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

object (StreetViewThumbnail)

Значок Просмотра улиц, на котором показан вход. Изображение можно запросить из Street View Static API. Подробнее: https://developers.google.com/maps/documentation/streetview/request-streetview.
streetViewAnnotation

object (ImageAnnotation)

Аннотация входа на streetViewThumbnail, возвращенная выше.

Entrance.Tag

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

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

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

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

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

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

StreetViewThumbnail

Параметры для представления значка Google Просмотра улиц. Эти параметры можно использовать для запроса изображения Просмотра улиц из Street View Static API. Подробнее: https://developers.google.com/maps/documentation/streetview/request-streetview.

JSON-представление 
{
  "pano": string,
  "widthPx": integer,
  "heightPx": integer,
  "headingDegree": number,
  "pitchDegree": number,
  "fovDegree": number
}
Поля
pano

string

Идентификатор панорамы.
widthPx

integer

Ширина значка в пикселях. Примечание. При запросе аннотаций вместе со значком эти значения высоты и ширины должны использоваться в запросе Street View API, чтобы координаты аннотации правильно совпадали с изображением.
heightPx

integer

Высота значка в пикселях. Примечание. При запросе аннотаций вместе со значком эти значения высоты и ширины должны использоваться в запросе Street View API, чтобы координаты аннотации правильно совпадали с изображением.
headingDegree

number

Горизонтальная ориентация камеры в градусах. Диапазон: [0, 360). 0 означает север, а 90 – восток.
pitchDegree

number

Вертикальная ориентация камеры в градусах. Диапазон: [-90, 90]. 0 – горизонт, +90 – строго вверх, -90 – строго вниз.
fovDegree

number

Горизонтальная зона обзора в градусах. Диапазон: (0, 180]. Управляет уровнем масштабирования. Чем меньше поле зрения, тем больше увеличение.

ImageAnnotation

Аннотация на уменьшенном изображении, например многоугольник, обозначающий вход.

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

object (ImageAnnotation.Coordinate)

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

ImageAnnotation.Coordinate

Пиксельные координаты точки на изображении. Начало координат (0,0) – это верхний левый угол верхнего левого пикселя изображения. Ось X направлена вправо, а ось Y – вниз.

JSON-представление 
{
  "xPx": number,
  "yPx": number
}
Поля
xPx

number

Координата X.
yPx

number

Координата Y.

Destination.ParkingOptions

Информация о парковках в пункте назначения.

JSON-представление 
{
  "availability": enum (Destination.ParkingOptions.Availability),
  "parkingFacilities": [
    {
      object (Destination.ParkingOptions.ParkingFacility)
    }
  ],
  "onsiteParking": boolean,
  "freeParkingLot": boolean,
  "paidParkingLot": boolean,
  "freeStreetParking": boolean,
  "paidStreetParking": boolean,
  "valetParking": boolean,
  "freeGarageParking": boolean,
  "paidGarageParking": boolean
}
Поля
availability

enum (Destination.ParkingOptions.Availability)

Доступность парковки в этом месте.
parkingFacilities[]

object (Destination.ParkingOptions.ParkingFacility)

Парковка в пункте назначения.
onsiteParking

boolean

На территории отеля есть парковка.
freeParkingLot

boolean

Есть бесплатная парковка.
paidParkingLot

boolean

Есть платные парковки.
freeStreetParking

boolean

Есть бесплатная уличная парковка.
paidStreetParking

boolean

Есть платная уличная парковка.
valetParking

boolean

Есть услуги парковщика.
freeGarageParking

boolean

Есть бесплатная крытая стоянка.
paidGarageParking

boolean

Есть платная крытая парковка.

Destination.ParkingOptions.Availability

Общая оценка того, насколько сложно найти парковку рядом с этим местом.

В будущем могут быть добавлены новые значения.

Перечисления
AVAILABILITY_UNSPECIFIED Информация о наличии парковки недоступна.
PLENTY Парковочных мест достаточно.
SOMEWHAT_DIFFICULT Парковку найти непросто.
DIFFICULT Найти место для парковки очень сложно.

Destination.ParkingOptions.ParkingFacility

Отдельный вариант парковки (например, конкретный гараж или стоянка), связанный с пунктом назначения. В нем содержится подробная информация об определенной парковке, а в родительском сообщении ParkingOptions – сводные данные обо всех доступных парковках.

JSON-представление 
{
  "place": {
    object (PlaceView)
  },
  "onsite": boolean,
  "popular": boolean,
  "straightLineDistanceMeters": number
}
Поля
place

object (PlaceView)

Представление места для этой парковки.
onsite

boolean

Расположена ли парковка на территории основного пункта назначения. Если это поле не заполнено, статус неизвестен.
popular

boolean

Популярна ли эта парковка среди посетителей, направляющихся к основному пункту назначения. Если это поле не заполнено, статус популярности неизвестен.
straightLineDistanceMeters

number

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

Destination.ArrivalSummary

Сводка о прибытии в пункт назначения, созданная ИИ.

JSON-представление 
{
  "text": {
    object (LocalizedText)
  },
  "flagContentUrl": string,
  "disclosureText": {
    object (LocalizedText)
  }
}
Поля
text

object (LocalizedText)

Краткое описание прибытия в пункт назначения.
flagContentUrl

string

Ссылка, по которой пользователи могут сообщить о проблеме с кратким пересказом.
disclosureText

object (LocalizedText)

Только для вывода. Содержит текст раскрытия информации для сводки о прибытии.