Настройка поиска

В экосистеме Mapbox поиск географических объектов реализуется через Geocoding API и UI-компоненты, интегрируемые в Mapbox GL JS. Поиск в данном контексте включает три ключевых сценария: прямое геокодирование (адрес → координаты), обратное геокодирование (координаты → адрес) и интерактивный поиск с автодополнением.

Механизм поиска в Mapbox строится вокруг HTTP-запросов к API и последующего связывания результатов с картой через события, источники и методы управления камерой.

Подключение и базовая конфигурация поиска

Основой интеграции является токен доступа и подключение геокодера.

mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';

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

import MapboxGeocoder fr om '@mapbox/mapbox-gl-geocoder';

Инициализация геокодера:

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

Добавление на карту:

map.addControl(geocoder);

Компонент автоматически создает поисковую строку, выполняет запросы к Geocoding API и синхронизирует результат с картой.

Прямое геокодирование и структура запроса

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

Запрос формируется следующим образом:

https://api.mapbox.com/geocoding/v5/mapbox.places/{query}.json

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

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

Ключевые параметры запроса

  • limit — количество возвращаемых результатов
  • proximity — приоритет результатов относительно точки
  • bbox — ограничивающий прямоугольник поиска
  • types — фильтрация типов объектов (адрес, регион, POI)
  • language — язык результатов
  • country — ограничение по странам

Настройка геокодера Mapbox GL JS

Компонент MapboxGeocoder поддерживает расширенную конфигурацию поведения поиска.

const geocoder = new MapboxGeocoder({
  accessToken: mapboxgl.accessToken,
  mapboxgl: mapboxgl,
  placeholder: 'Поиск объектов',
  lim it: 5,
  minLength: 2,
});

Автодополнение

Автодополнение управляется параметром минимальной длины:

minLength: 3

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

Привязка поиска к области карты

Поиск может быть ограничен текущей видимой областью карты.

const geocoder = new MapboxGeocoder({
  accessToken: mapboxgl.accessToken,
  mapboxgl: mapboxgl,
  bbox: [-5.0, 35.0, 15.0, 45.0]
});

Использование bbox заставляет API возвращать результаты только внутри заданных границ, что критично для локальных приложений.

Смещение поиска (proximity bias)

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

const geocoder = new MapboxGeocoder({
  accessToken: mapboxgl.accessToken,
  mapboxgl: mapboxgl,
  proximity: {
    longitude: 69.2401,
    latitude: 53.2145
  }
});

Этот механизм не ограничивает результаты, но изменяет их ранжирование.

Фильтрация типов объектов

Поиск можно сузить до конкретных типов географических сущностей.

types: 'address,poi,place'

Поддерживаемые категории:

  • address — адреса
  • poi — точки интереса
  • place — города и населенные пункты
  • region — административные области
  • country — страны

Локализация результатов поиска

Язык ответов управляется параметром language.

language: 'ru'

Это влияет на:

  • транслитерацию названий
  • локализованные подписи
  • форматирование адресов

Обработка результатов поиска

Геокодер генерирует событие result, которое содержит выбранный объект.

geocoder.on('result', (event) => {
  console.log(event.result);
});

Структура результата:

  • geometry — координаты
  • place_name — полное название
  • center — центральная точка
  • bbox — границы объекта

Программное управление камерой

После получения результата карта обычно перемещается к объекту:

map.flyTo({
  center: result.geometry.coordinates,
  zoom: 12
});

При необходимости можно отключить автоматическое перемещение:

flyTo: false

Пользовательский UI поиска

Стандартный контрол можно заменить кастомным интерфейсом.

const input = document.createElement('input');

input.type = 'text';
input.placeholder = 'Поиск...';

input.addEventListener('input', (e) => {
  const query = e.target.value;

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

Такой подход позволяет полностью контролировать UX и интеграцию с другими компонентами интерфейса.

Ограничение результатов и оптимизация

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

Debounce запросов

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

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

input.addEventListener('input', debounce(handleSearch, 300));

Ограничение количества результатов

limit: 3

Снижение числа результатов уменьшает объем данных и ускоряет рендеринг интерфейса.

Обратное геокодирование

Обратный поиск преобразует координаты в адрес.

fetch(`https://api.mapbox.com/geocoding/v5/mapbox.places/-73.9857,40.7484.json?access_token=${mapboxgl.accessToken}`)
  .then(res => res.json())
  .then(data => {
    console.log(data.features[0]);
  });

Этот механизм используется при клике по карте или определении текущей позиции пользователя.

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

Поиск часто связывается с интерактивными событиями:

map.on('click', (e) => {
  const coords = e.lngLat;

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

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

Для аналитики и оптимизации API запросов используется session token.

const sessionToken = crypto.randomUUID();

Передача в запрос:

session_token=${sessionToken}

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

Комбинирование фильтров поиска

Поиск может одновременно использовать несколько ограничений:

const geocoder = new MapboxGeocoder({
  accessToken: mapboxgl.accessToken,
  mapboxgl: mapboxgl,
  countries: 'kz',
  types: 'place,poi',
  proximity: {
    longitude: 69.2401,
    latitude: 53.2145
  },
  limit: 5
});

Такая конфигурация формирует локализованный и контекстно релевантный поиск, ориентированный на конкретный регион и типы объектов.

Оглавление