Место автозаполнения

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.
Выберите платформу: Android iOS JavaScript Web Service

Введение

Автозаполнение — это функция библиотеки Places в Maps JavaScript API. Вы можете использовать автозаполнение, чтобы придать своим приложениям поведение опережающего поиска, аналогичное полю поиска Google Maps. Служба автозаполнения может сопоставлять полные слова и подстроки, разрешая географические названия, адреса и плюс-коды . Таким образом, приложения могут отправлять запросы по мере того, как пользователь вводит данные, чтобы на лету получать прогнозы места.

Начиная

Прежде чем использовать библиотеку Places в Maps JavaScript API, сначала убедитесь, что Places API включен в Google Cloud Console в том же проекте, который вы настроили для Maps JavaScript API.

Чтобы просмотреть список включенных API:

  1. Перейдите в облачную консоль Google .
  2. Нажмите кнопку « Выбрать проект» , затем выберите тот же проект, который вы настроили для Maps JavaScript API, и нажмите « Открыть » .
  3. В списке API на панели инструментов найдите Places API .
  4. Если вы видите API в списке, все готово. Если API нет в списке, включите его:
    1. В верхней части страницы выберите ВКЛЮЧИТЬ API , чтобы отобразить вкладку « Библиотека ». Кроме того, в левом боковом меню выберите « Библиотека ».
    2. Найдите Places API и выберите его в списке результатов.
    3. Выберите ВКЛЮЧИТЬ . Когда процесс завершится, Places API появится в списке API на панели инструментов .

Загрузка библиотеки

Служба Places представляет собой автономную библиотеку, отдельную от основного кода Maps JavaScript API. Чтобы использовать функции, содержащиеся в этой библиотеке, вы должны сначала загрузить ее, используя параметр libraries в URL начальной загрузки Maps API:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places&callback=initMap">
</script>

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

Резюме классов

API предлагает два типа виджетов автозаполнения, которые вы можете добавить с помощью классов Autocomplete и SearchBox соответственно. Кроме того, вы можете использовать класс AutocompleteService для программного получения результатов автозаполнения (см. Справочник по API JavaScript для Карт: класс AutocompleteService ).

Ниже приводится краткая информация о доступных классах:

  • Autocomplete добавляет поле ввода текста на вашу веб-страницу и отслеживает ввод символов в этом поле. По мере того, как пользователь вводит текст, автозаполнение возвращает подсказки места в виде раскрывающегося списка выбора. Когда пользователь выбирает место из списка, информация о месте возвращается в объект автозаполнения и может быть извлечена вашим приложением. Подробнее см. ниже .
    Текстовое поле автозаполнения и список подсказок мест, которые появляются, когда пользователь вводит поисковый запрос.
    Рисунок 1: Текстовое поле автозаполнения и список выбора
    Заполненная адресная форма.
    Рисунок 2: Заполненная адресная форма
  • SearchBox добавляет поле ввода текста на вашу веб-страницу почти так же, как Autocomplete . Различия заключаются в следующем:
    • Основное отличие заключается в результатах, которые появляются в списке выбора. SearchBox предоставляет расширенный список прогнозов, который может включать места (в соответствии с определением Places API) и предлагаемые условия поиска. Например, если пользователь вводит «пицца в Нью-Йорке», список выбора может включать фразу «пицца в Нью-Йорке, штат Нью-Йорк», а также названия различных пиццерий.
    • SearchBox предлагает меньше возможностей для ограничения поиска, чем Autocomplete . В первом случае вы можете сместить поиск в сторону заданного LatLngBounds . В последнем вы можете ограничить поиск определенной страной и конкретными типами мест, а также установить границы. Для получения дополнительной информации см. ниже .
    Заполненная адресная форма.
    Рис. 3. Поле поиска представляет поисковые запросы и подсказки мест.
    Подробнее см. ниже .
  • Вы можете создать объект AutocompleteService для программного получения прогнозов. Вызовите getPlacePredictions() , чтобы получить совпадающие места, или вызовите getQueryPredictions() , чтобы получить совпадающие места и предлагаемые условия поиска. Примечание. AutocompleteService не добавляет никаких элементов управления пользовательского интерфейса. Вместо этого вышеуказанные методы возвращают массив объектов предсказания. Каждый объект прогноза содержит текст прогноза, а также справочную информацию и сведения о том, как результат соответствует вводу пользователя. Подробнее см. ниже .

Добавление виджета автозаполнения

Виджет Autocomplete создает поле ввода текста на вашей веб-странице, предоставляет прогнозы мест в списке выбора пользовательского интерфейса и возвращает сведения о месте в ответ на getPlace() . Каждая запись в списке выбора соответствует одному месту (согласно определению Places API).

