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

Источники запросов и их базовая структура

Mapbox GL JS работает как клиент, который динамически формирует множество HTTP-запросов к различным сервисам и ресурсам. Каждый тип источника данных (tiles, styles, sprites, glyphs, GeoJSON) использует собственный набор параметров, определяющих содержимое ответа и поведение сервера.

Основная особенность архитектуры — разделение запросов на несколько категорий:

  • загрузка стиля (Style JSON)
  • загрузка тайлов (vector / raster / terrain)
  • получение шрифтов (glyphs)
  • получение изображений (sprites)
  • запросы к GeoJSON источникам
  • интерактивные запросы (queryRenderedFeatures, querySourceFeatures)

Каждый из этих запросов имеет собственный набор параметров, но все они подчиняются общей модели HTTP-формирования URL и конфигурации через API Mapbox GL JS.

Параметры загрузки стиля

Стиль карты представляет собой JSON-документ, который загружается первым и определяет всю структуру визуализации.

Типичный запрос:

https://api.mapbox.com/styles/v1/{username}/{style_id}?access_token=...

Основные параметры:

access_token

  • обязательный параметр
  • используется для авторизации
  • передаётся как query string

fresh

  • управляет кешированием стиля
  • используется при необходимости принудительной загрузки обновлённого JSON

optimize

  • включает серверную оптимизацию стиля
  • может уменьшать размер ответа

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

Тайлы являются основным источником геоданных (vector tiles, raster tiles).

Шаблон URL:

https://api.mapbox.com/v4/{tileset_id}/{z}/{x}/{y}.vector.pbf?access_token=...

Ключевые параметры:

z / x / y

  • координаты тайла в системе Web Mercator
  • z — уровень масштаба
  • x, y — позиция тайла

limit

  • ограничение количества объектов (в некоторых API)
  • используется для серверной фильтрации

geometry

  • определяет, какие геометрии возвращать:

    • point
    • line
    • polygon
    • all

buffer

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

layer

  • выбор конкретного слоя внутри векторного тайлсета

Параметры GeoJSON источников

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

source: {
  type: "geojson",
  data: "https://example.com/data.geojson"
}

Возможные параметры запроса:

data

  • URL или объект GeoJSON
  • может быть динамически обновляемым через setData()

cluster

  • включает кластеризацию точек

  • серверные и клиентские параметры:

    • cluster_radius
    • cluster_max_zoom

buffer

  • добавляет запас при тайлизации GeoJSON

tolerance

  • влияет на упрощение геометрии

Параметры запросов glyphs (шрифты)

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

https://api.mapbox.com/fonts/v1/{username}/{fontstack}/{range}.pbf

Основные параметры:

fontstack

  • набор шрифтов (например, “Open Sans Regular”)

range

  • диапазон символов Unicode
  • формат: 0-255, 256-511

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

Sprites используются для иконок и UI-элементов карты:

https://api.mapbox.com/styles/v1/{style_id}/sprite.png
https://api.mapbox.com/styles/v1/{style_id}/sprite@2x.json

Параметры:

@2x

  • высокое разрешение (retina-дисплеи)

format

  • png / json
  • JSON описывает координаты спрайтов

TransformRequest: контроль параметров запроса

Ключевой механизм кастомизации HTTP-запросов в Mapbox GL JS — функция transformRequest.

Она позволяет изменять каждый исходящий запрос:

transformRequest: (url, resourceType) => {
  return {
    url: url,
    headers: {
      'X-Custom-Header': 'value'
    },
    credentials: 'include'
  };
}

Возможности transformRequest:

Добавление query-параметров

  • динамическое добавление токенов
  • трекинг параметров
  • A/B тестирование

Изменение заголовков

  • авторизация через Bearer tokens
  • кастомные метаданные

Переопределение URL

  • проксирование через собственный сервер
  • подмена endpoint’ов

Параметры queryRenderedFeatures и querySourceFeatures

Эти методы не формируют HTTP-запрос напрямую, но работают с уже загруженными данными.

queryRenderedFeatures

Используется для выборки объектов на экране:

map.queryRenderedFeatures(point, {
  layers: ['cities']
});

Параметры:

layers

  • фильтрация по слоям

filter

  • выражение фильтра Mapbox GL

geometry

  • область поиска (point, bbox)

querySourceFeatures

Работает с исходными тайлами:

map.querySourceFeatures('my-source', {
  sourceLayer: 'buildings'
});

Параметры:

sourceLayer

  • слой внутри векторного источника

filter

  • выражения фильтрации

Параметры фильтрации выражений (filter expressions)

Фильтры являются частью query-логики и применяются к данным после загрузки.

Пример:

["==", ["get", "type"], "park"]

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

  • ==
  • !=
  • >
  • <
  • in
  • all
  • any

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

Параметры загрузки ресурсов через API Mapbox

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

Общие параметры API:

access_token

  • основной механизм авторизации

sku

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

session_token

  • связывает последовательность запросов

language

  • локализация подписей

geometry

  • тип возвращаемой геометрии

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

Mapbox GL JS активно использует кеширование, и параметры запросов могут влиять на него:

cache-control (серверный)

  • max-age
  • no-cache
  • public / private

URL fingerprinting

  • изменение query string приводит к обходу кеша

ETag

  • используется для проверки актуальности тайлов

Параметры tiled JSON и vector tiles

Vector tiles используют бинарный формат PBF и поддерживают дополнительные параметры:

layers

  • выбор слоёв внутри тайла

extent

  • координатная система внутри тайла (обычно 4096)

simplify

  • упрощение геометрии

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

При обновлении данных через runtime API:

map.getSource('points').setData(newData);

Используемые параметры:

type

  • geojson / vector / raster

cluster options

  • cluster, clusterRadius, clusterMaxZoom

promoteId

  • определение уникального идентификатора

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

При работе через transformRequest часто реализуются:

CORS handling

  • добавление credentials
  • прокси-заголовки

token rotation

  • динамическая смена access_token

signed URLs

  • добавление подписи к URL (HMAC)

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

В Mapbox GL JS существуют косвенные параметры, влияющие на количество и частоту запросов:

maxZoom / minZoom

  • ограничение уровня детализации

tileSize

  • влияет на количество тайлов

reparse geometry

  • управление перерасчётом данных

promoteId

  • ускоряет доступ к feature properties

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

При обработке событий карты:

map.on('click', (e) => {
  map.queryRenderedFeatures(e.point);
});

Используются параметры:

point

  • координаты клика

bbox

  • ограничивающая рамка

layers

  • фильтрация по слоям

Параметры URL-конструкции в стиле Mapbox

Стиль Mapbox GL JS — это композиция множества URL-параметров:

  • sprite URL
  • glyphs URL
  • sources tiles URL
  • layers configuration

Каждый URL может включать:

template parameters

  • {z}, {x}, {y}
  • {bbox-epsg-3857}
  • {access_token}

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

В защищённых конфигурациях используются:

signature

  • криптографическая подпись запроса

expires

  • время жизни URL

policy

  • ограничения доступа

Эти параметры часто генерируются серверной частью и передаются в Mapbox GL JS как часть URL.

Оглавление