Служба автозаполнения (новая) — это веб-служба, которая возвращает прогнозы мест и прогнозы запросов в ответ на 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
}]
},
...
}
...]
}Обязательные параметры
вход
Текстовая строка, по которой осуществляется поиск. Укажите полные слова и подстроки, географические названия, адреса и плюсовые коды . Служба автозаполнения (новая) возвращает совпадения кандидатов на основе этой строки и упорядочивает результаты на основе их предполагаемой релевантности.
Дополнительные параметры
Маска поля
Укажите список полей, которые будут возвращены в ответе, создав маску поля ответа . Передайте маску поля ответа методу, используя HTTP-заголовок
X-Goog-FieldMask.Укажите разделенный запятыми список предлагаемых полей для возврата. Например, чтобы получить
suggestions.placePrediction.placeиsuggestions.placePrediction.textпредложения.X-Goog-FieldMask: places.displayName,places.formattedAddress
Используйте
*, чтобы получить все поля.X-Goog-FieldMask: *
включенные первичные типы
Место может иметь только один основной тип из типов, перечисленных в Таблице A или Таблице B. Например, основным типом может быть
"mexican_restaurant"или"steak_house".По умолчанию API возвращает все места на основе
inputпараметра, независимо от значения основного типа, связанного с этим местом. Ограничьте результаты определенным основным типом или основными типами, передав параметрincludedPrimaryTypes.Используйте этот параметр, чтобы указать до пяти значений типа из таблицы A или таблицы B. Для включения в ответ место должно соответствовать одному из указанных значений основного типа.
Вместо этого этот параметр также может включать один из
(regions)или(cities). Фильтры сбора типов(regions)для областей или подразделений, таких как районы и почтовые индексы. Коллекция типов(cities)фильтрует места, которые Google идентифицирует как города.Запрос отклоняется с ошибкой
INVALID_REQUEST, если:- Указано более пяти типов.
- Помимо
(cities)или(regions)указывается любой тип. - Указываются любые нераспознанные типы.
includePureServiceAreaBusinesses
Если установлено значение
true, в ответ будут включены компании, которые посещают клиентов или осуществляют доставку напрямую клиентам, но не имеют физического местоположения. Если установлено значениеfalse, API возвращает только компании с физическим местоположением.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
locationRestriction указывает область для поиска. Результаты за пределами указанной области не возвращаются. В следующем примере вы используете locationRestriction , чтобы ограничить запрос кругом радиусом 5000 метров с центром в Сан-Франциско:
curl -X POST -d '{
"input": "Art museum",
"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/ChIJkQQVTZqAhYARHxPt2iJkm1Q", "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q", "text": { "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "structuredFormat": { "mainText": { "text": "Asian Art Museum", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "secondaryText": { "text": "Larkin Street, San Francisco, CA, USA" } }, "types": [ "establishment", "museum", "point_of_interest" ] } }, { "placePrediction": { "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w", "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w", "text": { "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA", "matches": [ { "endOffset": 15 } ] }, "structuredFormat": { "mainText": { "text": "de Young Museum", "matches": [ { "endOffset": 15 } ] }, "secondaryText": { "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA" } }, "types": [ "establishment", "point_of_interest", "tourist_attraction", "museum" ] } }, /.../ ] }
Вы также можете использовать locationRestriction , чтобы ограничить поиск прямоугольным окном просмотра . В следующем примере запрос ограничивается центром Сан-Франциско:
curl -X POST -d '{
"input": "Art museum",
"locationRestriction": {
"rectangle": {
"low": {
"latitude": 37.7751,
"longitude": -122.4219
},
"high": {
"latitude": 37.7955,
"longitude": -122.3937
}
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
Результаты содержатся в массиве suggestions :
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q", "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q", "text": { "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "structuredFormat": { "mainText": { "text": "Asian Art Museum", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "secondaryText": { "text": "Larkin Street, San Francisco, CA, USA" } }, "types": [ "point_of_interest", "museum", "establishment" ] } }, { "placePrediction": { "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc", "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc", "text": { "text": "International Art Museum of America, Market Street, San Francisco, CA, USA", "matches": [ { "startOffset": 14, "endOffset": 24 } ] }, "structuredFormat": { "mainText": { "text": "International Art Museum of America", "matches": [ { "startOffset": 14, "endOffset": 24 } ] }, "secondaryText": { "text": "Market Street, San Francisco, CA, USA" } }, "types": [ "museum", "point_of_interest", "tourist_attraction", "art_gallery", "establishment" ] } } ] }
Смещение поиска в область с использованием 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" ] } }, ... ] }
Вы также можете использовать locationBias , чтобы ограничить поиск прямоугольным окном просмотра . В следующем примере запрос ограничивается центром Сан-Франциско:
curl -X POST -d '{
"input": "Amoeba",
"locationBias": {
"rectangle": {
"low": {
"latitude": 37.7751,
"longitude": -122.4219
},
"high": {
"latitude": 37.7955,
"longitude": -122.3937
}
}
}
}' \
-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": [ "point_of_interest", "store", "establishment" ] } }, { "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": [ "point_of_interest", "store", "establishment" ] } }, { "placePrediction": { "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI", "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI", "text": { "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Hollywood Boulevard, Los Angeles, CA, USA" } }, "types": [ "point_of_interest", "store", "establishment" ] } }, /.../ ] }
Используйте включенные первичные типы
Используйте параметр 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.