Method: places.autocomplete

Возвращает прогнозы для заданного входного значения.

HTTP-запрос

POST https://places.googleapis.com/v1/places:autocomplete

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

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

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

JSON-представление 
{
  "input": string,
  "locationBias": {
    object (LocationBias)
  },
  "locationRestriction": {
    object (LocationRestriction)
  },
  "includedPrimaryTypes": [
    string
  ],
  "includedRegionCodes": [
    string
  ],
  "languageCode": string,
  "regionCode": string,
  "origin": {
    object (LatLng)
  },
  "inputOffset": integer,
  "includeQueryPredictions": boolean,
  "sessionToken": string,
  "includePureServiceAreaBusinesses": boolean,
  "includeFutureOpeningBusinesses": boolean
}
Поля
input

string

Обязательно. Текстовая строка, по которой будет производиться поиск.

locationBias

object ( LocationBias )

Необязательно. Приведение результатов к определенному местоположению.

Необходимо установить максимум один из параметров: locationBias или locationRestriction . Если ни один из них не установлен, результаты будут искажены IP-адресом, то есть IP-адрес будет сопоставлен с неточным местоположением и использован в качестве сигнала искажения.

locationRestriction

object ( LocationRestriction )

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

Необходимо установить максимум один из параметров: locationBias или locationRestriction . Если ни один из них не установлен, результаты будут искажены IP-адресом, то есть IP-адрес будет сопоставлен с неточным местоположением и использован в качестве сигнала искажения.

includedPrimaryTypes[]

string

Необязательно. Укажите основной тип места (например, "ресторан" или "заправка") в списке типов мест ( https://developers.google.com/maps/documentation/places/web-service/place-types) , или только (regions) , или только (cities) . Место возвращается только в том случае, если его основной тип включен в этот список. Можно указать до 5 значений. Если типы не указаны, возвращаются все типы мест.

includedRegionCodes[]

string

Необязательно. Включать результаты только из указанных регионов, заданных в виде до 15 двухсимвольных кодов регионов CLDR. Пустой набор не будет ограничивать результаты. Если заданы параметры locationRestriction и includedRegionCodes , результаты будут расположены в области пересечения.

languageCode

string

Необязательный параметр. Язык, на котором будут возвращаться результаты. По умолчанию используется en-US. Результаты могут быть на разных языках, если язык, использованный во input , отличается от languageCode или если возвращаемое место не имеет перевода с местного языка на languageCode .

regionCode

string

Необязательный параметр. Код региона, указанный в виде двухсимвольного кода региона CLDR. Это влияет на форматирование адреса, ранжирование результатов и может повлиять на то, какие результаты будут возвращены. Это не ограничивает результаты указанным регионом. Чтобы ограничить результаты регионом, используйте region_code_restriction .

origin

object ( LatLng )

Необязательный параметр. Начальная точка, от которой рассчитывается геодезическое расстояние до пункта назначения (возвращается значение типа distanceMeters ). Если этот параметр опущен, геодезическое расстояние не будет возвращено.

inputOffset

integer

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

Если поле пустое, значение по умолчанию равно длине input .

includeQueryPredictions

boolean

Необязательный параметр. Если значение равно true, ответ будет содержать как предсказания по месту, так и предсказания по запросу. В противном случае ответ будет содержать только предсказания по месту.

sessionToken

string

Необязательный параметр. Строка, идентифицирующая сессию автозаполнения для целей выставления счетов. Должна представлять собой безопасную для URL-адресов и имен файлов строку в формате base64 длиной не более 36 символов ASCII. В противном случае возвращается ошибка INVALID_ARGUMENT.

Сессия начинается, когда пользователь начинает вводить запрос, и завершается, когда он выбирает место и выполняется вызов функции проверки сведений о месте или адреса. Каждая сессия может содержать несколько запросов, за которыми следует один запрос на проверку сведений о месте или адреса. Учетные данные, используемые для каждого запроса в рамках сессии, должны принадлежать одному и тому же проекту Google Cloud Console. После завершения сессии токен становится недействительным; ваше приложение должно генерировать новый токен для каждой сессии. Если параметр sessionToken опущен или если вы повторно используете токен сессии, оплата за сессию производится так, как если бы токен сессии не был предоставлен (каждый запрос оплачивается отдельно).

Мы рекомендуем следующие рекомендации:

  • Используйте токены сессии для всех вызовов функции автозаполнения.
  • Для каждой сессии генерируйте новый токен. Рекомендуется использовать UUID версии 4.
  • Убедитесь, что учетные данные, используемые для всех запросов автозаполнения места, сведений о месте и проверки адреса в рамках одной сессии, относятся к одному и тому же проекту Cloud Console.
  • Обязательно передавайте уникальный токен сессии для каждой новой сессии. Использование одного и того же токена для нескольких сессий приведет к тому, что каждый запрос будет оплачиваться отдельно.
includePureServiceAreaBusinesses

boolean

Необязательно. Если поле установлено в значение true, следует включить только компании, работающие в определенной зоне обслуживания. К таким компаниям относятся те, которые посещают клиентов или доставляют им товары напрямую, но не обслуживают их по своему адресу. Например, клининговые компании или сантехнические фирмы. У таких компаний нет физического адреса или местоположения на Google Maps. В результатах поиска по запросу «Места» поля, включая location , plusCode и другие поля, связанные с местоположением, для таких компаний отображаться не будут.

includeFutureOpeningBusinesses

boolean

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

Ответный текст

Прототип ответа для places.autocomplete.

В случае успеха тело ответа содержит данные следующей структуры:

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

object ( Suggestion )

Содержит список предложений, упорядоченных в порядке убывания релевантности.

Области полномочий

Требуется следующая область действия OAuth:

  • https://www.googleapis.com/auth/cloud-platform

LocationBias

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

JSON-представление 
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
Поля

type поля объединения.

type может быть только одним из следующих:

rectangle

object ( Viewport )

Видовое окно, ограниченное северо-восточным и юго-западным углами.

circle

object ( Circle )

Окружность, определяемая центром и радиусом.

Ограничение местоположения

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

JSON-представление 
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
Поля

type поля объединения.

type может быть только одним из следующих:

rectangle

object ( Viewport )

Видовое окно, ограниченное северо-восточным и юго-западным углами.

circle

object ( Circle )

Окружность, определяемая центром и радиусом.

Предположение

Результат автозаполнения.

JSON-представление 
{

  // Union field kind can be only one of the following:
  "placePrediction": {
    object (PlacePrediction)
  },
  "queryPrediction": {
    object (QueryPrediction)
  }
  // End of list of possible types for union field kind.
}
Поля

kind поля Союза.

kind может быть только одним из следующих:

placePrediction

object ( PlacePrediction )

Прогноз для одного места.

queryPrediction

object ( QueryPrediction )

Прогноз для запроса.

Прогнозирование местоположения

Результаты прогнозирования для функции автозаполнения места.

JSON-представление 
{
  "place": string,
  "placeId": string,
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  },
  "types": [
    string
  ],
  "distanceMeters": integer
}
Поля
place

