Geocoder control

Geocoder control в Mapbox GL JS представляет собой готовый UI-компонент для поиска географических объектов, адресов и координат через сервис геокодирования Mapbox Geocoding API. В экосистеме Mapbox этот контрол подключается как отдельный плагин и расширяет базовую карту строкой поиска с автодополнением, обработкой результатов и управлением камерой карты.

Geocoder control не входит в ядро Mapbox GL JS и подключается через отдельный пакет @mapbox/mapbox-gl-geocoder. Он работает как связующее звено между пользовательским вводом и API геокодирования.

Основные компоненты:

  • UI-элемент (input + dropdown)
  • клиент запросов к Geocoding API
  • обработчик результатов (features)
  • интеграция с map.flyTo, map.fitBounds
  • опциональный маркер результата

Контрол реализует модель “ввод → запрос → список подсказок → выбор → перемещение карты”.

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

Библиотека подключается через npm:

npm install @mapbox/mapbox-gl-geocoder

Импорт в проект:

import mapboxgl from "mapbox-gl";
import MapboxGeocoder from "@mapbox/mapbox-gl-geocoder";
import "@mapbox/mapbox-gl-geocoder/dist/mapbox-gl-geocoder.css";

Подключение базовой карты:

mapboxgl.accessToken = "YOUR_MAPBOX_TOKEN";

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

Создание Geocoder control

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

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

map.addControl(geocoder);

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

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

accessToken

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

accessToken: mapboxgl.accessToken

mapboxgl

Передача объекта Mapbox GL JS обязательна для управления картой.

mapboxgl: mapboxgl

marker

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

marker: true

Возможные значения:

  • true — стандартный маркер
  • false — без маркера
  • объект new mapboxgl.Marker(...) — кастомный маркер

zoom

Определяет уровень масштабирования при выборе результата:

zoom: 14

placeholder

Текст в поле ввода:

placeholder: "Поиск адреса"

proximity

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

proximity: {
  longitude: 37.6173,
  latitude: 55.7558
}

Используется для повышения релевантности поиска.

bbox

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

bbox: [30, 50, 40, 60]

Формат: [minX, minY, maxX, maxY].

countries

Фильтрация по странам:

countries: "ru,kz"

language

Язык результатов:

language: "ru"

types

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

types: "address,place,poi"

Обработка событий

Geocoder control генерирует события, позволяющие управлять логикой приложения.

result

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

geocoder.on("result", (e) => {
  console.log(e.result);
});

e.result содержит GeoJSON Feature:

  • geometry (Point)
  • center [lng, lat]
  • place_name
  • properties
  • bbox (если доступен)

results

Срабатывает при обновлении списка подсказок:

geocoder.on("results", (e) => {
  console.log(e.features);
});

clear

Срабатывает при очистке поля:

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

Интеграция с управлением картой

Geocoder автоматически взаимодействует с картой:

  • перемещение камеры (flyTo)
  • масштабирование (zoom)
  • центрирование (setCenter)
  • подгонка границ (fitBounds)

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

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

  map.flyTo({
    center: coords,
    zoom: 16,
    speed: 1.2
  });
});

Кастомизация маркера результата

Отключение стандартного маркера:

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

Добавление собственного маркера:

const customMarker = new mapboxgl.Marker({ color: "red" });

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

Добавление в нестандартный контейнер

Geocoder можно разместить вне стандартных контролов карты:

document.getElementById("geocoder").appendChild(
  geocoder.onAdd(map)
);

Это позволяет интегрировать поиск в собственный UI.

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

Geocoder может работать как автономный компонент:

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

Результаты можно обрабатывать вручную через событие result.

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

Каждый результат соответствует формату GeoJSON Feature:

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [37.6173, 55.7558]
  },
  "place_name": "Москва, Россия",
  "center": [37.6173, 55.7558]
}

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

map.addSource("search-result", {
  type: "geojson",
  data: {
    type: "FeatureCollection",
    features: []
  }
});

Динамическое обновление источника

geocoder.on("result", (e) => {
  map.getSource("search-result").setData({
    type: "FeatureCollection",
    features: [e.result]
  });
});

Ограничение поиска по бизнес-логике

Geocoder позволяет настраивать поведение через фильтры:

  • ограничение региона (bbox)
  • ограничение стран (countries)
  • приоритет ближайших результатов (proximity)
  • типы объектов (types)

Комбинация параметров используется для строгих сценариев:

const geocoder = new MapboxGeocoder({
  accessToken: mapboxgl.accessToken,
  mapboxgl: mapboxgl,
  countries: "kz",
  types: "address,place",
  bbox: [46, 40, 87, 56],
  proximity: {
    longitude: 66.9237,
    latitude: 48.0196
  }
});

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

Geocoder использует дебаунсинг ввода: запрос отправляется после короткой паузы, что снижает нагрузку на Mapbox Geocoding API.

Дополнительно:

  • кеширование результатов
  • ограничение количества подсказок
  • оптимизация по proximity
  • адаптивная выдача по zoom/region

Стилизация интерфейса

CSS подключается отдельно и может быть переопределён:

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

Возможные кастомизации:

  • высота input
  • цвет фокуса
  • стили dropdown
  • оформление результатов

Встраивание нескольких геокодеров

В сложных интерфейсах можно использовать несколько экземпляров:

  • поиск отправной точки
  • поиск назначения
  • фильтрация объектов по слоям
const startGeocoder = new MapboxGeocoder({...});
const endGeocoder = new MapboxGeocoder({...});

Расширенные сценарии использования

Geocoder control часто используется как:

  • система поиска адресов в логистике
  • инструмент выбора точек маршрута
  • интерфейс выбора POI
  • компонент аналитических панелей
  • вспомогательный инструмент редактирования геоданных

При интеграции с пользовательскими слоями Mapbox GL JS он становится частью интерактивной гео-логики приложения, связывая текстовый поиск и пространственные данные карты в единую систему.

Оглавление