Конструктор 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. Несколько стран должны быть переданы в виде списка кодов стран.

      Примечание. Если вы получаете непредвиденные результаты с кодом страны, убедитесь, что вы используете код, который включает страны, зависимые территории и особые географические области, которые вы планируете использовать. Информацию о кодах можно найти в Википедии: Список кодов стран ISO 3166 или на платформе онлайн-просмотра ISO .

    • placeIdOnly можно указать виджету Autocomplete получать только идентификаторы мест. При вызове getPlace() для объекта Autocomplete доступный PlaceResult будет иметь только установленные свойства place id , types и name . Вы можете использовать возвращенный идентификатор места с вызовами служб Places, Geocoding, Directions или Distance Matrix.

Ограничение прогнозов автозаполнения

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

Задайте параметры при построении

Конструктор Autocomplete принимает параметр AutocompleteOptions для установки ограничений при создании виджета. В следующем примере параметры bounds , componentRestrictions и types задаются для запроса мест типа establishment , отдавая предпочтение тем, которые находятся в указанной географической области, и ограничивая прогнозы только местами в Соединенных Штатах. Установка параметра fields указывает, какую информацию о выбранном пользователем месте следует возвращать.

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

Машинопись

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
  types: ["establishment"],
};

const autocomplete = new google.maps.places.Autocomplete(input, options);

JavaScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input");
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
  types: ["establishment"],
};
const autocomplete = new google.maps.places.Autocomplete(input, options);

Укажите поля данных

Укажите поля данных, чтобы не взимать плату за SKU Places Data , которые вам не нужны. Включите свойство fields в AutocompleteOptions , которые передаются конструктору виджета, как показано в предыдущем примере, или вызовите setFields() для существующего объекта Autocomplete .

autocomplete.setFields(["place_id", "geometry", "name"]);

Определите смещения и границы области поиска для автозаполнения

Вы можете сместить результаты автозаполнения в пользу приблизительного местоположения или области следующими способами:

  • Установите границы создания объекта Autocomplete .
  • Измените границы существующего Autocomplete .
  • Установите границы области просмотра карты.
  • Ограничьте поиск границами.
  • Ограничьте поиск определенной страной.

В предыдущем примере демонстрируется установка границ при создании. Следующие примеры демонстрируют другие методы смещения.

Изменить границы существующего автозаполнения

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

Машинопись

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);

JavaScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);
Установите границы области просмотра карты

Используйте bindTo() для смещения результатов в область просмотра карты, даже если эта область просмотра изменяется.

Машинопись

autocomplete.bindTo("bounds", map);

JavaScript

autocomplete.bindTo("bounds", map);

Используйте unbind() , чтобы отменить привязку прогнозов автозаполнения к области просмотра карты.

Машинопись

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });

JavaScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });

Посмотреть пример

Ограничить поиск текущими границами

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

autocomplete.setOptions({ strictBounds: true });
Ограничить прогнозы для конкретной страны

Используйте параметр componentRestrictions или вызовите setComponentRestrictions() , чтобы ограничить поиск автозаполнения определенным набором из пяти стран.

Машинопись

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

JavaScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

Посмотреть пример

Ограничение типов мест

Используйте опцию types или вызовите setTypes() , чтобы ограничить предсказания определенными типами мест. Это ограничение задает тип или коллекцию типов, как указано в Place Types . Если ограничение не указано, возвращаются все типы.

Для значения параметра types или значения, переданного в setTypes() , вы можете указать:

  • Массив, содержащий до пяти значений из Таблицы 1 или Таблицы 2 из Типов мест . Например:

    types: ['hospital', 'pharmacy', 'bakery', 'country']

    Или же:

    autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
  • Любой фильтр в Таблице 3 из Типов мест . Вы можете указать только одно значение из Таблицы 3.

Запрос будет отклонен, если:

  • Вы указываете более пяти типов.
  • Вы указываете любые нераспознанные типы.
  • Вы смешиваете любые типы из Таблицы 1 или Таблицы 2 с любым фильтром из Таблицы 3 .

Демонстрация автозаполнения мест демонстрирует различия в прогнозах для разных типов мест.

Посетите демо

Получение информации о месте

Когда пользователь выбирает место из подсказок, прикрепленных к текстовому полю автозаполнения, служба запускает событие place_changed . Чтобы получить информацию о месте:

  1. Создайте обработчик события place_changed и вызовите addListener() для объекта Autocomplete , чтобы добавить обработчик.
  2. Вызовите Autocomplete.getPlace() для объекта Autocomplete , чтобы получить объект PlaceResult , который затем можно использовать для получения дополнительной информации о выбранном месте.

