Static Images API в экосистеме Mapbox используется для генерации статических изображений карт на основе заданных параметров запроса. В отличие от интерактивного рендеринга в браузере через Mapbox GL JS, данный интерфейс возвращает готовое изображение карты (PNG, JPEG или WebP), которое можно использовать в любых контекстах, где отсутствует необходимость в динамическом взаимодействии: отчёты, email-рассылки, серверные рендеры, предпросмотр объектов, генерация миниатюр и печатные материалы.
Ключевая особенность заключается в том, что визуализация карты формируется на стороне серверов Mapbox, что позволяет снизить нагрузку на клиентскую часть и обеспечить стабильный результат рендеринга вне зависимости от окружения выполнения.
Запрос к Static Images API формируется через HTTP GET и имеет следующий общий вид:
https://api.mapbox.com/styles/v1/{username}/{style_id}/static/{overlay}/{lon},{lat},{zoom},{bearing},{pitch}/{width}x{height}@{scale}?access_token=YOUR_MAPBOX_ACCESS_TOKENКаждый сегмент URL определяет отдельный аспект изображения, начиная от стиля карты и заканчивая параметрами камеры и разрешением выходного файла.
style_id Идентификатор стиля карты, созданного в Mapbox Studio или использующего стандартные стили Mapbox. Определяет визуальное оформление: цвета, слои, шрифты, иконки.
overlay Дополнительные элементы, накладываемые поверх карты:
lon, lat Центр карты в координатах долготы и широты. Определяет географическую область изображения.
zoom Масштаб отображения. Значения обычно варьируются от 0 (вся планета) до 22 (максимальная детализация улиц).
bearing Поворот карты относительно севера. Значение в градусах.
pitch Наклон камеры. Используется для создания псевдо-3D перспективы.
width x height Размер изображения в пикселях. Максимальные значения зависят от тарифного плана, но обычно ограничены серверными лимитами.
scale (@2x) Множитель плотности пикселей. Используется для Retina-дисплеев и высокодетализированных изображений.
Несмотря на то, что API работает через HTTP, в контексте Mapbox GL JS часто требуется динамическая генерация URL.
Пример базовой генерации ссылки:
const accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';
const url = `https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/` +
`-74.0060,40.7128,12,0,0/800x600@2x` +
`?access_token=${accessToken}`;Полученный URL можно использовать как источник изображения:
const img = document.createElement('img');
img.src = url;
document.body.appendChild(img);Static Images API поддерживает добавление простых визуальных элементов поверх карты через overlay-синтаксис.
Маркер задаётся в URL с помощью конструкции:
pin-s+ff0000(lon,lat)Пример:
const marker = 'pin-s+ff0000(-74.0060,40.7128)';
const url = `https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/` +
`${marker}/-74.0060,40.7128,12/800x600?access_token=${accessToken}`;Для более сложных сценариев используется кодирование геометрии в polyline или GeoJSON encoding.
Пример линии маршрута:
const path = 'path-5+f44-0.5(%7Bencoded_polyline%7D)';В реальных проектах чаще применяется предварительное кодирование геометрии на сервере, поскольку API ожидает компактное представление данных.
Хотя Mapbox GL JS предназначен для интерактивных карт, Static Images API часто используется как вспомогательный инструмент для генерации превью текущего состояния карты.
Пример извлечения параметров из интерактивной карты:
map.on('moveend', () => {
const center = map.getCenter();
const zoom = map.getZoom();
const bearing = map.getBearing();
const pitch = map.getPitch();
const width = 800;
const height = 600;
const url = `https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/` +
`${center.lng},${center.lat},${zoom},${bearing},${pitch}` +
`/${width}x${height}@2x` +
`?access_token=${accessToken}`;
document.getElementById('preview').src = url;
});Такой подход позволяет синхронизировать статическое изображение с состоянием интерактивной карты.
Static Images API часто применяется в серверных сценариях, где требуется формировать изображения карт без браузера.
Пример на Node.js:
import fetch from 'node-fetch';
import fs from 'fs';
const url = 'https://api.mapbox.com/styles/v1/mapbox/light-v11/static/' +
'-73.9857,40.7484,14/1024x768?access_token=YOUR_MAPBOX_ACCESS_TOKEN';
const response = await fetch(url);
const buffer = await response.arrayBuffer();
fs.writeFileSync('map.png', Buffer.from(buffer));Такой подход используется для:
Static Images API имеет ряд технических ограничений, связанных с серверным рендерингом:
Также следует учитывать, что сложные слои (например, большое количество маркеров или сложные GeoJSON-объекты) могут увеличивать время генерации изображения.
Ответы Static Images API могут кэшироваться на уровне CDN, если URL остаётся неизменным. Это означает, что идентичные запросы часто возвращаются быстрее за счёт повторного использования ранее сгенерированного изображения.
Для эффективного использования рекомендуется:
Static Images API напрямую использует те же стили, что и Mapbox GL JS. Это обеспечивает визуальную консистентность между интерактивной и статической картой.
Пример использования пользовательского стиля:
const styleId = 'username/custom-style-id';
const url = `https://api.mapbox.com/styles/v1/${styleId}/static/` +
`-122.4194,37.7749,13/900x700` +
`?access_token=${accessToken}`;Изменение стиля автоматически отражается как в интерактивной карте, так и в статических изображениях, что позволяет централизованно управлять визуальной системой.
Static Images API используется в системах, где карта выступает как визуальный компонент данных:
Во всех этих случаях статическая карта выступает как финальный визуальный слой, не требующий пользовательского взаимодействия, но сохраняющий географическую точность и стилистику Mapbox.