Method: geocode.destinations.searchDestinations

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

HTTP-запрос

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

В URL-адресе используется синтаксис транскодирования gRPC .

Текст запроса

Тело запроса содержит данные следующей структуры:

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

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)
    }
  ],
  "arrivalSummary": {
    object (Destination.ArrivalSummary)
  }
}
Поля
primary

object ( PlaceView )

Основное место, указанное параметром primary_query в запросе.

containingPlaces[]

object ( PlaceView )

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

subDestinations[]

object ( PlaceView )

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

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

landmarks[]

object ( Landmark )

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

entrances[]

object ( Entrance )

Входы в этот регион.

navigationPoints[]

object ( NavigationPoint )

Ориентиры для этого пункта назначения.

arrivalSummary

object ( Destination.ArrivalSummary )

Сводная информация о впечатлениях от прибытия в пункт назначения, сгенерированная искусственным интеллектом.

PlaceView

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

В некоторых случаях идентификатор места PlaceView может отличаться от того, что возвращается API Places для полей 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
  }
}
Поля
place

string

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

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 поддерживает многоугольники (MultiPolygons), поэтому один объект displayPolygon может представлять несколько многоугольников.

Достопримечательность

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

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 )

Место, которое является символом этой достопримечательности.

Достопримечательность.Тег

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

Если адрес содержит одновременно метки ADDRESS и ARRIVAL , это означает, что ориентир хорошо известен в этом районе и находится недалеко от места назначения.

Перечисления
TAG_UNSPECIFIED Не используется.
ADDRESS Заметное место в местности, которое можно использовать для определения приблизительного местоположения пункта назначения. Обычно находится в нескольких сотнях метров от пункта назначения. Они похожи на ориентиры, возвращаемые функцией «Описание адреса» 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} .

Вход.Тег

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

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

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

Например, если основным местом является ресторан в торговом центре, то в поле «ПРЕДПОЧТИТЕЛЬНЫЕ» будут указаны входы, которые, скорее всего, ведут в сам ресторан, а остальные указанные входы будут другими входами в здание, например, входами в другие рестораны в торговом центре.

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

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

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

Сводная информация о впечатлениях от прибытия в пункт назначения, сгенерированная искусственным интеллектом.

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

object ( LocalizedText )

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

flagContentUrl

string

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

disclosureText

object ( LocalizedText )

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