На этой странице описывается клиентская библиотека, доступная с Maps JavaScript API. Если вы хотите работать с веб-сервисом Places API на своем сервере, взгляните на Node.js Client for Google Maps Services . На странице по этой ссылке также представлены Java Client, Python Client и Go Client for Google Maps Services.
Введение
Автозаполнение — это функция библиотеки Places в API JavaScript Карт. Вы можете использовать автозаполнение, чтобы дать своим приложениям поведение поиска с опережением ввода, как в поле поиска Google Карт. Служба автозаполнения может сопоставлять полные слова и подстроки, разрешая названия мест, адреса и плюс-коды . Таким образом, приложения могут отправлять запросы по мере ввода текста пользователем, чтобы предоставлять прогнозы мест на лету. Согласно определению API Places, «место» может быть учреждением, географическим местоположением или выдающейся точкой интереса.
Начиная
Перед использованием библиотеки Places в Maps JavaScript API сначала убедитесь, что Places API включен в консоли Google Cloud в том же проекте, который вы настроили для Maps JavaScript API.
Нажмите кнопку Выбрать проект , затем выберите тот же проект, который вы настроили для Maps JavaScript API, и нажмите Открыть .
В списке API на панели инструментов найдите API мест .
Если вы видите API в списке, все готово. Однако этот проект находится в статусе Legacy. Для получения дополнительной информации о стадии Legacy и о том, как перейти с Legacy на более новые сервисы, см. раздел Legacy products and features . Исключение доступно для виджетов Autocomplete и SearchBox , которые пока не доступны как продукт GA в API Places (New).
Загрузить библиотеку
Служба Places — это самостоятельная библиотека, отдельная от основного кода API JavaScript Карт. Чтобы использовать функции, содержащиеся в этой библиотеке, необходимо сначала загрузить ее с помощью параметра libraries в URL-адресе начальной загрузки API Карт:
API предлагает два типа виджетов автозаполнения, которые можно добавить с помощью классов Autocomplete и SearchBox соответственно. Кроме того, можно использовать класс AutocompleteService для программного получения результатов автозаполнения (см. Maps JavaScript API Reference: AutocompleteService class ).
Ниже приведен краткий обзор доступных классов:
Autocomplete добавляет поле ввода текста на вашу веб-страницу и отслеживает это поле на предмет ввода символов. Когда пользователь вводит текст, autocomplete возвращает прогнозы мест в виде раскрывающегося списка. Когда пользователь выбирает место из списка, информация о месте возвращается в объект autocomplete и может быть извлечена вашим приложением. Подробности см. ниже . Рисунок 1: Поле автозаполнения текста и список выбора Рисунок 2: Заполненная форма адреса
SearchBox добавляет поле ввода текста на вашу веб-страницу, во многом так же, как Autocomplete . Различия следующие:
Главное отличие заключается в результатах, которые появляются в списке выбора. SearchBox предоставляет расширенный список прогнозов, который может включать места (как определено API Places) и предлагаемые поисковые термины. Например, если пользователь вводит «пицца в новом», список выбора может включать фразу «пицца в Нью-Йорке, штат Нью-Йорк», а также названия различных точек пиццы.
SearchBox предлагает меньше возможностей, чем Autocomplete для ограничения поиска. В первом случае вы можете сместить поиск в сторону заданных LatLngBounds . Во втором случае вы можете ограничить поиск определенной страной и определенными типами мест, а также установить границы. Для получения дополнительной информации см. ниже .
Рисунок 3: SearchBox отображает поисковые запросы и прогнозы мест. Подробности смотрите ниже .
Вы можете создать объект AutocompleteService для программного извлечения прогнозов. Вызовите getPlacePredictions() для извлечения соответствующих мест или вызовите getQueryPredictions() для извлечения соответствующих мест и предлагаемых поисковых терминов. Примечание: AutocompleteService не добавляет никаких элементов управления пользовательского интерфейса. Вместо этого указанные выше методы возвращают массив объектов прогнозов. Каждый объект прогноза содержит текст прогноза, а также справочную информацию и сведения о том, как результат соответствует вводимым пользователем данным. Подробности см . ниже .
Добавить виджет автозаполнения
Виджет Autocomplete создает поле ввода текста на вашей веб-странице, предоставляет прогнозы мест в списке выбора пользовательского интерфейса и возвращает сведения о месте в ответ на запрос getPlace() . Каждая запись в списке выбора соответствует одному месту (как определено API Places).
Конструктор Autocomplete принимает два аргумента:
Элемент input HTML типа text . Это поле ввода, которое служба автозаполнения будет отслеживать и прикреплять к нему свои результаты.
Необязательный аргумент AutocompleteOptions , который может содержать следующие свойства:
Массив fields данных, которые будут включены в ответ Place Details для выбранного пользователем PlaceResult . Если свойство не задано или передано ['ALL'] , возвращаются все доступные поля и за них выставляется счет (это не рекомендуется для производственных развертываний). Список полей см. PlaceResult .
Массив types , который указывает явный тип или коллекцию типов, как указано в поддерживаемых типах . Если тип не указан, возвращаются все типы.
bounds — это объект google.maps.LatLngBounds , указывающий область, в которой следует искать места. Результаты смещены в сторону мест, содержащихся в этих границах, но не ограничиваются ими.
strictBounds — это boolean , указывающее, должен ли API возвращать только те места, которые строго находятся в пределах области, определенной заданными bounds . API не возвращает результаты за пределами этой области, даже если они соответствуют пользовательскому вводу.
componentRestrictions можно использовать для ограничения результатов определенными группами. Вы можете использовать componentRestrictions для фильтрации по 5 странам. Страны должны быть переданы как двухсимвольный код страны, совместимый с ISO 3166-1 Alpha-2. Несколько стран должны быть переданы как список кодов стран.
Примечание: Если вы получаете неожиданные результаты с кодом страны, убедитесь, что вы используете код, который включает страны, зависимые территории и особые географические области, которые вы подразумеваете. Информацию о коде можно найти в Wikipedia: List of ISO 3166 country codes или на платформе ISO Online Browsing Platform .
placeIdOnly можно использовать для указания виджету Autocomplete извлекать только идентификаторы мест. При вызове getPlace() для объекта Autocomplete , доступный PlaceResult будет иметь только place id , types и свойства name . Вы можете использовать возвращаемый идентификатор места с вызовами служб Places, Geocoding, Directions или Distance Matrix.
Ограничить прогнозы автозаполнения
По умолчанию Place Autocomplete представляет все типы мест, смещенные для прогнозов вблизи местоположения пользователя, и извлекает все доступные поля данных для выбранного пользователем места. Установите параметры Place Autocomplete, чтобы представить более релевантные прогнозы на основе вашего варианта использования.
Установить параметры при строительстве
Конструктор Autocomplete принимает параметр AutocompleteOptions для установки ограничений при создании виджета. Следующий пример устанавливает параметры bounds , componentRestrictions и types для запроса мест типа establishment , отдавая предпочтение тем, которые находятся в указанной географической области, и ограничивая прогнозы только местами в пределах Соединенных Штатов. Установка параметра fields указывает, какую информацию следует возвращать о выбранном пользователем месте.
Вызовите setOptions() , чтобы изменить значение параметра для существующего виджета.
Машинопись
constcenter={lat:50.064192,lng:-130.605469};// Create a bounding box with sides ~10km away from the center pointconstdefaultBounds={north:center.lat+0.1,south:center.lat-0.1,east:center.lng+0.1,west:center.lng-0.1,};constinput=document.getElementById("pac-input")asHTMLInputElement;constoptions={bounds:defaultBounds,componentRestrictions:{country:"us"},fields:["address_components","geometry","icon","name"],strictBounds:false,};constautocomplete=newgoogle.maps.places.Autocomplete(input,options);
constcenter={lat:50.064192,lng:-130.605469};// Create a bounding box with sides ~10km away from the center pointconstdefaultBounds={north:center.lat+0.1,south:center.lat-0.1,east:center.lng+0.1,west:center.lng-0.1,};constinput=document.getElementById("pac-input");constoptions={bounds:defaultBounds,componentRestrictions:{country:"us"},fields:["address_components","geometry","icon","name"],strictBounds:false,};constautocomplete=newgoogle.maps.places.Autocomplete(input,options);
Укажите поля данных, чтобы избежать выставления счетов за ненужные вам SKU Places Data . Включите свойство fields в AutocompleteOptions , которые передаются конструктору виджетов, как показано в предыдущем примере, или вызовите setFields() для существующего объекта Autocomplete .
Установите параметр strictBounds , чтобы ограничить результаты текущими границами, основанными на области просмотра карты или прямоугольных границах.
autocomplete.setOptions({strictBounds:true});
Ограничить прогнозы определенной страной
Используйте параметр componentRestrictions или вызовите setComponentRestrictions() , чтобы ограничить автозаполнение поиска определенным набором из пяти стран.
Используйте опцию types или вызовите setTypes() , чтобы ограничить прогнозы определенными типами мест. Это ограничение указывает тип или коллекцию типов, как указано в разделе Типы мест . Если ограничение не указано, возвращаются все типы.
Для значения параметра types или значения, переданного в setTypes() , вы можете указать одно из следующих значений:
Когда пользователь выбирает место из прогнозов, прикрепленных к текстовому полю автозаполнения, служба запускает событие place_changed . Чтобы получить сведения о месте:
Создайте обработчик событий для события place_changed и вызовите addListener() для объекта Autocomplete , чтобы добавить обработчик.
Вызовите Autocomplete.getPlace() для объекта Autocomplete , чтобы получить объект PlaceResult , который затем можно использовать для получения дополнительной информации о выбранном месте.
По умолчанию, когда пользователь выбирает место, автозаполнение возвращает все доступные поля данных для выбранного места, и вам будет выставлен счет соответственно . Используйте Autocomplete.setFields() , чтобы указать, какие поля данных о месте возвращать. Узнайте больше об объекте PlaceResult , включая список полей данных о месте, которые вы можете запросить. Чтобы не платить за данные, которые вам не нужны, обязательно используйте Autocomplete.setFields() чтобы указать только те данные о месте, которые вы будете использовать.
Свойство name содержит description из подсказок Places Autocomplete. Подробнее об description можно прочитать в документации Places Autocomplete .
Для форм адреса полезно получить адрес в структурированном формате. Чтобы вернуть структурированный адрес для выбранного места, вызовите Autocomplete.setFields() и укажите поле address_components .
В следующем примере автозаполнение используется для заполнения полей в форме адреса.
Машинопись
functionfillInAddress(){// Get the place details from the autocomplete object.constplace=autocomplete.getPlace();letaddress1="";letpostcode="";// Get each component of the address from the place details,// and then fill-in the corresponding field on the form.// place.address_components are google.maps.GeocoderAddressComponent objects// which are documented at http://goo.gle/3l5i5Mrfor(constcomponentofplace.address_componentsasgoogle.maps.GeocoderAddressComponent[]){// @ts-ignore remove once typings fixedconstcomponentType=component.types[0];switch(componentType){case"street_number":{address1=`${component.long_name}${address1}`;break;}case"route":{address1+=component.short_name;break;}case"postal_code":{postcode=`${component.long_name}${postcode}`;break;}case"postal_code_suffix":{postcode=`${postcode}-${component.long_name}`;break;}case"locality":(document.querySelector("#locality")asHTMLInputElement).value=component.long_name;break;case"administrative_area_level_1":{(document.querySelector("#state")asHTMLInputElement).value=component.short_name;break;}case"country":(document.querySelector("#country")asHTMLInputElement).value=component.long_name;break;}}address1Field.value=address1;postalField.value=postcode;// After filling the form with address components from the Autocomplete// prediction, set cursor focus on the second address line to encourage// entry of subpremise information such as apartment, unit, or floor number.address2Field.focus();}
functionfillInAddress(){// Get the place details from the autocomplete object.constplace=autocomplete.getPlace();letaddress1="";letpostcode="";// Get each component of the address from the place details,// and then fill-in the corresponding field on the form.// place.address_components are google.maps.GeocoderAddressComponent objects// which are documented at http://goo.gle/3l5i5Mrfor(constcomponentofplace.address_components){// @ts-ignore remove once typings fixedconstcomponentType=component.types[0];switch(componentType){case"street_number":{address1=`${component.long_name}${address1}`;break;}case"route":{address1+=component.short_name;break;}case"postal_code":{postcode=`${component.long_name}${postcode}`;break;}case"postal_code_suffix":{postcode=`${postcode}-${component.long_name}`;break;}case"locality":document.querySelector("#locality").value=component.long_name;break;case"administrative_area_level_1":{document.querySelector("#state").value=component.short_name;break;}case"country":document.querySelector("#country").value=component.long_name;break;}}address1Field.value=address1;postalField.value=postcode;// After filling the form with address components from the Autocomplete// prediction, set cursor focus on the second address line to encourage// entry of subpremise information such as apartment, unit, or floor number.address2Field.focus();}window.initAutocomplete=initAutocomplete;
По умолчанию текстовое поле, созданное службой автозаполнения, содержит стандартный текст-заполнитель. Чтобы изменить текст, установите атрибут- placeholder на элементе input :
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
Примечание: текст заполнителя по умолчанию локализуется автоматически. Если вы указываете собственное значение заполнителя, вы должны обработать локализацию этого значения в своем приложении. Для получения информации о том, как Google Maps JavaScript API выбирает используемый язык, прочтите документацию по локализации .
SearchBox позволяет пользователям выполнять текстовый географический поиск, например, «пицца в Нью-Йорке» или «обувные магазины рядом с улицей Робсон». Вы можете прикрепить SearchBox к текстовому полю, и по мере ввода текста служба будет возвращать прогнозы в виде раскрывающегося списка выбора.
SearchBox предоставляет расширенный список прогнозов, который может включать места (как определено API Places) и предлагаемые поисковые термины. Например, если пользователь вводит «пицца в новом», список выбора может включать фразу «пицца в Нью-Йорке, штат Нью-Йорк», а также названия различных точек пиццы. Когда пользователь выбирает место из списка, информация об этом месте возвращается объекту SearchBox и может быть извлечена вашим приложением.
Конструктор SearchBox принимает два аргумента:
Элемент input HTML типа text . Это поле ввода, которое служба SearchBox будет отслеживать и прикреплять к нему свои результаты.
Аргумент options , который может содержать свойство bounds : bounds — это объект google.maps.LatLngBounds , указывающий область, в которой следует искать места. Результаты смещены в сторону мест, содержащихся в этих границах, но не ограничиваются ими.
Следующий код использует параметр bounds для смещения результатов в сторону мест в пределах определенной географической области, указанной с помощью координат широты/долготы.
Чтобы изменить область поиска для существующего SearchBox , вызовите setBounds() для объекта SearchBox и передайте соответствующий объект LatLngBounds .
Когда пользователь выбирает элемент из прогнозов, прикрепленных к полю поиска, служба запускает событие places_changed . Вы можете вызвать getPlaces() для объекта SearchBox , чтобы получить массив, содержащий несколько прогнозов, каждый из которых является объектом PlaceResult .
// Listen for the event fired when the user selects a prediction and retrieve// more details for that place.searchBox.addListener("places_changed",()=>{constplaces=searchBox.getPlaces();if(places.length==0){return;}// Clear out the old markers.markers.forEach((marker)=>{marker.setMap(null);});markers=[];// For each place, get the icon, name and location.constbounds=newgoogle.maps.LatLngBounds();places.forEach((place)=>{if(!place.geometry||!place.geometry.location){console.log("Returned place contains no geometry");return;}consticon={url:place.iconasstring,size:newgoogle.maps.Size(71,71),origin:newgoogle.maps.Point(0,0),anchor:newgoogle.maps.Point(17,34),scaledSize:newgoogle.maps.Size(25,25),};// Create a marker for each place.markers.push(newgoogle.maps.Marker({map,icon,title:place.name,position:place.geometry.location,}));if(place.geometry.viewport){// Only geocodes have viewport.bounds.union(place.geometry.viewport);}else{bounds.extend(place.geometry.location);}});map.fitBounds(bounds);});
// Listen for the event fired when the user selects a prediction and retrieve// more details for that place.searchBox.addListener("places_changed",()=>{constplaces=searchBox.getPlaces();if(places.length==0){return;}// Clear out the old markers.markers.forEach((marker)=>{marker.setMap(null);});markers=[];// For each place, get the icon, name and location.constbounds=newgoogle.maps.LatLngBounds();places.forEach((place)=>{if(!place.geometry||!place.geometry.location){console.log("Returned place contains no geometry");return;}consticon={url:place.icon,size:newgoogle.maps.Size(71,71),origin:newgoogle.maps.Point(0,0),anchor:newgoogle.maps.Point(17,34),scaledSize:newgoogle.maps.Size(25,25),};// Create a marker for each place.markers.push(newgoogle.maps.Marker({map,icon,title:place.name,position:place.geometry.location,}),);if(place.geometry.viewport){// Only geocodes have viewport.bounds.union(place.geometry.viewport);}else{bounds.extend(place.geometry.location);}});map.fitBounds(bounds);});
Программное получение прогнозов Place Autocomplete Service
Для программного получения прогнозов используйте класс AutocompleteService . AutocompleteService не добавляет никаких элементов управления пользовательского интерфейса. Вместо этого он возвращает массив объектов прогнозов, каждый из которых содержит текст прогноза, справочную информацию и сведения о том, как результат соответствует вводу пользователя. Это полезно, если вам нужно больше контроля над пользовательским интерфейсом, чем предлагают Autocomplete и SearchBox описанные выше.
AutocompleteService предоставляет следующие методы:
getPlacePredictions() возвращает прогнозы мест. Примечание: «место» может быть учреждением, географическим местоположением или выдающейся точкой интереса, как определено API Places.
getQueryPredictions() возвращает расширенный список прогнозов, который может включать места (как определено API Places) и предлагаемые поисковые термины. Например, если пользователь вводит «пицца в новом», список выбора может включать фразу «пицца в Нью-Йорке, штат Нью-Йорк», а также названия различных точек пиццы.
distance_meters — расстояние в метрах от указанного AutocompletionRequest.origin места.
matched_substrings содержит набор подстрок в описании, которые соответствуют элементам во вводе пользователя. Это полезно для выделения этих подстрок в вашем приложении. Во многих случаях запрос будет отображаться как подстрока поля описания.
length — длина подстроки.
offset — это смещение символа, измеренное от начала строки описания, в котором появляется совпадающая подстрока.
terms — это массив, содержащий элементы запроса. Для места каждый элемент обычно составляет часть адреса.
offset — это смещение символа, измеренное от начала строки описания, в котором появляется совпадающая подстрока.
value — это соответствующий термин.
В приведенном ниже примере выполняется запрос прогнозирования для фразы «пицца рядом» и отображается результат в виде списка.
Машинопись
// This example retrieves autocomplete predictions programmatically from the// autocomplete service, and displays them as an HTML list.// This example requires the Places library. Include the libraries=places// parameter when you first load the API. For example:// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">functioninitService():void{constdisplaySuggestions=function(predictions:google.maps.places.QueryAutocompletePrediction[]|null,status:google.maps.places.PlacesServiceStatus){if(status!=google.maps.places.PlacesServiceStatus.OK||!predictions){alert(status);return;}predictions.forEach((prediction)=>{constli=document.createElement("li");li.appendChild(document.createTextNode(prediction.description));(document.getElementById("results")asHTMLUListElement).appendChild(li);});};constservice=newgoogle.maps.places.AutocompleteService();service.getQueryPredictions({input:"pizza near Syd"},displaySuggestions);}declareglobal{interfaceWindow{initService:()=>void;}}window.initService=initService;
// This example retrieves autocomplete predictions programmatically from the// autocomplete service, and displays them as an HTML list.// This example requires the Places library. Include the libraries=places// parameter when you first load the API. For example:// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">functioninitService(){constdisplaySuggestions=function(predictions,status){if(status!=google.maps.places.PlacesServiceStatus.OK||!predictions){alert(status);return;}predictions.forEach((prediction)=>{constli=document.createElement("li");li.appendChild(document.createTextNode(prediction.description));document.getElementById("results").appendChild(li);});};constservice=newgoogle.maps.places.AutocompleteService();service.getQueryPredictions({input:"pizza near Syd"},displaySuggestions);}window.initService=initService;
<html>
<head>
<title>Retrieving Autocomplete Predictions</title>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
</head>
<body>
<p>Query suggestions for 'pizza near Syd':</p>
<ul id="results"></ul>
<!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
<img
class="powered-by-google"
src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
alt="Powered by Google"
/>
<!--
The `defer` attribute causes the script to execute after the full HTML
document has been parsed. For non-blocking uses, avoiding race conditions,
and consistent behavior across browsers, consider loading using Promises. See
https://developers.google.com/maps/documentation/javascript/load-maps-js-api
for more information.
-->
<script
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
defer
></script>
</body>
</html>
AutocompleteService.getPlacePredictions() может использовать токены сеанса (если реализован) для группировки запросов автозаполнения для выставления счетов. Токены сеанса группируют фазы запроса и выбора поиска автозаполнения пользователя в отдельный сеанс для выставления счетов. Сеанс начинается, когда пользователь начинает вводить запрос, и заканчивается, когда он выбирает место. Каждый сеанс может иметь несколько запросов, за которыми следует один выбор места. После завершения сеанса токен больше недействителен. Ваше приложение должно генерировать новый токен для каждого сеанса. Мы рекомендуем использовать токены сеанса для всех сеансов автозаполнения. Если параметр sessionToken опущен или если вы повторно используете токен сеанса, сеанс тарифицируется так, как если бы токен сеанса не был предоставлен (каждый запрос тарифицируется отдельно).
Вы можете использовать тот же токен сеанса для создания одного запроса Place Details для места, которое является результатом вызова AutocompleteService.getPlacePredictions() . В этом случае запрос автозаполнения объединяется с запросом Place Details, и вызов тарифицируется как обычный запрос Place Details. Запрос автозаполнения бесплатен.
Обязательно передайте уникальный токен сеанса для каждого нового сеанса. Использование одного и того же токена для нескольких сеансов Autocomplete сделает эти сеансы Autocomplete недействительными, и все запросы Autocomplete в недействительных сеансах будут оплачиваться индивидуально с использованием Autocomplete Per Request SKU . Подробнее о токенах сеанса .
В следующем примере показано создание токена сеанса и его последующая передача в AutocompleteService (функция displaySuggestions() опущена для краткости):
// Create a new session token.varsessionToken=newgoogle.maps.places.AutocompleteSessionToken();// Pass the token to the autocomplete service.varautocompleteService=newgoogle.maps.places.AutocompleteService();autocompleteService.getPlacePredictions({input:'pizza near Syd',sessionToken:sessionToken},displaySuggestions);
Обязательно передайте уникальный токен сеанса для каждого нового сеанса. Использование одного и того же токена для более чем одного сеанса приведет к тому, что каждый запрос будет выставлен по отдельности.
Стилизация виджетов «Автозаполнение» и «SearchBox»
По умолчанию элементы пользовательского интерфейса, предоставляемые Autocomplete и SearchBox , стилизованы для включения в карту Google. Вы можете настроить стили в соответствии с вашим сайтом. Доступны следующие классы CSS. Все перечисленные ниже классы применяются как к виджетам Autocomplete , так и к виджетам SearchBox .
CSS-классы для виджетов Autocomplete и SearchBox
CSS-класс
Описание
pac-container
Визуальный элемент, содержащий список прогнозов, возвращаемых службой Place Autocomplete. Этот список отображается в виде раскрывающегося списка под виджетом Autocomplete или SearchBox .
pac-icon
Значок, отображаемый слева от каждого элемента в списке прогнозов.
pac-item
Элемент в списке подсказок, предоставленных виджетом Autocomplete или SearchBox .
pac-item:hover
Элемент, на который пользователь наводит указатель мыши.
pac-item-selected
Элемент, когда пользователь выбирает его с помощью клавиатуры. Примечание: выбранные элементы будут членами этого класса и класса pac-item .
pac-item-query
Диапазон внутри pac-item , который является основной частью прогноза. Для географических местоположений он содержит название места, например «Сидней», или название улицы и номер дома, например «10 King Street». Для текстовых поисков, таких как «пицца в Нью-Йорке», он содержит полный текст запроса. По умолчанию pac-item-query окрашен в черный цвет. Если в pac-item есть какой-либо дополнительный текст, он находится за пределами pac-item-query и наследует его стиль от pac-item . По умолчанию он окрашен в серый цвет. Дополнительный текст обычно является адресом.
pac-matched
Часть возвращаемого прогноза, которая соответствует вводу пользователя. По умолчанию этот совпавший текст выделен жирным шрифтом. Обратите внимание, что совпавший текст может находиться где угодно в pac-item . Он не обязательно является частью pac-item-query , и он может находиться частично в pac-item-query , а частично в оставшемся тексте в pac-item .
Оптимизация автозаполнения (устаревшая версия)
В этом разделе описываются рекомендации, которые помогут вам максимально эффективно использовать услугу Place Autocomplete (Legacy).
С самого начала разработайте понимание основных полей данных Place Autocomplete (Legacy).
Поля смещения местоположения и ограничения местоположения являются необязательными, но могут оказать существенное влияние на производительность автозаполнения.
Используйте обработку ошибок, чтобы гарантировать, что ваше приложение будет корректно работать, если API вернет ошибку.
Убедитесь, что ваше приложение обрабатывает ситуацию, когда нет выбора, и предлагает пользователям возможность продолжить.
Лучшие практики оптимизации затрат
Базовая оптимизация затрат
Чтобы оптимизировать стоимость использования сервиса автозаполнения мест (устаревшая версия), используйте маски полей в виджетах «Сведения о месте (устаревшая версия)» и «Автозаполнение мест (устаревшая версия)», чтобы возвращать только необходимые вам поля данных о местах .
Расширенная оптимизация затрат
Рассмотрите программную реализацию Place Autocomplete (Legacy) для доступа к ценам Per Request и запроса результатов Geocoding API о выбранном месте вместо Place Details (Legacy). Цены Per Request в сочетании с Geocoding API более рентабельны, чем цены Per Session (на основе сеанса), если выполняются оба следующих условия:
Если вам нужны только широта/долгота или адрес выбранного пользователем места, API геокодирования предоставит эту информацию менее чем за один вызов Place Details (Legacy).
Если пользователи выбирают прогноз автозаполнения в среднем в течение четырех запросов прогнозов Place Autocomplete (Legacy) или менее, цена за запрос может быть более рентабельной, чем цена за сеанс.
Для получения помощи в выборе реализации Place Autocomplete (Legacy), которая соответствует вашим потребностям, выберите вкладку, соответствующую вашему ответу на следующий вопрос.
Требуется ли для вашего приложения какая-либо информация, помимо адреса и широты/долготы выбранного прогноза?
В следующих рекомендациях описываются способы оптимизации производительности Place Autocomplete (Legacy):
Добавьте ограничения по странам, смещение местоположения и (для программных реализаций) языковые предпочтения в реализацию Place Autocomplete (Legacy). Языковые предпочтения не нужны для виджетов, поскольку они выбирают языковые предпочтения из браузера или мобильного устройства пользователя.
Если функция автозаполнения мест (устаревшая) сопровождается картой, вы можете смещать местоположение в зависимости от области просмотра карты.
В ситуациях, когда пользователь не выбирает ни одно из предсказаний Place Autocomplete (Legacy), как правило, потому, что ни одно из этих предсказаний не является желаемым адресом результата, вы можете повторно использовать исходный пользовательский ввод, чтобы попытаться получить более релевантные результаты:
Если вы ожидаете, что пользователь введет только адресную информацию, повторно используйте исходный пользовательский ввод в вызове API геокодирования .
Если вы ожидаете, что пользователь введет запросы для определенного места по имени или адресу, используйте запрос Find Place (Legacy) . Если результаты ожидаются только в конкретной области, используйте смещение местоположения .
Другие сценарии, когда лучше вернуться к геокодированию API, включают:
Пользователи вводят адреса подпресс -адресов, такие как адреса для конкретных единиц или квартир в здании. Например, чешский адрес «Stroupežnického 3191/17, Praha» дает частичный прогноз на месте автозаполнения (Legacy).
Пользователи вводят адреса с префиксами сегмента дорожного движения, такими как «23-30 29th St, Queens» в Нью-Йорке или «47-380 Kamehameha Hwy, Kaneohe» на острове Кауаи на Гавайях.
На этой странице описывается библиотека на стороне клиента, доступную с API Maps JavaScript. Если вы хотите поработать с веб -службой API API на своем сервере, посмотрите на клиент Node.js для служб Google Maps . Страница по этой ссылке также представляет Java Client, Python Client и Go Client для Google Maps Services.
Введение
AutoComplete - это особенность библиотеки мест в API Maps JavaScript. Вы можете использовать автозаполнение, чтобы дать вашим приложениям поведение типового поиска в поле поиска Google Maps. Служба автозаполнения может соответствовать полным словам и подстрокам, разрешению имен мест, адресов и плюс кодов . Поэтому приложения могут отправлять запросы в качестве типов пользователей, чтобы предоставить предсказания на лету. Как определено местами API, «место» может быть учреждением, географическим положением или выдающимся интересом.
Начиная
Перед использованием библиотеки «Места» в API Maps JavaScript сначала убедитесь, что API Place включен в облачной консоли Google, в том же проекте, который вы настроили для API Maps JavaScript.
Нажмите кнопку «Выберите проект» , затем выберите тот же проект, который вы настроили для API Maps JavaScript, и нажмите «Открыть» .
Из списка API на приборной панели ищите места API .
Если вы видите API в списке, все готово. Тем не менее, этот проект находится в устаревшем статусе. Для получения дополнительной информации о стадии наследия и о том, как перейти от наследия на новые услуги, см. Унаследованные продукты и функции . Исключение доступно для виджетов автозаполнения и поисковой коробки , которые еще не доступны в качестве продукта GA на API Places (новый).
Загрузите библиотеку
Сервис Places-это автономная библиотека, отдельная от основных карт JavaScript API-кода. Чтобы использовать функции, содержащиеся в этой библиотеке, необходимо сначала загрузить их, используя параметр libraries в URL -адреса Bootstrap Maps API:
Смотрите обзор библиотек для получения дополнительной информации.
Резюме классов
API предлагает два типа автоматических виджетов, которые вы можете добавить, используя классы Autocomplete и SearchBox соответственно. Кроме того, вы можете использовать класс AutocompleteService для программного получения результатов автозаполнения (см. Справочник по API API MAPS: класс AutoCompleteService ).
Ниже приводится сводка доступных классов:
Autocomplete добавляет поле текстового ввода на вашу веб -страницу и контролирует это поле для записей символов. Когда пользователь входит в текст, автозаполнение возвращает предсказания в виде раскрывающегося списка. Когда пользователь выбирает место из списка, информация о месте возвращается в объект автозаполнения и может быть извлечена по вашему приложению. Смотрите подробности ниже . Рисунок 1: Поле текстового поля автозаполнения и список выбора Рисунок 2: Заполненная форма адреса
SearchBox добавляет поле текста в вашу веб -страницу, почти так же, как и Autocomplete . Различия следующие:
Основное различие заключается в результатах, которые появляются в списке выбора. SearchBox предоставляет расширенный список прогнозов, который может включать места (как определено местами API), а также предлагаемые поисковые термины. Например, если пользователь входит в «Пиццу в новой», список выбора может включать фразу «Пицца в Нью -Йорке, штат Нью -Йорк», а также имена различных торговых точек пиццы.
SearchBox предлагает меньше параметров, чем Autocomplete для ограничения поиска. В первом вы можете склонить поиск в направлении данных LatLngBounds . В последнем вы можете ограничить поиск определенной страной и конкретными типами мест, а также устанавливать границы. Для получения дополнительной информации см. Ниже .
Рисунок 3: Поисковая коробка представляет термины поиска и размещает прогнозы. Смотрите подробности ниже .
Вы можете создать объект AutocompleteService для программного извлечения прогнозов. Вызовите getPlacePredictions() , чтобы извлечь места для сопоставления, или позвоните getQueryPredictions() чтобы получить подходящие места, а также предлагаемые поисковые термины. Примечание: AutocompleteService не добавляет никаких элементов управления пользовательским интерфейсом. Вместо этого приведенные выше методы возвращают массив объектов прогнозирования. Каждый объект прогнозирования содержит текст прогнозирования, а также справочную информацию и подробную информацию о том, как результат соответствует пользовательскому вводу. Смотрите подробности ниже .
Добавить виджет автозаполнения
Виджет Autocomplete создает поле текстового ввода на вашей веб -странице, поставляет прогнозы мест в списке выбора пользовательского интерфейса и возвращает детали размещения в ответ на запрос getPlace() . Каждая запись в списке выбора соответствует одному месту (как определено местами API).
Конструктор Autocomplete принимает два аргумента:
HTML input элемент text типа. Это поле ввода, в котором служба автозаполнения будет отслеживать и прикрепить его результаты.
Необязательный аргумент AutocompleteOptions , который может содержать следующие свойства:
Массив fields данных, которые должны быть включены в ответ сведения PlaceResultPlace Details для выбранного пользователя. Если недвижимость не установлена или если ['ALL'] передается, все доступные поля возвращаются и выставлены за счет (это не рекомендуется для развертывания производства). Список полей см. PlaceResult .
Массив types , которые определяют явный тип или коллекцию типов, как указано в поддерживаемых типах . Если тип не указан, все типы возвращаются.
bounds - это объект google.maps.LatLngBounds , указывающий область, в которой можно найти места. Результаты смещены в сторону, но не ограничены местами, содержащимися в этих границах.
strictBounds - это boolean указывающее, должен ли API возвращать только те места, которые строго находятся в области, определяемой данными bounds . API не возвращает результаты за пределами этого региона, даже если они соответствуют пользовательскому вводу.
componentRestrictions могут использоваться для ограничения результатов конкретными группами. Вы можете использовать componentRestrictions для фильтрации до 5 стран. Страны должны быть приняты как двуххамерный, ISO 3166-1 Alpha-2, совместимый с кодом страны. Несколько стран должны быть приняты в виде списка кодов страны.
Примечание. Если вы получаете неожиданные результаты с кодом страны, убедитесь, что вы используете код, который включает в себя страны, зависимые территории и особые области географического интереса, которые вы намереваете. Вы можете найти информацию о коде в Wikipedia: список кодов страны ISO 3166 или онлайн -платформы онлайн -просмотра ISO .
placeIdOnly может использоваться для обучения виджета Autocomplete , чтобы получить только идентификаторы размещения. При вызове getPlace() на объекте Autocomplete , доступный PlaceResult будет иметь только place id , types и свойства name . Вы можете использовать возвращенный идентификатор места с вызовами в места, геокодирование, направления или службы матрицы расстояний.
Ограничьте предсказания автозаполнения
По умолчанию Place AutoComplete представляет все типы мест, предвзятые для прогнозов вблизи местоположения пользователя, и приносит все доступные поля данных для выбранного места пользователя. Установите размещение параметров автозаполнения, чтобы представить более релевантные прогнозы на основе вашего варианта использования.
Установить варианты на строительстве
Конструктор Autocomplete принимает параметр AutocompleteOptions для установки ограничений при создании виджетов. В следующем примере устанавливаются bounds , componentRestrictions и types вариантов для запроса мест типа establishment , в пользу тех, кто находится в указанной географической области и ограничивая прогнозы только местами в Соединенных Штатах. Установка опции fields Указывает, какую информацию вернуть в выбранное место пользователя.
Вызовы setOptions() Чтобы изменить значение опции для существующего виджета.
Машинопись
constcenter={lat:50.064192,lng:-130.605469};// Create a bounding box with sides ~10km away from the center pointconstdefaultBounds={north:center.lat+0.1,south:center.lat-0.1,east:center.lng+0.1,west:center.lng-0.1,};constinput=document.getElementById("pac-input")asHTMLInputElement;constoptions={bounds:defaultBounds,componentRestrictions:{country:"us"},fields:["address_components","geometry","icon","name"],strictBounds:false,};constautocomplete=newgoogle.maps.places.Autocomplete(input,options);
constcenter={lat:50.064192,lng:-130.605469};// Create a bounding box with sides ~10km away from the center pointconstdefaultBounds={north:center.lat+0.1,south:center.lat-0.1,east:center.lng+0.1,west:center.lng-0.1,};constinput=document.getElementById("pac-input");constoptions={bounds:defaultBounds,componentRestrictions:{country:"us"},fields:["address_components","geometry","icon","name"],strictBounds:false,};constautocomplete=newgoogle.maps.places.Autocomplete(input,options);
Укажите поля данных, чтобы избежать выставления счетов за данные, которые вам не нужны. Включите свойство fields в AutocompleteOptions , которые передаются в конструктор виджетов, как показано в предыдущем примере, или Call setFields() на существующем объекте Autocomplete .
Установите опцию strictBounds , чтобы ограничить результаты текущими границами, будь то на основе просмотра карты или прямоугольных границ.
autocomplete.setOptions({strictBounds:true});
Ограничить прогнозы в конкретной стране
Используйте опцию componentRestrictions или вызовы setComponentRestrictions() чтобы ограничить поиск автозаполнения определенным набором из пяти стран.
Используйте опцию types или Call setTypes() чтобы ограничить прогнозы определенным типам мест. Это ограничение указывает тип или коллекцию типа, как указано на типах места . Если не указано ограничение, все типы возвращаются.
Для значения опции types или значения, передаваемого setTypes() , вы можете указать либо:
Когда пользователь выбирает место из прогнозов, прикрепленных к автозаполненному текстовому полю, служба запускает событие place_changed . Чтобы получить детали места:
Создайте обработчик событий для события place_changed и вызовите addListener() на объекте Autocomplete , чтобы добавить обработчик.
Вызовите Autocomplete.getPlace() на объекте Autocomplete , чтобы получить объект PlaceResult , который затем вы можете использовать, чтобы получить больше информации о выбранном месте.
По умолчанию, когда пользователь выбирает место, автозаполнение возвращает все доступные поля данных для выбранного места, и вам будет выставлено соответствующее счет . Используйте Autocomplete.setFields() чтобы указать, какие поля данных поместите поля данных для возврата. Узнайте больше об объекте PlaceResult , включая список полей данных места, которые вы можете запросить. Чтобы не платить за данные, которые вам не нужны, обязательно используйте Autocomplete.setFields() чтобы указать только данные места, которые вы будете использовать.
Свойство name содержит description из Places AutoCoplete Prodictions. Вы можете прочитать больше об description в The Plays Autocomplete Documentation .
Для форм адреса полезно получить адрес в структурированном формате. Чтобы вернуть структурированный адрес для выбранного места, вызовите Autocomplete.setFields() и укажите поле address_components .
В следующем примере используется автозаполнение для заполнения полей в форме адреса.
Машинопись
functionfillInAddress(){// Get the place details from the autocomplete object.constplace=autocomplete.getPlace();letaddress1="";letpostcode="";// Get each component of the address from the place details,// and then fill-in the corresponding field on the form.// place.address_components are google.maps.GeocoderAddressComponent objects// which are documented at http://goo.gle/3l5i5Mrfor(constcomponentofplace.address_componentsasgoogle.maps.GeocoderAddressComponent[]){// @ts-ignore remove once typings fixedconstcomponentType=component.types[0];switch(componentType){case"street_number":{address1=`${component.long_name}${address1}`;break;}case"route":{address1+=component.short_name;break;}case"postal_code":{postcode=`${component.long_name}${postcode}`;break;}case"postal_code_suffix":{postcode=`${postcode}-${component.long_name}`;break;}case"locality":(document.querySelector("#locality")asHTMLInputElement).value=component.long_name;break;case"administrative_area_level_1":{(document.querySelector("#state")asHTMLInputElement).value=component.short_name;break;}case"country":(document.querySelector("#country")asHTMLInputElement).value=component.long_name;break;}}address1Field.value=address1;postalField.value=postcode;// After filling the form with address components from the Autocomplete// prediction, set cursor focus on the second address line to encourage// entry of subpremise information such as apartment, unit, or floor number.address2Field.focus();}
functionfillInAddress(){// Get the place details from the autocomplete object.constplace=autocomplete.getPlace();letaddress1="";letpostcode="";// Get each component of the address from the place details,// and then fill-in the corresponding field on the form.// place.address_components are google.maps.GeocoderAddressComponent objects// which are documented at http://goo.gle/3l5i5Mrfor(constcomponentofplace.address_components){// @ts-ignore remove once typings fixedconstcomponentType=component.types[0];switch(componentType){case"street_number":{address1=`${component.long_name}${address1}`;break;}case"route":{address1+=component.short_name;break;}case"postal_code":{postcode=`${component.long_name}${postcode}`;break;}case"postal_code_suffix":{postcode=`${postcode}-${component.long_name}`;break;}case"locality":document.querySelector("#locality").value=component.long_name;break;case"administrative_area_level_1":{document.querySelector("#state").value=component.short_name;break;}case"country":document.querySelector("#country").value=component.long_name;break;}}address1Field.value=address1;postalField.value=postcode;// After filling the form with address components from the Autocomplete// prediction, set cursor focus on the second address line to encourage// entry of subpremise information such as apartment, unit, or floor number.address2Field.focus();}window.initAutocomplete=initAutocomplete;
По умолчанию текстовое поле, созданное службой автозаполнения, содержит стандартный текст заполнителей. Чтобы изменить текст, установите атрибут placeholder на input элементе:
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
Примечание. Текст заполнителя по умолчанию локализуется автоматически. Если вы указываете собственное значение заполнителя, вы должны обрабатывать локализацию этого значения в вашем приложении. Для получения информации о том, как Google Maps JavaScript API выбирает язык для использования, прочитайте документацию по локализации .
SearchBox позволяет пользователям выполнять текстовый географический поиск, такой как «Pizza в Нью-Йорке» или «обувные магазины возле улицы Робсон». Вы можете подключить SearchBox к текстовому поле, и, как введен текст, служба вернет прогнозы в форме раскрывающегося списка выбора.
SearchBox предоставляет расширенный список прогнозов, который может включать места (как определено местами API), а также предлагаемые поисковые термины. Например, если пользователь входит в «Пиццу в новой», список выбора может включать фразу «Пицца в Нью -Йорке, штат Нью -Йорк», а также имена различных торговых точек пиццы. Когда пользователь выбирает место из списка, информация об этом месте возвращается в объект Searchbox и может быть извлечена в ваше приложение.
Конструктор SearchBox принимает два аргумента:
HTML input элемент text типа. Это поле ввода, в которое служба SearchBox будет отслеживать и прикрепить свои результаты.
Аргумент options , который может содержать свойство bounds : bounds - это объект google.maps.LatLngBounds , указывающий область для поиска мест. Результаты смещены в сторону, но не ограничены местами, содержащимися в этих границах.
Следующий код использует параметр границ для смещения результатов в направлении мест в определенной географической области, указанный с использованием координат Laitude/Longitude.
Чтобы изменить область поиска для существующего SearchBox , вызовите setBounds() на объекте SearchBox и передайте соответствующий объект LatLngBounds .
Когда пользователь выбирает элемент из предсказаний, прикрепленных к поле поиска, служба запускает событие places_changed . Вы можете вызвать getPlaces() в объекте SearchBox , чтобы получить массив, содержащий несколько прогнозов, каждый из которых является объектом PlaceResult .
Для получения дополнительной информации о объекте PlaceResult см. В документации о подробных результатах места .
Машинопись
// Listen for the event fired when the user selects a prediction and retrieve// more details for that place.searchBox.addListener("places_changed",()=>{constplaces=searchBox.getPlaces();if(places.length==0){return;}// Clear out the old markers.markers.forEach((marker)=>{marker.setMap(null);});markers=[];// For each place, get the icon, name and location.constbounds=newgoogle.maps.LatLngBounds();places.forEach((place)=>{if(!place.geometry||!place.geometry.location){console.log("Returned place contains no geometry");return;}consticon={url:place.iconasstring,size:newgoogle.maps.Size(71,71),origin:newgoogle.maps.Point(0,0),anchor:newgoogle.maps.Point(17,34),scaledSize:newgoogle.maps.Size(25,25),};// Create a marker for each place.markers.push(newgoogle.maps.Marker({map,icon,title:place.name,position:place.geometry.location,}));if(place.geometry.viewport){// Only geocodes have viewport.bounds.union(place.geometry.viewport);}else{bounds.extend(place.geometry.location);}});map.fitBounds(bounds);});
// Listen for the event fired when the user selects a prediction and retrieve// more details for that place.searchBox.addListener("places_changed",()=>{constplaces=searchBox.getPlaces();if(places.length==0){return;}// Clear out the old markers.markers.forEach((marker)=>{marker.setMap(null);});markers=[];// For each place, get the icon, name and location.constbounds=newgoogle.maps.LatLngBounds();places.forEach((place)=>{if(!place.geometry||!place.geometry.location){console.log("Returned place contains no geometry");return;}consticon={url:place.icon,size:newgoogle.maps.Size(71,71),origin:newgoogle.maps.Point(0,0),anchor:newgoogle.maps.Point(17,34),scaledSize:newgoogle.maps.Size(25,25),};// Create a marker for each place.markers.push(newgoogle.maps.Marker({map,icon,title:place.name,position:place.geometry.location,}),);if(place.geometry.viewport){// Only geocodes have viewport.bounds.union(place.geometry.viewport);}else{bounds.extend(place.geometry.location);}});map.fitBounds(bounds);});
Программно извлечение предсказаний службы автозаполнения мест
Чтобы программно получить прогнозы, используйте класс AutocompleteService . AutocompleteService не добавляет никаких элементов управления пользовательским интерфейсом. Вместо этого он возвращает массив объектов прогнозирования, каждый из которых содержит текст прогнозирования, справочной информации и детали того, как результат соответствует вводу пользователя. Это полезно, если вы хотите больше управлять пользовательским интерфейсом, чем предлагается Autocomplete и SearchBox описанным выше.
AutocompleteService раскрывает следующие методы:
getPlacePredictions() возвращает предсказания. Примечание. «Место» может быть учреждением, географическим положением или выдающейся интересом, как определено местами API.
getQueryPredictions() возвращает расширенный список прогнозов, который может включать места (как определено The Place API), а также предлагаемые поисковые термины. Например, если пользователь входит в «Пиццу в новой», список выбора может включать фразу «Пицца в Нью -Йорке, штат Нью -Йорк», а также имена различных торговых точек пиццы.
distance_meters - это расстояние в метрах места от указанного AutocompletionRequest.origin .
matched_substrings содержит набор подстроков в описании, которые соответствуют элементам при вводе пользователя. Это полезно для выделения этих подстроков в вашем приложении. Во многих случаях запрос появится как подстроение поля описания.
length - это длина подстроения.
offset - это смещение символов, измеренное с начала строки описания, при которой появляется соответствующая подстроение.
place_id - это текстовый идентификатор, который уникально идентифицирует место. Чтобы получить информацию о месте, передайте этот идентификатор в поле placeId о запросе деталей места . Узнайте больше о том, как ссылаться на место с идентификатором места .
terms - это массив, содержащий элементы запроса. Для места каждый элемент обычно составляет часть адреса.
offset - это смещение символов, измеренное с начала строки описания, при которой появляется соответствующая подстроение.
value - это соответствующий термин.
Пример ниже выполняет запрос на прогнозирование запросов для фразы «Пицца рядом» и отображает результат в списке.
Машинопись
// This example retrieves autocomplete predictions programmatically from the// autocomplete service, and displays them as an HTML list.// This example requires the Places library. Include the libraries=places// parameter when you first load the API. For example:// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">functioninitService():void{constdisplaySuggestions=function(predictions:google.maps.places.QueryAutocompletePrediction[]|null,status:google.maps.places.PlacesServiceStatus){if(status!=google.maps.places.PlacesServiceStatus.OK||!predictions){alert(status);return;}predictions.forEach((prediction)=>{constli=document.createElement("li");li.appendChild(document.createTextNode(prediction.description));(document.getElementById("results")asHTMLUListElement).appendChild(li);});};constservice=newgoogle.maps.places.AutocompleteService();service.getQueryPredictions({input:"pizza near Syd"},displaySuggestions);}declareglobal{interfaceWindow{initService:()=>void;}}window.initService=initService;
// This example retrieves autocomplete predictions programmatically from the// autocomplete service, and displays them as an HTML list.// This example requires the Places library. Include the libraries=places// parameter when you first load the API. For example:// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">functioninitService(){constdisplaySuggestions=function(predictions,status){if(status!=google.maps.places.PlacesServiceStatus.OK||!predictions){alert(status);return;}predictions.forEach((prediction)=>{constli=document.createElement("li");li.appendChild(document.createTextNode(prediction.description));document.getElementById("results").appendChild(li);});};constservice=newgoogle.maps.places.AutocompleteService();service.getQueryPredictions({input:"pizza near Syd"},displaySuggestions);}window.initService=initService;
<html>
<head>
<title>Retrieving Autocomplete Predictions</title>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
</head>
<body>
<p>Query suggestions for 'pizza near Syd':</p>
<ul id="results"></ul>
<!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
<img
class="powered-by-google"
src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
alt="Powered by Google"
/>
<!--
The `defer` attribute causes the script to execute after the full HTML
document has been parsed. For non-blocking uses, avoiding race conditions,
and consistent behavior across browsers, consider loading using Promises. See
https://developers.google.com/maps/documentation/javascript/load-maps-js-api
for more information.
-->
<script
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
defer
></script>
</body>
</html>
AutocompleteService.getPlacePredictions() может использовать токены сеанса (если реализованы) для группировки запросов на автозаполнение для целей выставления счетов. Сессионные токеновые токены Группа Фазы запроса и выбора пользовательского поиска в дискретном сеансе для целей выставления счетов. Сеанс начинается, когда пользователь начинает печатать запрос, и завершается, когда он выбирает место. Каждый сеанс может иметь несколько запросов, за которым следует один выбор места. Как только сессия завершится, токен больше не является действительным. Ваше приложение должно генерировать свежий токен для каждого сеанса. Мы рекомендуем использовать токены сеанса для всех сеансов автозаполнения. Если параметр sessionToken опущен, или если вы повторно используете токен сеанса, сеанс взимается так, как если бы токен сеанса не был предоставлен (каждый запрос выставлен отдельно).
Вы можете использовать тот же токен сеанса, чтобы сделать один запрос сведений о месте в том месте, которое вызывает вызов к AutocompleteService.getPlacePredictions() . В этом случае запрос на автозаполнение сочетается с запросом с подробностями места, а вызов взимается в качестве регулярного запроса сведений о местах. За запрос на автозаполнение нет платы.
Обязательно пройдите уникальный токен сеанса для каждого нового сеанса. Использование одного и того же диапазона для более чем одного сеанса автозаполнения будет аннулировать эти сеансы автозаполнения, и весь запрос на автозаполнение в неверных сеансах будет взиматься индивидуально с использованием автозаполнения для запроса SKU . Узнайте больше о токенах сеанса .
В следующем примере показано создание токена сеанса, а затем передава его в AutocompleteService (функция displaySuggestions() была опущена для краткости):
// Create a new session token.varsessionToken=newgoogle.maps.places.AutocompleteSessionToken();// Pass the token to the autocomplete service.varautocompleteService=newgoogle.maps.places.AutocompleteService();autocompleteService.getPlacePredictions({input:'pizza near Syd',sessionToken:sessionToken},displaySuggestions);
Обязательно пройдите уникальный токен сеанса для каждого нового сеанса. Использование одного и того же ближеств для более чем одного сеанса приведет к тому, что каждый запрос будет выставлен индивидуально.
Стилизация виджетов автозаполнения и поисковой коробки
По умолчанию элементы пользовательского интерфейса, предоставленные Autocomplete и SearchBox , стилизованы для включения на карту Google. Вы можете настроить стиль в соответствии с вашим собственным сайтом. Следующие классы CSS доступны. Все перечисленные ниже классы применяются как к Autocomplete , так и к виджетам SearchBox .
Классы CSS для автозаполнения и виджетов Searchbox
CSS-класс
Описание
pac-container
Визуальный элемент, содержащий список прогнозов, возвращаемый службой автозаполнения места. Этот список отображается в виде раскрывающегося списка под Autocomplete или виджетом SearchBox .
pac-icon
Значок отображается слева от каждого элемента в списке прогнозов.
pac-item
Предмет в списке прогнозов, предоставленных виджетом Autocomplete или SearchBox .
pac-item:hover
Элемент, когда пользователь колеблется на него.
pac-item-selected
Элемент, когда пользователь выбирает его, используя клавиатуру. Примечание. Выбранные элементы будут членом этого класса и класса pac-item .
pac-item-query
Пролет внутри pac-item , который является основной частью прогноза. Для географических локаций это содержит название места, например, «Сидней», или название улицы и номер, например, «Кинг -стрит». Для текстовых поисков, таких как «Пицца в Нью-Йорке», он содержит полный текст запроса. По умолчанию pac-item-query цветной черный. Если в pac-item есть какой-либо дополнительный текст, он находится за пределами pac-item-query и наследует свой стиль от pac-item . По умолчанию он цветной серый. Дополнительный текст обычно является адресом.
pac-matched
Часть возвращаемого прогноза, которая соответствует вводу пользователя. По умолчанию этот соответствующий текст выделен жирным шрифтом. Обратите внимание, что соответствующий текст может быть где угодно в pac-item . Это не обязательно является частью pac-item-query , и это может быть частично в пределах pac-item-query , а также частично в оставшемся тексте в pac-item .
Поместите оптимизацию автозаполнения (Legacy)
В этом разделе описывается лучшие практики, которые помогут вам максимально использовать услугу автозаполнения (устаревшего).
Разработайте понимание существенных мест автозаполнения (Legacy) поля данных с самого начала.
Поля смещения местоположения и ограничения местоположения являются необязательными, но могут оказать существенное влияние на производительность автозаполнения.
Используйте обработку ошибок, чтобы убедиться, что ваше приложение изящно ослабляет, если API возвращает ошибку.
Убедитесь, что ваше приложение обрабатывает, когда нет выбора, и предлагает пользователям возможность продолжить.
Лучшие практики оптимизации затрат
Основная оптимизация затрат
Чтобы оптимизировать стоимость использования услуги AutoCoplete (Legacy) Place, используйте полевые маски на месте (Legacy) и разместите виджеты автозаполнения (Legacy), чтобы вернуть только необходимые поля данных .
Усовершенствованная оптимизация затрат
Рассмотрим программную реализацию автозаполнения места (Legacy), чтобы получить доступ к цене запроса и запросить результаты API геокодирования о выбранном месте вместо деталей места (Legacy). Ценообразование для запроса в сочетании с API геокодирования более рентабельно, чем ценообразование на сеанс (на основе сеанса), если оба из следующих условий выполнены:
Если вам нужна только широта/долгота или адрес выбранного пользователя, геокодирование API предоставляет эту информацию для вызова меньшего количества данных (Legacy).
Если пользователи выбирают предсказание автозаполнения в среднем из четырех запросов на AutoComplete (Legacy) или меньше, ценообразование для запроса может быть более рентабельным, чем цена за сеанс.
Для выбора реализации AutoComplete (Legacy), которая соответствует вашим потребностям, выберите вкладку, которая соответствует вашему ответу на следующий вопрос.
Требует ли ваша приложение какую -либо информацию, кроме адреса и широты/долготы выбранного прогноза?
The following guidelines describe ways to optimize Place Autocomplete (Legacy) performance:
Add country restrictions, location biasing , and (for programmatic implementations) language preference to your Place Autocomplete (Legacy) implementation. Language preference is not needed with widgets since they pick language preferences from the user's browser or mobile device.
If Place Autocomplete (Legacy) is accompanied by a map, you can bias location by map viewport.
In situations when a user does not choose one of the Place Autocomplete (Legacy) predictions, generally because none of those predictions are the result-address wanted, you can reuse the original user input to attempt to get more relevant results:
If you expect the user to enter only address information, reuse the original user input in a call to the Geocoding API .
If you expect the user to enter queries for a specific place by name or address, use a Find Place (Legacy) request . If results are only expected in a specific region, use location biasing .
Other scenarios when it's best to fall back to the Geocoding API include:
Users inputting subpremise addresses, such as addresses for specific units or apartments within a building. For example, the Czech address "Stroupežnického 3191/17, Praha" yields a partial prediction in Place Autocomplete (Legacy).
Users inputting addresses with road-segment prefixes like "23-30 29th St, Queens" in New York City or "47-380 Kamehameha Hwy, Kaneohe" on the island of Kauai in Hawai'i.
