Параметры запросов

В MapLibre GL JS все данные карты подгружаются динамически через сетевые запросы. Архитектура библиотеки построена вокруг потоковой загрузки тайлов, стилей, шрифтов и дополнительных ресурсов, поэтому контроль параметров HTTP-запросов является ключевым элементом интеграции с бэкендом, CDN и системами авторизации.

Базовая структура запросов к источникам данных

Каждый источник данных в стиле (sources) формирует собственный набор сетевых обращений. Основные типы ресурсов:

  • тайлы векторных и растровых слоёв
  • изображения спрайтов (sprite)
  • шрифты (glyphs)
  • стиль (style.json)
  • GeoJSON-данные

Пример источника:

{
  "sources": {
    "cities": {
      "type": "vector",
      "tiles": ["https://example.com/tiles/{z}/{x}/{y}.pbf"],
      "minzoom": 0,
      "maxzoom": 14
    }
  }
}

Каждый URL может содержать шаблонные параметры {z}, {x}, {y}, {bbox}. Они подставляются MapLibre автоматически в момент формирования запроса.

Шаблонные параметры URL

Координатные параметры тайлов

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

  • {z} — уровень масштабирования
  • {x} — координата тайла по оси X
  • {y} — координата тайла по оси Y
  • {quadkey} — альтернативный формат индексации (редко)

Пример:

https://tiles.server.com/{z}/{x}/{y}.mvt

BBOX-параметры

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

https://server.com/tiles?bbox={bbox}

Формат {bbox}:

minLon,minLat,maxLon,maxLat

Перехват и модификация запросов

MapLibre GL JS предоставляет механизм transformRequest, позволяющий изменять каждый сетевой запрос до его отправки.

const map = new maplibregl.Map({
  container: 'map',
  style: 'style.json',
  transformRequest: (url, resourceType) => {
    return {
      url: url,
      headers: {
        'Authorization': 'Bearer TOKEN'
      }
    };
  }
});

Параметры объекта transformRequest

Функция возвращает объект, который может содержать:

  • url — изменённый URL
  • headers — HTTP-заголовки
  • credentials — режим передачи cookies (same-origin, include, omit)
  • method — HTTP метод (GET/POST, редко используется)
  • body — тело запроса (для нестандартных API)

Управление заголовками HTTP

Частая задача — передача токенов, ключей доступа и служебных заголовков.

transformRequest: (url) => {
  return {
    url,
    headers: {
      'X-API-Key': 'abcdef123456',
      'X-Client': 'map-app'
    }
  };
}

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

  • приватными тайл-серверами
  • корпоративными WMS/WMTS
  • защищёнными vector tiles API

Параметры запросов источников данных

GeoJSON source

При использовании GeoJSONSource параметры запроса могут включать:

  • buffer
  • tolerance
  • cluster
  • clusterRadius
  • clusterMaxZoom

Пример:

map.addSource('points', {
  type: 'geojson',
  data: 'https://example.com/data.geojson',
  cluster: true,
  clusterRadius: 40
});

При удалённой загрузке MapLibre выполняет простой HTTP GET без дополнительной трансформации URL, если не задан transformRequest.

Vector source параметры

Для vector tiles важны параметры:

  • minzoom — минимальный zoom загрузки
  • maxzoom — максимальный zoom
  • tileSize — размер тайла (обычно 512 или 256)
  • bounds — географические ограничения загрузки
"bounds": [-180, -85.0511, 180, 85.0511]

Эти параметры уменьшают количество запросов за пределами области интереса.

Параметры кеширования запросов

MapLibre использует внутренний кеш тайлов, но поведение можно косвенно контролировать через HTTP заголовки:

  • Cache-Control
  • ETag
  • If-None-Match

Пример серверной настройки:

Cache-Control: public, max-age=86400

При корректной настройке серверных заголовков повторные запросы к тайлам не выполняются, а используется кеш браузера или MapLibre.

Параметры запроса спрайтов и шрифтов

Спрайты

Спрайты загружаются как два файла:

  • sprite.json
  • sprite.png

MapLibre автоматически добавляет суффиксы:

sprite@2x.json
sprite@2x.png

Для Retina-экранов.

Glyphs (шрифты)

Шрифты запрашиваются по шаблону:

https://server/fonts/{fontstack}/{range}.pbf

Параметры:

  • {fontstack} — список шрифтов через запятую
  • {range} — диапазон символов (например 0-255.pbf)

Параметры запроса при queryRenderedFeatures

Метод queryRenderedFeatures не выполняет HTTP-запросы, но использует уже загруженные тайлы. Однако параметры фильтрации влияют на выбор данных:

map.queryRenderedFeatures({
  layers: ['cities'],
  filter: ['==', 'type', 'capital']
});

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

  • layers — список слоёв
  • filter — выражение фильтра
  • geometry — ограничение по области
  • validate — включение проверки данных

Параметры querySourceFeatures

map.querySourceFeatures('cities', {
  sourceLayer: 'urban_areas',
  filter: ['>=', 'population', 1000000]
});

Параметры:

  • sourceLayer — имя слоя внутри векторного тайла
  • filter — фильтрация features
  • validate — проверка геометрии

Кастомизация параметров через query string

Некоторые серверы требуют дополнительные query-параметры:

https://tiles.server.com/{z}/{x}/{y}.pbf?token=abc123&lang=ru

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

transformRequest: (url) => {
  const u = new URL(url);
  u.searchParams.set('token', 'abc123');
  return { url: u.toString() };
}

Приоритеты обработки параметров

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

  1. URL из style.json
  2. Подстановка шаблонных параметров {z}/{x}/{y}
  3. transformRequest
  4. HTTP-кеширование
  5. Внутренний кеш MapLibre

Ограничения и особенности сетевой модели

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

Поведение при ошибках запросов

При ошибках HTTP:

  • 404 — тайл считается пустым
  • 403 — источник отключается до следующей перезагрузки
  • 500 — выполняется повторная попытка загрузки
  • timeout — запрос прерывается и может быть повторён

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

Эффективная настройка включает:

  • ограничение minzoom и maxzoom
  • использование bounds
  • уменьшение tileSize при необходимости
  • агрегацию параметров в CDN
  • применение HTTP кеширования

Пользовательские сценарии модификации запросов

Мультиарендный доступ

transformRequest: (url, type) => {
  return {
    url,
    headers: {
      'X-Tenant-ID': getTenantId()
    }
  };
};

Локализация данных

transformRequest: (url) => {
  const u = new URL(url);
  u.searchParams.set('lang', 'ru');
  return { url: u.toString() };
};

Переключение окружений

transformRequest: (url) => {
  return {
    url: url.replace('tiles.prod.com', 'tiles.dev.com')
  };
};

Итоговая модель параметров запросов

Сетевые обращения MapLibre GL JS формируются как комбинация:

  • шаблонов URL источников
  • динамических координатных параметров
  • пользовательской модификации через transformRequest
  • HTTP-заголовков и cookies
  • кеширующих механизмов браузера и библиотеки

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

Оглавление