По умолчанию, когда пользователь выбирает место, автозаполнение возвращает все доступные поля данных для выбранного места, и вам будет выставлен соответствующий счет . Используйте Autocomplete.setFields() , чтобы указать, какие поля данных места возвращаются. Узнайте больше об объекте PlaceResult , включая список полей данных места, которые вы можете запросить. Чтобы не платить за данные, которые вам не нужны, обязательно используйте Autocomplete.setFields() , чтобы указать только те данные о местах, которые вы будете использовать.

Свойство name содержит description из подсказок Places Autocomplete. Подробнее об description можно прочитать в документации Places Autocomplete .

Для адресных форм полезно получать адрес в структурированном формате. Чтобы вернуть структурированный адрес для выбранного места, вызовите Autocomplete.setFields() и укажите поле address_components .

В следующем примере используется автозаполнение для заполнения полей в адресной форме.

Машинопись

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // 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/3l5i5Mr
  for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
    // @ts-ignore remove once typings fixed
    const componentType = 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") as HTMLInputElement).value =
          component.long_name;
        break;

      case "administrative_area_level_1": {
        (document.querySelector("#state") as HTMLInputElement).value =
          component.short_name;
        break;
      }

      case "country":
        (document.querySelector("#country") as HTMLInputElement).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();
}

JavaScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // 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/3l5i5Mr
  for (const component of place.address_components) {
    // @ts-ignore remove once typings fixed
    const componentType = 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 предоставляет расширенный список прогнозов, который может включать места (в соответствии с определением Places API) и предлагаемые условия поиска. Например, если пользователь вводит «пицца в Нью-Йорке», список выбора может включать фразу «пицца в Нью-Йорке, штат Нью-Йорк», а также названия различных пиццерий. Когда пользователь выбирает место из списка, информация об этом месте возвращается в объект SearchBox и может быть извлечена вашим приложением.

Конструктор SearchBox принимает два аргумента:

  • Элемент input HTML типа text . Это поле ввода, которое служба SearchBox будет отслеживать и прикреплять к нему свои результаты.
  • Аргумент options , который может содержать свойство bounds : bounds — это объект google.maps.LatLngBounds , указывающий область, в которой нужно искать места. Результаты смещены в сторону мест, содержащихся в этих границах, но не ограничиваются ими.

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

var defaultBounds = new google.maps.LatLngBounds(
  new google.maps.LatLng(-33.8902, 151.1759),
  new google.maps.LatLng(-33.8474, 151.2631));

var input = document.getElementById('searchTextField');

var searchBox = new google.maps.places.SearchBox(input, {
  bounds: defaultBounds
});

Изменение области поиска для SearchBox

Чтобы изменить область поиска для существующего 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", () => {
  const places = 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.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon as string,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.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);
});

JavaScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = 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.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.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() возвращает прогнозы мест. Примечание. «Место» может быть заведением, географическим местоположением или известной достопримечательностью, как определено в Places API.
  • getQueryPredictions() возвращает расширенный список прогнозов, который может включать места (в соответствии с определением Places API) и предлагаемые условия поиска. Например, если пользователь вводит «пицца в Нью-Йорке», список выбора может включать фразу «пицца в Нью-Йорке, штат Нью-Йорк», а также названия различных пиццерий.

Оба вышеуказанных метода возвращают массив объектов предсказания следующего вида:

  • description соответствует предсказанию.
  • Distance_meters — это distance_meters в метрах до места от указанного AutocompletionRequest.origin .
  • matched_substrings содержит набор подстрок в описании, которые соответствуют элементам пользовательского ввода. Это полезно для выделения этих подстрок в вашем приложении. Во многих случаях запрос будет отображаться как подстрока поля описания.
    • length — это длина подстроки.
    • offset — это смещение символа, измеренное от начала строки описания, на котором появляется совпавшая подстрока.
  • place_id — это текстовый идентификатор, однозначно идентифицирующий место. Чтобы получить информацию о месте, передайте этот идентификатор в поле placeId запроса Place Details . Узнайте больше о том, как сослаться на место с помощью идентификатора места .
  • 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">
function initService(): void {
  const displaySuggestions = 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) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      (document.getElementById("results") as HTMLUListElement).appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

declare global {
  interface Window {
    initService: () => void;
  }
}
window.initService = initService;

JavaScript

