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,

  // 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)
    }
  ],
  "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,
  "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

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

Подробную информацию можно найти на странице 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,
  "streetViewThumbnail": {
    object (StreetViewThumbnail)
  },
  "streetViewAnnotation": {
    object (ImageAnnotation)
  }
}
Поля
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 может вести в основное место.

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),
  "onsiteParking": boolean,
  "freeParkingLot": boolean,
  "paidParkingLot": boolean,
  "freeStreetParking": boolean,
  "paidStreetParking": boolean,
  "valetParking": boolean,
  "freeGarageParking": boolean,
  "paidGarageParking": boolean
}
Поля
availability

enum (Destination.ParkingOptions.Availability)

Наличие парковки в пункте назначения.
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.ArrivalSummary

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

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

object (LocalizedText)

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

string

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

object (LocalizedText)

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