string

Название ресурса предлагаемого места. Это название можно использовать в других API, которые принимают названия мест.

placeId

string

Уникальный идентификатор предлагаемого места. Этот идентификатор можно использовать в других API, которые принимают идентификаторы мест.

text

object ( FormattableText )

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

Использование text рекомендуется разработчикам, которые хотят отобразить один элемент пользовательского интерфейса. Разработчикам, которые хотят отобразить два отдельных, но связанных между собой элемента пользовательского интерфейса, может быть полезно использовать structuredFormat . Это два разных способа представления прогноза местоположения. Пользователям не следует пытаться преобразовывать structuredFormat в text или наоборот.

Этот текст может отличаться от displayName возвращаемого функцией places.get.

Возможно использование смешанных языков, если input запроса и languageCode указаны на разных языках или если для данного места отсутствует перевод с местного языка на languageCode .

structuredFormat

object ( StructuredFormat )

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

structuredFormat рекомендуется разработчикам, которые хотят отображать два отдельных, но связанных между собой элемента пользовательского интерфейса. Разработчикам, которые хотят отображать один элемент пользовательского интерфейса, может быть удобнее использовать text . Это два разных способа представления прогноза местоположения. Пользователям не следует пытаться преобразовывать structuredFormat в text или наоборот.

types[]

string

Список типов, применимых к этому месту, взят из таблицы A или таблицы B по адресу https://developers.google.com/maps/documentation/places/web-service/place-types .

Тип — это классификация места. Места с общим типом будут обладать схожими характеристиками.

distanceMeters

integer

Длина геодезической линии в метрах от origin , если origin указано. Некоторые прогнозы, такие как маршруты, могут не заполнять это поле.

Форматируемый текст

Текст, представляющий собой прогноз местоположения или запроса. Текст может использоваться как в исходном виде, так и в отформатированном.

JSON-представление 
{
  "text": string,
  "matches": [
    {
      object (StringRange)
    }
  ]
}
Поля
text

string

Текст, который можно использовать как есть или отформатировать с помощью matches .

matches[]

object ( StringRange )

Список диапазонов строк, определяющих, где запрос на ввод совпал с text . Диапазоны можно использовать для форматирования определенных частей text . Подстроки могут не являться точным совпадением с input , если совпадение определялось критериями, отличными от сопоставления строк (например, исправление орфографических ошибок или транслитерация).

Эти значения представляют собой смещения символов text в формате Unicode. Гарантируется, что диапазоны упорядочены в порядке возрастания значений смещения.

StringRange

Определяет подстроку в заданном тексте.

JSON-представление 
{
  "startOffset": integer,
  "endOffset": integer
}
Поля
startOffset

integer

Смещение первого символа Unicode в строке (включая нуль) от начала координат.

endOffset

integer

Смещение последнего символа Unicode (исключая нуль).

Структурированный формат

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

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

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

JSON-представление 
{
  "mainText": {
    object (FormattableText)
  },
  "secondaryText": {
    object (FormattableText)
  }
}
Поля
mainText

object ( FormattableText )

Представляет собой название места или запроса.

secondaryText

object ( FormattableText )

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

QueryPrediction

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

JSON-представление 
{
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  }
}
Поля
text

object ( FormattableText )

Предсказанный текст. Этот текст не представляет собой местоположение, а скорее текстовый запрос, который можно использовать в поисковой системе (например, текстовый поиск).

Использование text рекомендуется разработчикам, которые хотят отобразить один элемент пользовательского интерфейса. Разработчикам, которые хотят отобразить два отдельных, но связанных между собой элемента пользовательского интерфейса, может быть целесообразно использовать structuredFormat . Это два разных способа представления прогноза запроса. Пользователям не следует пытаться преобразовывать structuredFormat в text или наоборот.

Возможно, проблема возникает при использовании смешанных языков, если input данные запроса и languageCode указаны на разных языках или если часть запроса не имеет перевода с локального языка на languageCode .

structuredFormat

object ( StructuredFormat )

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

structuredFormat рекомендуется разработчикам, которые хотят отображать два отдельных, но связанных между собой элемента пользовательского интерфейса. Разработчикам, желающим отобразить один элемент пользовательского интерфейса, может быть удобнее использовать text . Это два разных способа представления прогнозируемого запроса. Пользователям не следует пытаться преобразовывать structuredFormat в text или наоборот.