Autocomplete функционал

Autocomplete в контексте Mapbox GL JS реализуется через связку Mapbox Geocoding API и компонента интерфейса Mapbox Geocoder, который предоставляет интерактивное поле поиска с автоподсказками адресов, объектов и географических сущностей. Механизм основан на серверной генерации предложений (suggestions) по мере ввода текста и локальной фильтрации результатов с учётом контекста карты.

Архитектура автодополнения в экосистеме Mapbox

Autocomplete не является встроенной функцией Mapbox GL JS как рендера карты. Он формируется на уровне отдельного API:

  • Geocoding API — отвечает за поиск и генерацию предложений
  • Mapbox Geocoder (plugin) — UI-компонент для взаимодействия
  • Mapbox GL JS — визуализация результата на карте

Система работает по схеме:

  1. Ввод текста в поле поиска
  2. Отправка запроса в Geocoding API
  3. Получение списка предложений (suggestions)
  4. Отображение автодополнения
  5. Выбор результата и интеграция с картой (переход, маркер, зум)

Подключение Mapbox Geocoder

Autocomplete реализуется через официальный плагин:

import mapboxgl fr om "mapbox-gl";
import MapboxGeocoder fr om "@mapbox/mapbox-gl-geocoder";

mapboxgl.accessToken = "YOUR_MAPBOX_ACCESS_TOKEN";

const map = new mapboxgl.Map({
  container: "map",
  style: "mapbox://styles/mapbox/streets-v12",
  center: [69.2401, 41.2995],
  zoom: 10
});

Добавление геокодера:

const geocoder = new MapboxGeocoder({
  accessToken: mapboxgl.accessToken,
  mapboxgl: mapboxgl
});

map.addControl(geocoder);

Принцип работы autocomplete в Geocoder

Autocomplete активируется автоматически при вводе текста. Каждый ввод инициирует запрос:

/geocoding/v5/mapbox.places/{query}.json

Результат содержит массив предложений, отсортированных по релевантности.

Основные параметры конфигурации

types — типы объектов поиска

Ограничение поиска конкретными категориями:

types: "country,region,place,address,poi"

Используется для сужения области автодополнения.

countries — ограничение по странам

countries: "kz"

Фильтрация результатов только по указанным странам.

language — локализация результатов

language: "ru"

Влияет на язык названий в подсказках.

limit — количество предложений

limit: 5

Определяет число автоподсказок в списке.

proximity — приоритет географической близости

proximity: {
  longitude: 69.2401,
  latitude: 41.2995
}

Смещает релевантность в сторону объектов рядом с указанной точкой.

bbox — ограничение области поиска

bbox: [68.0, 40.0, 71.0, 43.0]

Используется для строгого географического ограничения результатов.

Полная конфигурация автодополнения

const geocoder = new MapboxGeocoder({
  accessToken: mapboxgl.accessToken,
  mapboxgl: mapboxgl,
  placeholder: "Поиск",
  language: "ru",
  countries: "kz",
  types: "place,address,poi",
  lim it: 6,
  proximity: {
    longitude: 69.2401,
    latitude: 41.2995
  }
});

События выбора результата

Autocomplete тесно связан с событиями Geocoder.

result

Срабатывает при выборе элемента:

geocoder.on("result", (e) => {
  const coords = e.result.center;

  map.flyTo({
    center: coords,
    zoom: 14
  });
});

clear

Очистка поиска:

geocoder.on("clear", () => {
  console.log("поиск очищен");
});

Управление поведением autocomplete

Отключение автоподсказок

Хотя стандартный Geocoder всегда использует suggestions, можно управлять логикой через кастомную реализацию и прямой вызов API.

Пример запроса без UI:

fetch(
  `https://api.mapbox.com/geocoding/v5/mapbox.places/Almaty.json?access_token=${mapboxgl.accessToken}`
)
  .then(res => res.json())
  .then(data => console.log(data.features));

Debounce и оптимизация запросов

Autocomplete чувствителен к производительности. Каждый ввод инициирует API-запрос, поэтому применяется debounce:

function debounce(fn, delay) {
  let timeout;
  return (...args) => {
    clearTimeout(timeout);
    timeout = setTimeout(() => fn(...args), delay);
  };
}

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

const search = debounce((value) => {
  console.log("запрос:", value);
}, 300);

Session tokens и биллинг

Mapbox использует session tokens для группировки запросов autocomplete в одну сессию. Это влияет на биллинг и релевантность.

Типичная схема:

  • начало ввода → создаётся session token
  • серия autocomplete запросов
  • выбор результата завершает сессию

Пример кастомного использования:

const geocoder = new MapboxGeocoder({
  accessToken: mapboxgl.accessToken,
  mapboxgl: mapboxgl,
  sessionToken: "random-session-id"
});

Кастомизация интерфейса autocomplete

Geocoder позволяет переопределять внешний вид:

.mapboxgl-ctrl-geocoder {
  width: 100%;
  max-width: 400px;
}

Также возможно создание полностью кастомного UI с использованием только Geocoding API.

Работа с результатами autocomplete

Каждый элемент результата содержит структуру:

{
  "place_name": "Almaty, Kazakhstan",
  "center": [76.9286, 43.222],
  "place_type": ["place"]
}

Основные поля:

  • place_name — отображаемое название
  • center — координаты
  • geometry — геометрия объекта
  • context — административная структура

Глубокая фильтрация результатов

Autocomplete можно настраивать через комбинации фильтров:

types: "address",
countries: "kz",
bbox: [68, 40, 75, 45],
limit: 10

Это позволяет строить узкоспециализированные поисковые интерфейсы, например:

  • только адреса
  • только POI
  • только внутри региона

Интеграция с кастомными маркерами

После выбора результата часто добавляется маркер:

geocoder.on("result", (e) => {
  const coords = e.result.center;

  new mapboxgl.Marker()
    .setLngLat(coords)
    .addTo(map);
});

Продвинутый сценарий: собственный autocomplete

Без Geocoder UI можно реализовать собственную систему:

async function autocomplete(query) {
  const res = await fetch(
    `https://api.mapbox.com/geocoding/v5/mapbox.places/${query}.json?access_token=${mapboxgl.accessToken}&autocomplete=true`
  );

  const data = await res.json();
  return data.features;
}

Далее результаты отображаются в любом UI-слое приложения.

Типичные проблемы и ограничения

  • задержка сети влияет на ощущение “живого” autocomplete
  • слишком широкий bbox снижает релевантность
  • отсутствие proximity ухудшает локальные результаты
  • частые запросы без debounce приводят к throttling

Роль autocomplete в картографических интерфейсах

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

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

Обработка неоднозначных результатов

Некоторые запросы возвращают несколько типов объектов. Например, название может совпадать с городом и POI. В таких случаях используется:

  • приоритет proximity
  • сортировка по relevance
  • уточнение через context
e.result.context.forEach(c => {
  console.log(c.id, c.text);
});

Использование autocomplete в сложных интерфейсах

В SPA-приложениях autocomplete часто связывается с:

  • фильтрами слоёв карты
  • динамическими маршрутами
  • выбором точек A/B
  • геоаналитикой

Mapbox GL JS выступает как визуальный слой, а autocomplete — как входной фильтр пространственных данных.

Оглавление