// 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">
function initService() {
  const displaySuggestions = function (predictions, status) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById("results").appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

window.initService = initService;

CSS

HTML

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <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 callback 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
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <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.
var sessionToken = new google.maps.places.AutocompleteSessionToken();

// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
  input: 'pizza near Syd',
  sessionToken: sessionToken
},
displaySuggestions);

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

Подробнее о сессионных токенах .

Стилизация виджетов Autocomplete и SearchBox

По умолчанию элементы пользовательского интерфейса, предоставляемые Autocomplete и SearchBox , настроены для включения на карту Google. Вы можете настроить стиль в соответствии с вашим сайтом. Доступны следующие классы CSS. Все перечисленные ниже классы применяются как к виджетам Autocomplete , так и к виджетам SearchBox .

Графическая иллюстрация классов CSS для виджетов Autocomplete и SearchBox.
Классы CSS для виджетов Autocomplete и 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 , который является основной частью прогноза. Для географических местоположений это содержит название места, например «Сидней», или название улицы и номер, например «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 .

Место для оптимизации автозаполнения

В этом разделе описаны рекомендации, которые помогут вам максимально эффективно использовать службу автозаполнения мест.

Вот несколько общих рекомендаций:

  • Самый быстрый способ разработать работающий пользовательский интерфейс — использовать виджет автозаполнения Maps JavaScript API , виджет Places SDK для Android Autocomplete или Places SDK для элемента управления пользовательского интерфейса автозаполнения iOS.
  • С самого начала разберитесь с основными полями данных Place Autocomplete.
  • Поля смещения местоположения и ограничения местоположения являются необязательными, но могут существенно повлиять на производительность автозаполнения.
  • Используйте обработку ошибок, чтобы убедиться, что ваше приложение корректно деградирует, если API возвращает ошибку.
  • Убедитесь, что ваше приложение обрабатывает, когда нет выбора, и предлагает пользователям возможность продолжить.

Лучшие практики оптимизации затрат

Базовая оптимизация затрат

Чтобы оптимизировать затраты на использование службы автозаполнения места, используйте маски полей в виджетах «Сведения о месте» и «Автозаполнение места», чтобы возвращать только те поля данных места, которые вам нужны.

Расширенная оптимизация затрат

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

  • Если вам нужны только широта/долгота или адрес выбранного пользователем места, API геокодирования предоставит эту информацию дешевле, чем вызов сведений о месте.
  • Если пользователи выбирают прогноз автозаполнения в среднем из четырех запросов прогнозов автозаполнения или меньше, цена за запрос может быть более рентабельной, чем цена за сеанс.
Чтобы получить помощь в выборе реализации Place Autocomplete, которая соответствует вашим потребностям, выберите вкладку, соответствующую вашему ответу на следующий вопрос.

Требует ли ваше приложение какой-либо информации, кроме адреса и широты/долготы выбранного прогноза?

Да, нужно больше подробностей

Используйте автозаполнение места на основе сеанса со сведениями о месте.
Поскольку вашему приложению требуются сведения о месте, такие как название места, бизнес-статус или часы работы, ваша реализация автозаполнения места должна использовать токен сеанса ( программно или встроенный в виджеты JavaScript , Android или iOS ) с общей стоимостью 0,017 долл . США за каждое приложение. сеанс плюс применимые SKU данных о местах в зависимости от того, какие поля данных о местах вы запрашиваете. 1

Реализация виджета
Управление сеансом автоматически встроено в виджеты JavaScript , Android или iOS . Сюда входят как запросы автозаполнения места, так и запрос сведений о месте для выбранного прогноза. Обязательно укажите параметр fields , чтобы убедиться, что вы запрашиваете только те поля данных места, которые вам нужны.

Программная реализация
Используйте токен сеанса с вашими запросами автозаполнения мест. При запросе сведений о месте для выбранного прогноза укажите следующие параметры:

  1. Идентификатор места из ответа автозаполнения места
  2. Токен сеанса, используемый в запросе автозаполнения места
  3. Параметр fields , указывающий, какие поля данных места вам нужны

Нет, нужен только адрес и местоположение

Geocoding API может быть более экономичным вариантом, чем Place Details для вашего приложения, в зависимости от производительности вашего использования Place Autocomplete. Эффективность автозаполнения каждого приложения зависит от того, что вводят пользователи, где используется приложение и были ли реализованы передовые методы оптимизации производительности .

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

Ваши пользователи выбирают подсказку автозаполнения места в среднем за четыре или меньше запросов?

Да

