Работа с Tile JSON

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

Tile JSON представляет собой JSON-документ, который описывает набор тайлов и параметры их загрузки. В экосистеме MapLibre GL JS он используется как конфигурационный слой для источников vector, raster и raster-dem.

Ключевая задача Tile JSON — стандартизировать описание источника так, чтобы рендерер мог:

  • построить URL-запросы к тайлам;
  • определить допустимые уровни масштабирования;
  • интерпретировать формат данных;
  • применить ограничения по области отображения;
  • использовать дополнительные метаданные (атрибуция, схема тайлов и др.).

Базовые поля Tile JSON

Типичный Tile JSON включает следующие поля:

tilejson

Версия спецификации. Например:

"tilejson": "3.0.0"

Это позволяет клиенту понимать, как интерпретировать документ.

tiles

Основной массив URL-шаблонов тайлов:

"tiles": [
  "https://example.com/tiles/{z}/{x}/{y}.pbf"
]

Поддерживаются переменные:

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

MapLibre GL JS использует эти шаблоны для динамического построения запросов при панорамировании и масштабировании карты.

vector_layers

Присутствует в векторных источниках и описывает слои внутри тайлов:

"vector_layers": [
  {
    "id": "roads",
    "fields": {
      "name": "String",
      "type": "String"
    }
  }
]

Это поле не обязательно для работы, но важно для инспекции данных и инструментов отладки.

minzoom и maxzoom

Ограничивают диапазон доступных уровней масштабирования:

"minzoom": 0,
"maxzoom": 14

При выходе за пределы этих значений клиент либо перестаёт запрашивать тайлы, либо использует кэшированные данные.

bounds

Географические границы источника:

"bounds": [-180, -85.0511, 180, 85.0511]

Формат: [west, south, east, north].

Используется для оптимизации запросов и предотвращения загрузки данных вне области покрытия.

center

Рекомендуемая точка центра и масштаб:

"center": [37.6173, 55.7558, 10]

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

scheme

Определяет схему нумерации тайлов:

"scheme": "xyz"

Основные варианты:

  • xyz — стандартная схема (y увеличивается вниз);
  • tms — обратная схема (y инвертирован).

MapLibre GL JS автоматически учитывает это поле при расчёте координат тайлов.

Подключение Tile JSON в MapLibre GL JS

Tile JSON может использоваться напрямую через параметр tiles или косвенно через url, указывающий на JSON-документ.

Вариант 1: прямое использование Tile JSON URL

map.addSource('terrain', {
  type: 'vector',
  url: 'https://example.com/tiles/tiles.json'
});

В этом случае MapLibre GL JS выполняет запрос к Tile JSON, извлекает параметры и начинает загрузку тайлов.

Вариант 2: инлайн-конфигурация

map.addSource('terrain', {
  type: 'vector',
  tiles: [
    'https://example.com/tiles/{z}/{x}/{y}.pbf'
  ],
  minzoom: 0,
  maxzoom: 14
});

Этот вариант фактически эквивалентен Tile JSON, но без отдельного HTTP-документа.

Типы источников и Tile JSON

Vector tiles

Для type: "vector" Tile JSON часто включает:

  • tiles
  • minzoom
  • maxzoom
  • vector_layers

Формат данных обычно Mapbox Vector Tile (MVT).

Пример:

{
  "tilejson": "3.0.0",
  "tiles": ["https://example.com/vectiles/{z}/{x}/{y}.pbf"],
  "minzoom": 0,
  "maxzoom": 14,
  "vector_layers": [
    {
      "id": "buildings",
      "fields": {
        "height": "Number"
      }
    }
  ]
}

Raster tiles

Для type: "raster" Tile JSON описывает изображение-тайлы:

{
  "tilejson": "3.0.0",
  "tiles": ["https://example.com/raster/{z}/{x}/{y}.png"],
  "minzoom": 0,
  "maxzoom": 18
}

Здесь отсутствует vector_layers, так как данные уже растеризованы.

Raster DEM

Используется для высотных данных:

{
  "tilejson": "3.0.0",
  "tiles": ["https://example.com/dem/{z}/{x}/{y}.png"],
  "encoding": "mapbox"
}

Дополнительное поле encoding определяет способ кодирования высот.

Механизм загрузки Tile JSON в MapLibre GL JS

При добавлении источника с url происходит следующий процесс:

  1. Запрос Tile JSON через HTTP.
  2. Парсинг конфигурации.
  3. Регистрация источника в внутреннем реестре.
  4. Построение tile grid на основе minzoom, maxzoom, scheme.
  5. Динамическая генерация запросов к tiles.

Особое значение имеет кэширование:

  • Tile JSON кэшируется отдельно от тайлов;
  • тайлы кэшируются по ключу {z}/{x}/{y} + URL;
  • повторные запросы минимизируются через внутренний cache system.

Поддержка шаблонов URL

Tile JSON поддерживает расширенные шаблоны:

Поддомены

"tiles": [
  "https://a.tiles.example.com/{z}/{x}/{y}.pbf",
  "https://b.tiles.example.com/{z}/{x}/{y}.pbf"
]

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

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

"tiles": [
  "https://example.com/{z}/{x}/{y}.pbf?api_key=TOKEN"
]

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

Обработка ошибок и fallback

MapLibre GL JS при работе с Tile JSON учитывает:

  • недоступность отдельных тайлов (HTTP 404/500);
  • частичную недоступность серверов;
  • превышение таймаутов.

В этих случаях используется:

  • повторный запрос (retry);
  • fallback на кэш;
  • пропуск тайла при невозможности загрузки.

CORS и требования к серверу

Tile JSON и тайлы должны корректно поддерживать CORS:

  • Access-Control-Allow-Origin обязателен для браузерного использования;
  • preflight-запросы могут возникать при авторизации;
  • отсутствие CORS приводит к блокировке загрузки.

Взаимодействие Tile JSON и Style JSON

Tile JSON редко используется изолированно. Обычно он подключается через стиль:

{
  "version": 8,
  "sources": {
    "my-vector": {
      "type": "vector",
      "url": "https://example.com/tiles.json"
    }
  },
  "layers": [
    {
      "id": "roads",
      "type": "line",
      "source": "my-vector",
      "source-layer": "roads"
    }
  ]
}

Здесь Tile JSON определяет инфраструктуру данных, а стиль — их визуализацию.

Производительность и оптимизация Tile JSON

Ключевые параметры, влияющие на производительность:

  • корректный minzoom снижает количество лишних запросов;
  • ограничение bounds уменьшает область загрузки;
  • использование CDN ускоряет доставку тайлов;
  • дробление слоёв внутри vector tiles уменьшает размер ответа;
  • балансировка через несколько доменов повышает параллелизм загрузки.

Частые ошибки при работе с Tile JSON

  • отсутствие версии tilejson;
  • некорректные шаблоны {z}/{x}/{y};
  • несоответствие схемы xyz и серверной логики;
  • отсутствие CORS-заголовков;
  • неверные границы bounds, приводящие к пустой карте;
  • слишком широкий maxzoom, создающий избыточные запросы.

Расширенные поля и нестандартные расширения

Некоторые Tile JSON реализации добавляют:

  • attribution — текст атрибуции данных;
  • description — описание слоя;
  • format — явное указание формата (pbf, png);
  • legend — визуальная легенда.

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

Оглавление