Mapbox APIs

Mapbox APIs в экосистеме Mapbox представляют собой набор сервисов, обеспечивающих работу с картографическими данными, стилями, геокодированием, маршрутизацией и векторными тайлами. В связке с Mapbox GL JS они формируют основу для построения интерактивных веб-карт нового поколения, где рендеринг выполняется на стороне клиента с использованием WebGL.

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

  • предоставление картографических тайлов (raster и vector tiles)
  • управление стилями карт
  • геокодирование и обратное геокодирование
  • построение маршрутов
  • получение данных о местах (places API)
  • управление пользовательскими данными (datasets, tilesets)

Mapbox GL JS выступает клиентским рендерером, который получает данные от этих API и визуализирует их в браузере через WebGL. Вместо готовых изображений карта формируется динамически из векторных тайлов и стилей.

Ключевой принцип архитектуры — разделение данных и представления: API поставляют геоданные, а GL JS отвечает за визуализацию.

Типы Mapbox API

Style API

Style API управляет тем, как карта выглядит. Стиль представляет собой JSON-документ, описывающий:

  • источники данных (sources)
  • слои (layers)
  • типы визуализации (fill, line, symbol, circle, heatmap)
  • шрифты и иконки
  • правила фильтрации и масштабирования

Стиль в Mapbox GL JS загружается через:

map.setStyle('mapbox://styles/mapbox/streets-v12');

Стиль определяет не только визуализацию, но и структуру отображения данных. Каждый слой привязан к источнику и может быть условно активен в зависимости от zoom level.

Vector Tiles API

Vector Tiles API — ключевой компонент всей системы. В отличие от растровых тайлов, векторные тайлы содержат геометрию:

  • точки
  • линии
  • полигоны
  • атрибуты объектов

Mapbox GL JS интерпретирует эти данные и рендерит их динамически. Это позволяет:

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

Источник подключается так:

map.addSource('cities', {
  type: 'vector',
  url: 'mapbox://mapbox.urban-areas'
});

Далее слой связывается с источником:

map.addLayer({
  id: 'city-fill',
  type: 'fill',
  source: 'cities',
  'source-layer': 'urban_areas',
  paint: {
    'fill-color': '#3bb2d0',
    'fill-opacity': 0.5
  }
});

Geocoding API

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

Прямое геокодирование:

https://api.mapbox.com/geocoding/v5/mapbox.places/Almaty.json

Ответ содержит:

  • координаты (longitude, latitude)
  • тип объекта (place, address, region)
  • контекст (страна, регион, город)
  • рейтинг релевантности

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

https://api.mapbox.com/geocoding/v5/mapbox.places/76.8865,43.2389.json

В Mapbox GL JS результаты часто используются для поиска и автодополнения интерфейсов.

Directions API

Directions API строит маршруты между точками. Поддерживаются режимы:

  • driving
  • walking
  • cycling
  • traffic-aware routing

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

https://api.mapbox.com/directions/v5/mapbox/driving/76.8865,43.2389;77.0150,43.3550

Ответ включает:

  • геометрию маршрута
  • расстояние
  • время в пути
  • пошаговые инструкции

Маршрут может быть визуализирован в Mapbox GL JS как GeoJSON слой:

map.addSource('route', {
  type: 'geojson',
  data: routeGeoJSON
});

Places API

Places API предоставляет доступ к базе объектов:

  • компании
  • адреса
  • достопримечательности
  • инфраструктура

Используется для поиска и автодополнения. Результаты включают:

  • координаты
  • категорию
  • метаданные
  • контекст расположения

Data API и Tilesets API

Data API и Tilesets API используются для загрузки пользовательских данных.

Tilesets позволяют:

  • загружать GeoJSON
  • преобразовывать данные в векторные тайлы
  • оптимизировать отображение больших наборов данных

Процесс состоит из этапов:

  1. загрузка исходного GeoJSON
  2. валидация и обработка
  3. генерация тайлов
  4. публикация в виде mapbox:// URL

Access Tokens и безопасность API

Все запросы к Mapbox API требуют access token:

mapboxgl.accessToken = 'YOUR_ACCESS_TOKEN';

Токен определяет:

  • доступные API
  • лимиты запросов
  • разрешённые домены (restrictions)
  • уровень тарификации

Токены можно ограничивать по:

  • URL источника
  • типу API
  • IP-адресу

Работа Mapbox GL JS с API

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

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/light-v11',
  center: [76.8865, 43.2389],
  zoom: 10
});

При инициализации происходит:

  • запрос Style API
  • загрузка источников данных
  • получение векторных тайлов
  • построение WebGL сцены

Слои и источники данных

В Mapbox GL JS все визуальные элементы строятся на основе двух сущностей:

  • source — источник данных
  • layer — способ отображения

Типы источников:

  • vector
  • raster
  • geojson
  • image
  • video

Типы слоёв:

  • fill (полигоны)
  • line (линии)
  • symbol (иконки и текст)
  • circle (точки)
  • heatmap (тепловые карты)

Каждый слой поддерживает:

  • paint properties (цвет, прозрачность)
  • layout properties (размещение, порядок)
  • filter expressions

Expressions API

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

'fill-color': [
  'interpolate',
  ['linear'],
  ['zoom'],
  5, '#f2f0f7',
  10, '#756bb1'
]

Используются для:

  • зависимости от zoom
  • классификации данных
  • условного форматирования

Events API

Mapbox GL JS предоставляет событийную модель:

  • load
  • click
  • mousemove
  • move
  • zoom
  • render

Пример:

map.on('click', 'city-layer', (e) => {
  console.log(e.features);
});

События позволяют:

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

Query API внутри карты

Mapbox GL JS позволяет выполнять запросы по отрисованным данным:

map.queryRenderedFeatures(point, {
  layers: ['city-fill']
});

Также доступен bounding box запрос:

map.queryRenderedFeatures(bbox);

Это используется для:

  • выделения объектов
  • аналитики видимой области
  • построения интерфейсов поверх карты

Camera API

Camera API управляет положением карты:

  • center
  • zoom
  • bearing
  • pitch

Пример:

map.flyTo({
  center: [77.0150, 43.3550],
  zoom: 12,
  pitch: 45,
  bearing: 20
});

Режимы:

  • jumpTo (мгновенное перемещение)
  • easeTo (плавная анимация)
  • flyTo (инерционная анимация)

Performance и кэширование API

Mapbox API оптимизированы через:

  • CDN для тайлов
  • кэширование стилей
  • компрессию векторных данных
  • батчинг запросов

Mapbox GL JS использует:

  • WebGL batching
  • tile caching
  • worker threads для парсинга данных

Ограничения и квоты API

Система API ограничивает:

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

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

Связь API и декларативного стиля

Главная особенность Mapbox заключается в декларативном подходе:

  • API поставляют данные
  • стиль описывает визуализацию
  • GL JS выполняет рендеринг

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

Оглавление