Настройка автодополнения

Автодополнение в экосистеме Google Maps JavaScript API реализуется через библиотеку Places, которая подключается отдельно от базового скрипта карты. Основой выступает загрузка API с корректно указанными параметрами ключа и необходимых библиотек.

Ключевые требования:

  • активированный API-ключ в консоли Google
  • включённые сервисы Maps JavaScript API и Places API
  • корректно заданные ограничения по ключу (HTTP referrers)

Пример подключения базового скрипта:

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

Параметр libraries=places является обязательным, поскольку именно он предоставляет доступ к механизму автодополнения и поиску объектов.

Инициализация карты

Перед созданием автодополнения требуется базовая инициализация карты и связанного DOM-контейнера.

<div id="map" style="height: 400px;"></div>
<input id="search" type="text" placeholder="Поиск места" />
let map;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 51.1694, lng: 71.4491 },
    zoom: 12,
  });
}

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

Подключение Autocomplete

Автодополнение реализуется через объект google.maps.places.Autocomplete, входящий в библиотеку Places Places API.

const input = document.getElementById("search");

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

После создания объекта поле ввода начинает автоматически обрабатывать пользовательский ввод и формировать список предсказаний.

Привязка Autocomplete к карте

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

autocomplete.bindTo("bounds", map);

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

Дополнительно можно синхронизировать маркер:

const marker = new google.maps.Marker({
  map,
  visible: false,
});

Обработка выбора места

Основное событие автодополнения — place_changed. Оно срабатывает после выбора одного из предложенных вариантов.

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

  if (!place.geometry) {
    return;
  }

  if (place.geometry.viewport) {
    map.fitBounds(place.geometry.viewport);
  } else {
    map.setCenter(place.geometry.location);
    map.setZoom(17);
  }

  marker.setPosition(place.geometry.location);
  marker.setVisible(true);
});

Объект place содержит:

  • координаты
  • геометрию (viewport или location)
  • идентификатор места
  • набор метаданных

Настройка параметров Autocomplete

Объект Autocomplete поддерживает конфигурацию, влияющую на поведение поиска.

Ограничение типов данных

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

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

  • geocode — адреса
  • establishment — организации
  • (regions) — административные области
  • (cities) — города

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

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

Параметр componentRestrictions ограничивает результаты одной или несколькими странами.

Поля данных (fields)

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

const autocomplete = new google.maps.places.Autocomplete(input, {
  fields: ["geometry", "name", "formatted_address"],
});

Это снижает объём возвращаемых данных и ускоряет обработку.

Управление областью поиска через bounds

Для повышения точности используется ограничение области поиска:

const defaultBounds = {
  north: 51.3,
  south: 51.0,
  west: 71.2,
  east: 71.6,
};

autocomplete.setBounds(defaultBounds);

В сочетании с bindTo("bounds", map) происходит динамическая адаптация к текущему виду карты.

Получение детализированной информации о месте

После выбора результата можно извлекать расширенные данные:

const place = autocomplete.getPlace();

console.log(place.name);
console.log(place.formatted_address);
console.log(place.geometry.location.lat());
console.log(place.geometry.location.lng());

Если требуется более глубокая информация (например, телефон, сайт, часы работы), необходимо включение дополнительных полей:

fields: ["geometry", "name", "formatted_address", "place_id"]

Далее используется place_id для запроса деталей через Places Service:

const service = new google.maps.places.PlacesService(map);

service.getDetails(
  { placeId: place.place_id },
  (result, status) => {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
      console.log(result);
    }
  }
);

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

Debounce и оптимизация ввода

Хотя Autocomplete управляет запросами самостоятельно, часто добавляется дополнительный слой контроля ввода:

let timeout;

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

  timeout = setTimeout(() => {
    console.log("Текущий ввод:", e.target.value);
  }, 300);
});

Такой подход полезен при комбинировании Autocomplete с собственными API-запросами.

Управление видимостью dropdown

Список подсказок управляется внутренним UI компонента и не предоставляет прямого DOM API. Однако поведение можно косвенно влиять через:

  • изменение bounds
  • фильтрацию types
  • ограничение componentRestrictions

Использование Autocomplete без карты

Autocomplete может работать автономно, без привязки к карте:

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

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

Работа с несколькими полями ввода

При использовании нескольких инпутов создаётся отдельный экземпляр Autocomplete для каждого поля:

const inputs = document.querySelectorAll(".search-input");

inputs.forEach((input) => {
  const ac = new google.maps.places.Autocomplete(input, {
    fields: ["geometry", "name"],
  });
});

Каждый экземпляр независим и управляет собственным списком предсказаний.

Производительность и особенности поведения

Поведение автодополнения зависит от:

  • частоты ввода
  • области bounds
  • количества запрашиваемых fields
  • сетевой задержки

Оптимизационные принципы:

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

Типовые ошибки интеграции

Отсутствие библиотеки places

Симптом: google.maps.places is undefined

Причина: не добавлен libraries=places при загрузке API.

Пустой geometry в place

if (!place.geometry) return;

Причина: не указано поле geometry в fields.

Несоответствие API-ключа

Симптом: ошибки запроса или блокировка Autocomplete

Причина: не активированы Maps JavaScript API и Places API в проекте.

Игнорирование bounds

Симптом: нерелевантные результаты при локальном поиске

Причина: отсутствие bindTo или setBounds.

Взаимодействие Autocomplete с другими сервисами

Autocomplete тесно связан с Places Service Places API, который используется для:

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

В связке они формируют единый механизм поиска и уточнения географических объектов в приложениях на базе Google Maps JavaScript API

Оглавление