Служба автозаполнения (новая) — это веб-служба, которая возвращает прогнозы мест и прогнозы запросов в ответ на HTTP-запрос. В запросе укажите текстовую строку поиска и географические границы, контролирующие область поиска.
Служба автозаполнения (новая) может сопоставлять полные слова и подстроки входных данных, распознавая названия мест, адреса и плюсовые коды . Таким образом, приложения могут отправлять запросы по мере ввода пользователем, чтобы оперативно предоставлять прогнозы по местоположению и запросам.
Ответ от API автозаполнения (нового) может содержать два типа прогнозов:
- Подсказки мест : места, такие как предприятия, адреса и достопримечательности, на основе указанной входной текстовой строки и области поиска. Подсказки мест возвращаются по умолчанию.
- Прогнозы запроса : строки запроса, соответствующие входной текстовой строке и области поиска. Прогнозы запроса не возвращаются по умолчанию. Используйте параметр запроса
includeQueryPredictions
, чтобы добавить прогнозы запроса в ответ.
Например, вы вызываете API, используя в качестве входных данных строку, содержащую частичный пользовательский ввод «Сицилийский пиз», с областью поиска, ограниченной Сан-Франциско, Калифорния. Затем ответ содержит список подсказок мест , соответствующих строке поиска и области поиска, например ресторан под названием «Sicilian Pizza Kitchen», а также подробную информацию об этом месте.
Возвращенные прогнозы мест предназначены для представления пользователю, чтобы помочь ему выбрать желаемое место. Вы можете сделать запрос «Сведения о месте (новое)» , чтобы получить дополнительную информацию о любом из возвращенных прогнозов мест.
Ответ также может содержать список подсказок запроса , соответствующих строке поиска и области поиска, например «Сицилийская пицца и паста». Каждый прогноз запроса в ответе включает text
поле, содержащее рекомендуемую строку текстового поиска. Используйте эту строку в качестве входных данных для текстового поиска (новое), чтобы выполнить более подробный поиск.
API Explorer позволяет вам делать запросы в реальном времени, чтобы вы могли ознакомиться с API и опциями API:
Попробуйте!Автозаполнение (новые) запросы
Запрос автозаполнения (новый) — это запрос HTTP POST к URL-адресу в форме:
https://places.googleapis.com/v1/places:autocomplete
Передайте все параметры в теле запроса JSON или в заголовках как часть запроса POST. Например:
curl -X POST -d '{ "input": "pizza", "locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Об ответе
Автозаполнение (новое) возвращает объект JSON в качестве ответа. В ответ:
- Массив
suggestions
содержит все прогнозируемые места и запросы в порядке их предполагаемой релевантности. Каждое место представлено полемplacePrediction
, а каждый запрос представлен полемqueryPrediction
. - Поле
placePrediction
содержит подробную информацию об одном предсказании места, включая идентификатор места и текстовое описание. - Поле
queryPrediction
содержит подробную информацию о прогнозе одного запроса.
Полный объект JSON имеет вид:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 }] }, ... }, { "queryPrediction": { "text": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 }] }, ... } ...] }
Обязательные параметры
вход
Текстовая строка, по которой осуществляется поиск. Укажите полные слова и подстроки, географические названия, адреса и плюсовые коды . Служба автозаполнения (новая) возвращает совпадения кандидатов на основе этой строки и упорядочивает результаты на основе их предполагаемой релевантности.
Дополнительные параметры
включенные первичные типы
Место может иметь только один основной тип из типов, перечисленных в Таблице A или Таблице B. Например, основным типом может быть
"mexican_restaurant"
или"steak_house"
.По умолчанию API возвращает все места на основе
input
параметра, независимо от значения основного типа, связанного с этим местом. Ограничьте результаты определенным основным типом или основными типами, передав параметрincludedPrimaryTypes
.Используйте этот параметр, чтобы указать до пяти значений типа из таблицы A или таблицы B. Для включения в ответ место должно соответствовать одному из указанных значений основного типа.
Вместо этого этот параметр также может включать один из
(regions)
или(cities)
. Фильтры сбора типов(regions)
для областей или подразделений, таких как районы и почтовые индексы. Коллекция типов(cities)
фильтрует места, которые Google идентифицирует как города.Запрос отклоняется с ошибкой
INVALID_REQUEST
, если:- Указано более пяти типов.
- Помимо
(cities)
или(regions)
указывается любой тип. - Указываются любые нераспознанные типы.
includeQueryPredictions
Если
true
, ответ включает в себя как прогнозы места, так и запроса. Значение по умолчанию —false
, что означает, что ответ включает только прогнозы мест.включенные коды регионов
Включайте результаты только из списка указанных регионов, заданного в виде массива, содержащего до 15 двухсимвольных значений ccTLD («домен верхнего уровня») . Если этот параметр опущен, к ответу не применяются никакие ограничения. Например, чтобы ограничить регионы Германией и Францией:
"includedRegionCodes": ["de", "fr"]
Если вы укажете и
locationRestriction
, иincludedRegionCodes
, результаты будут расположены в области пересечения двух настроек.inputOffset
Смещение символов Юникода, отсчитываемое от нуля, указывающее позицию курсора во
input
. Положение курсора может влиять на то, какие прогнозы возвращаются. Если пусто, по умолчанию используется длинаinput
.языковой код
Предпочитаемый язык для возврата результатов. Результаты могут быть на смешанных языках, если язык, используемый во
input
отличается от значения, указанного в параметреlanguageCode
, или если возвращаемое место не имеет перевода с локального языка наlanguageCode
.- Для указания предпочтительного языка необходимо использовать языковые коды IETF BCP-47 .
- Если
languageCode
не указан, API использует значение, указанное в заголовкеAccept-Language
. Если ни один из них не указан, по умолчанию используетсяen
. Если вы укажете неверный код языка, API вернет ошибкуINVALID_ARGUMENT
. - Предпочтительный язык оказывает небольшое влияние на набор результатов, которые API выбирает для возврата, и порядок их возврата. Это также влияет на способность API исправлять орфографические ошибки.
- API пытается предоставить почтовый адрес, который будет доступен для чтения как пользователю, так и местному населению, и в то же время отражает вводимые пользователем данные. Подсказки мест форматируются по-разному в зависимости от вводимых пользователем данных в каждом запросе.
- Соответствующие термины во
input
параметре выбираются первыми, используя имена, соответствующие языковым предпочтениям, указанным в параметреlanguageCode
, если он доступен, а в противном случае используются имена, которые лучше всего соответствуют вводу пользователя. - Уличные адреса форматируются на местном языке, в сценарии, который, если возможно, читается пользователем только после того, как соответствующие термины были выбраны в соответствии с терминами во
input
параметре. - Все остальные адреса возвращаются на предпочитаемом языке после того, как соответствующие термины были выбраны для соответствия терминам во
input
параметре. Если имя недоступно на предпочитаемом языке, API использует наиболее близкое совпадение.
- Соответствующие термины во
предвзятость местоположения или ограничение местоположения
Вы можете указать
locationBias
илиlocationRestriction
, но не оба, чтобы определить область поиска. Подумайте оlocationRestriction
как об указании региона, в котором должны находиться результаты, аlocationBias
как об указании региона, рядом с которым результаты должны находиться, но могут находиться за его пределами.Смещение местоположения
Указывает область для поиска. Это местоположение служит смещением, что означает, что могут быть возвращены результаты вокруг указанного местоположения, включая результаты за пределами указанной области.
МестоположениеОграничение
Указывает область для поиска. Результаты за пределами указанной области не возвращаются.
Укажите область
locationBias
илиlocationRestriction
в виде прямоугольного видового экрана или круга.Круг определяется центральной точкой и радиусом в метрах. Радиус должен находиться в диапазоне от 0,0 до 50000,0 включительно. Значение по умолчанию — 0,0. Для
locationRestriction
необходимо установить радиус больше 0,0. В противном случае запрос не возвращает результатов.Например:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Прямоугольник — это окно просмотра широты и долготы, представленное в виде двух диагонально противоположных
low
и верхней точек. Область просмотра считается закрытой областью, то есть включает в себя ее границу. Границы широты должны находиться в диапазоне от -90 до 90 градусов включительно, а границы долготы должны находиться в диапазоне от -180 до 180 градусов включительно:- Если
low
=high
, область просмотра состоит из этой единственной точки. - Если
low.longitude
>high.longitude
, диапазон долготы инвертируется (окно просмотра пересекает линию долготы в 180 градусов). - Если
low.longitude
= -180 градусов иhigh.longitude
= 180 градусов, область просмотра включает все значения долготы. - Если
low.longitude
= 180 градусов иhigh.longitude
= -180 градусов, диапазон долготы пуст.
Оба значения
low
иhigh
должны быть заполнены, а представленное поле не может быть пустым. Пустое окно просмотра приводит к ошибке.Например, это окно просмотра полностью охватывает Нью-Йорк:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- Если
источник
Исходная точка, от которой рассчитывается расстояние по прямой до пункта назначения (возвращается как
distanceMeters
). Если это значение опущено, расстояние по прямой не будет возвращено. Необходимо указать координаты широты и долготы:"origin": { "latitude": 40.477398, "longitude": -74.259087 }
Код региона
Код региона, используемый для форматирования ответа, указанный в виде двухсимвольного значения ccTLD («домен верхнего уровня») . Большинство кодов ccTLD идентичны кодам ISO 3166-1, за некоторыми заметными исключениями. Например, нДВУ Соединенного Королевства — «uk» (.co.uk), а код ISO 3166-1 — «gb» (технически для организации «Соединенное Королевство Великобритании и Северной Ирландии»).
Если вы укажете неверный код региона, API вернет ошибку
INVALID_ARGUMENT
. Параметр может повлиять на результаты в соответствии с действующим законодательством.сессионный токен
Токены сеанса — это созданные пользователем строки, которые отслеживают вызовы автозаполнения (новые) как «сеансы». Автозаполнение (новое) использует токены сеанса для группировки этапов запроса и выбора пользовательского поиска с автозаполнением в отдельный сеанс для целей выставления счетов. Дополнительные сведения см. в разделе Токены сеанса .
Примеры автозаполнения (новые)
Используйте locationRestriction и locationBias
API по умолчанию использует смещение IP-адреса для управления областью поиска. При смещении IP API использует IP-адрес устройства для смещения результатов. При желании вы можете использовать locationRestriction
или locationBias
, но не оба, чтобы указать область для поиска.
locationRestriction
указывает область для поиска. Результаты за пределами указанной области не возвращаются. В следующем примере вы используете locationRestriction
, чтобы ограничить запрос кругом радиусом 5000 метров с центром в Сан-Франциско:
curl -X POST -d '{ "input": "Amoeba", "locationRestriction": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Все результаты из указанных областей содержатся в массиве suggestions
:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "home_goods_store", "establishment", "store", "point_of_interest", "electronics_store" ] } } ] }
При использовании locationBias
местоположение служит смещением, что означает, что могут быть возвращены результаты вокруг указанного местоположения, включая результаты за пределами указанной области. В следующем примере вы измените запрос на использование locationBias
:
curl -X POST -d '{ "input": "Amoeba", "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Результаты теперь содержат гораздо больше элементов, включая результаты за пределами радиуса 5000 метров:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "store", "establishment", "home_goods_store" ] } }, { "placePrediction": { "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw", "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw", "text": { "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Telegraph Avenue, Berkeley, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "establishment", "home_goods_store", "store" ] } }, ... ] }
Используйте включенные первичные типы
Используйте параметр includedPrimaryTypes
, чтобы указать до пяти значений типа из Table A , Table B , only (regions)
или only (cities)
. Для включения в ответ место должно соответствовать одному из указанных значений основного типа.
В следующем примере вы указываете input
строку «Soccer» и используете параметр includedPrimaryTypes
, чтобы ограничить результаты заведениями типа "sporting_goods_store"
:
curl -X POST -d '{ "input": "Soccer", "includedPrimaryTypes": ["sporting_goods_store"], "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Если вы опустите параметр includedPrimaryTypes
, результаты могут включать заведения нежелательного типа, например "athletic_field"
.
Запросить прогнозы запросов
Прогнозы запроса не возвращаются по умолчанию. Используйте параметр запроса includeQueryPredictions
, чтобы добавить прогнозы запроса в ответ. Например:
curl -X POST -d '{ "input": "Amoeba", "includeQueryPredictions": true, "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Массив suggestions
теперь содержит как прогнозы мест, так и прогнозы запросов, как показано выше в разделе «Об ответе» . Каждый прогноз запроса включает text
поле, содержащее рекомендуемую строку текстового поиска. Вы можете сделать запрос на текстовый поиск (новый) , чтобы получить дополнительную информацию о любом из возвращаемых прогнозов запроса.
Использовать происхождение
В этом примере включите в запрос origin
как координаты широты и долготы. Когда вы включаете origin
, API включает в ответ поле distanceMeters
, которое содержит расстояние по прямой от origin
до пункта назначения. В этом примере начало координат устанавливается в центр Сан-Франциско:
curl -X POST -d '{ "input": "Amoeba", "origin": { "latitude": 37.7749, "longitude": -122.4194 }, "locationRestriction": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Теперь ответ включает в себя distanceMeters
:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "home_goods_store", "establishment", "point_of_interest", "store", "electronics_store" ], "distanceMeters": 3012 } } ] }
Попробуйте!
API Explorer позволяет вам создавать примеры запросов, чтобы вы могли ознакомиться с API и опциями API.
- Выберите значок API,
, в правой части страницы.
- При необходимости разверните Показать стандартные параметры и установите для параметра
fields
маску поля . - При желании отредактируйте тело запроса .
- Нажмите кнопку «Выполнить» . Во всплывающем окне выберите учетную запись, которую вы хотите использовать для отправки запроса.
На панели API Explorer выберите значок развертывания,
, чтобы развернуть окно API Explorer.