Autocomplete виджет

Подключение библиотеки Places

Функциональность автодополнения адресов и объектов реализуется через библиотеку Places внутри Google Maps JavaScript API. Без её подключения виджет Autocomplete недоступен.

Загрузка API выполняется с указанием нужной библиотеки:

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

Ключевой параметр — libraries=places, который активирует доступ к сервису предсказаний мест и адресов.

Базовая инициализация Autocomplete

Виджет google.maps.places.Autocomplete привязывается к DOM-элементу input и начинает обрабатывать ввод пользователя, формируя список подсказок.

<input id="address" type="text" placeholder="Введите адрес" />
const input = document.getElementById("address");

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

После инициализации поле ввода становится источником запросов к сервису Places, а выпадающий список формируется автоматически.

Основная структура работы

Механизм Autocomplete включает несколько этапов:

  1. Ввод текста пользователем
  2. Отправка запроса в Places API
  3. Получение списка предсказаний
  4. Отображение вариантов в UI
  5. Выбор конкретного места
  6. Получение детальной информации о месте

Объект Place и получение данных

После выбора элемента генерируется событие place_changed.

autocomplete.addListener("place_changed", () => {
  const place = autocomplete.getPlace();
  console.log(place);
});

Метод getPlace() возвращает объект PlaceResult, содержащий данные о выбранном объекте.

Типичная структура включает:

  • place_id — уникальный идентификатор
  • formatted_address — полный адрес
  • geometry.location — координаты
  • name — название объекта
  • types — категории места
  • address_components — структурированные элементы адреса

Пример доступа к координатам:

const location = place.geometry.location;

const lat = location.lat();
const lng = location.lng();

Настройка ограничений поиска

Autocomplete поддерживает фильтрацию результатов через параметры конфигурации.

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

const autocomplete = new google.maps.places.Autocomplete(input, {
  types: ["geocode"]
});

Основные значения:

  • geocode — адреса
  • address — адресные данные
  • establishment — организации
  • (regions) — регионы
  • (cities) — города

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

const autocomplete = new google.maps.places.Autocomplete(input, {
  componentRestrictions: { country: "kz" }
});

Код страны задаётся в формате ISO 3166-1 alpha-2.

Ограничение по области поиска (bounds)

const circle = new google.maps.Circle({
  center: { lat: 49.8, lng: 73.1 },
  radius: 50000
});

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

autocomplete.setBounds(circle.getBounds());

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

Жёсткое ограничение границ

const autocomplete = new google.maps.places.Autocomplete(input, {
  strictBounds: true
});

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

Ограничение возвращаемых полей

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

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

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

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

Управление сессиями автодополнения

Places API использует механизм сессий для группировки запросов автодополнения и последующего выбора места.

Сессии позволяют:

  • объединять ввод пользователя в одну логическую операцию
  • оптимизировать биллинг
  • повышать точность предсказаний

Сессионные токены применяются на уровне запросов к Places Service, особенно при использовании расширенного API через AutocompleteService.

Использование AutocompleteService

Для более низкоуровневого управления запросами применяется AutocompleteService, не привязанный к DOM.

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

service.getPlacePredictions(
  {
    input: "Almaty",
    types: ["geocode"]
  },
  (predictions, status) => {
    console.log(predictions);
  }
);

Каждое предсказание содержит:

  • description
  • place_id
  • structured_formatting
  • types

Геолокационные подсказки и bias

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

navigator.geolocation.getCurrentPosition((position) => {
  const center = {
    lat: position.coords.latitude,
    lng: position.coords.longitude
  };

  const circle = new google.maps.Circle({
    center,
    radius: position.coords.accuracy
  });

  autocomplete.setBounds(circle.getBounds());
});

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

Обработка пользовательского выбора

После выбора места важно корректно обрабатывать состояние компонента:

autocomplete.addListener("place_changed", () => {
  const place = autocomplete.getPlace();

  if (!place.geometry) {
    return;
  }

  const position = {
    lat: place.geometry.location.lat(),
    lng: place.geometry.location.lng()
  };

  map.setCenter(position);
});

Проверка place.geometry необходима, поскольку некоторые результаты могут не содержать координат.

Поведение UI и кастомизация

Стандартный виджет генерирует собственный dropdown, однако поведение можно частично контролировать через CSS:

.pac-container {
  z-index: 10000;
}

.pac-item {
  font-size: 14px;
}

Основные элементы интерфейса:

  • .pac-container — контейнер списка
  • .pac-item — элемент подсказки
  • .pac-icon — иконка результата
  • .pac-item-query — основной текст запроса

Типы данных и структура предсказаний

Предсказания, возвращаемые сервисом, имеют строгую структуру:

{
  "description": "Almaty, Kazakhstan",
  "place_id": "ChIJ...",
  "types": ["locality", "political"],
  "structured_formatting": {
    "main_text": "Almaty",
    "secondary_text": "Kazakhstan"
  }
}

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

Производительность и оптимизация

При интенсивном использовании автодополнения учитываются следующие факторы:

  • минимизация количества запросов
  • ограничение типов (types)
  • сужение географической области (bounds)
  • использование fields для сокращения ответа
  • применение debounce на пользовательский ввод при использовании AutocompleteService

Пример debounce:

let timeout;

input.addEventListener("input", (e) => {
  clearTimeout(timeout);

  timeout = setTimeout(() => {
    service.getPlacePredictions({ input: e.target.value }, callback);
  }, 300);
});

Ограничения и особенности поведения

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

Некоторые типы объектов:

  • могут отсутствовать в конкретном регионе
  • могут возвращаться с неполными данными
  • могут агрегироваться (например, районы вместо улиц)

Модель ранжирования учитывает популярность, географическую близость и релевантность запроса.

Оглавление