Реализуйте автозаполнение мест программно без токенов сеанса и вызовите API геокодирования для предсказания выбранного места.
API геокодирования предоставляет адреса и координаты широты/долготы по цене 0,005 доллара США за запрос. Выполнение четырех запросов автозаполнения места — на запрос стоит 0,01132 доллара США, поэтому общая стоимость четырех запросов плюс вызов API геокодирования по поводу прогноза выбранного места составит 0,01632 доллара США, что меньше, чем цена автозаполнения сеанса, составляющая 0,017 доллара США за сеанс. 1

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

Нет

Используйте автозаполнение места на основе сеанса со сведениями о месте.
Поскольку среднее количество запросов, которое вы ожидаете сделать, прежде чем пользователь выберет прогноз автозаполнения места, превышает стоимость ценообразования за сеанс, ваша реализация автозаполнения места должна использовать токен сеанса как для запросов автозаполнения места, так и для связанного запроса сведений о месте для общая стоимость $0,017 за сеанс . 1

Реализация виджета
Управление сеансом автоматически встроено в виджеты JavaScript , Android или iOS . Сюда входят как запросы автозаполнения места, так и запрос сведений о месте для выбранного прогноза. Обязательно укажите параметр fields , чтобы убедиться, что вы запрашиваете только поля основных данных .

Программная реализация
Используйте токен сеанса с вашими запросами автозаполнения места. При запросе сведений о месте для выбранного прогноза укажите следующие параметры:

  1. Идентификатор места из ответа автозаполнения места
  2. Токен сеанса, используемый в запросе автозаполнения места
  3. Параметр fields , определяющий поля базовых данных , такие как адрес и геометрия.

Рассмотрите возможность задержки запросов автозаполнения мест
Вы можете использовать такие стратегии, как отсрочка запроса автозаполнения места до тех пор, пока пользователь не введет первые три или четыре символа, чтобы ваше приложение делало меньше запросов. Например, отправка запросов автозаполнения места для каждого символа после того, как пользователь ввел третий символ, означает, что если пользователь введет семь символов, а затем выберет прогноз, для которого вы делаете один запрос API геокодирования, общая стоимость составит 0,01632 доллара США (4 * 0,00283 доллара США). За запрос + геокодирование 0,005 USD). 1

Если отложенные запросы могут привести к тому, что ваш средний программный запрос станет меньше четырех, вы можете следовать рекомендациям по эффективному автозаполнению мест с реализацией API геокодирования . Обратите внимание, что задержка запросов может восприниматься пользователем как задержка, поскольку он может ожидать появления прогнозов при каждом новом нажатии клавиши.

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


  1. Стоимость указана здесь в долларах США. Полную информацию о ценах см. на странице выставления счетов платформы Google Maps .

Рекомендации по повышению производительности

Следующие рекомендации описывают способы оптимизации производительности автозаполнения места:

  • Добавьте ограничения по странам, смещение местоположения и (для программных реализаций) языковые предпочтения в свою реализацию автозаполнения мест. Языковые предпочтения не требуются для виджетов, поскольку они выбирают языковые настройки в браузере пользователя или на мобильном устройстве.
  • Если автозаполнение места сопровождается картой, вы можете изменить местоположение по области просмотра карты.
  • В ситуациях, когда пользователь не выбирает один из прогнозов автозаполнения, как правило, потому, что ни один из этих прогнозов не является желаемым адресом результата, вы можете повторно использовать исходный пользовательский ввод, чтобы попытаться получить более релевантные результаты:
    • Если вы ожидаете, что пользователь введет только адресную информацию, повторно используйте исходный пользовательский ввод в вызове API геокодирования .
    • Если вы ожидаете, что пользователь будет вводить запросы для определенного места по имени или адресу, используйте запрос «Найти место ». Если результаты ожидаются только в определенном регионе, используйте смещение местоположения .
    Другие сценарии, когда лучше всего вернуться к API геокодирования, включают:
    • Пользователи, вводящие адреса субпомещений в странах, отличных от Австралии, Новой Зеландии или Канады. For example, the US address "123 Bowdoin St #456, Boston MA, USA" is not supported by Autocomplete. (Autocomplete supports subpremise addresses only in Australia, New Zealand, and Canada. Supported address formats in these three countries include "9/321 Pitt Street, Sydney, New South Wales, Australia" or "14/19 Langana Avenue, Browns Bay, Auckland, New Zealand" or "145-112 Renfrew Dr, Markham, Ontario, Canada".)
    • 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.

Usage limits and policies

Quotas

For quota and pricing information, see the Usage and Billing documentation for the Places API.

Policies

Use of the Places Library, Maps JavaScript API must be in accordance with the policies described for the Places API .