Uploads API

Uploads API в экосистеме Mapbox GL JS и платформы Mapbox предназначен для загрузки пользовательских геопространственных данных в облачное хранилище Mapbox с последующим использованием этих данных в стилях, тайлах и визуализациях. API реализует полный цикл работы с кастомными датасетами: от создания загрузочной сессии до получения готового tileset, доступного через стандартные Mapbox GL источники.

Основная идея Uploads API заключается в асинхронной обработке данных. Пользователь отправляет исходный файл (GeoJSON, Shapefile в виде .zip, KML и другие поддерживаемые форматы), система обрабатывает его на стороне сервера, валидирует геометрию, индексирует атрибуты и преобразует данные в формат векторных тайлов или растровых наборов, пригодных для быстрых запросов через WebGL-рендерер Mapbox GL JS.

Uploads API построен вокруг двух ключевых сущностей:

  • Upload Session — объект загрузки, описывающий процесс передачи файла
  • Tileset — конечный результат обработки данных

Поток обработки выглядит следующим образом:

  1. Создание загрузочной сессии
  2. Получение временных credentials для загрузки в S3
  3. Прямая загрузка файла в облачное хранилище
  4. Инициация обработки файла в Mapbox
  5. Асинхронная генерация tileset
  6. Проверка статуса обработки
  7. Использование tileset в Mapbox GL JS

Каждый этап контролируется через REST-запросы и имеет собственные ограничения и состояния.

Аутентификация и токены доступа

Uploads API требует использования Access Token с правами uploads:write и uploads:read. Эти токены привязаны к аккаунту Mapbox и определяют, какие ресурсы доступны для загрузки и чтения.

Типичный токен выглядит как строка:

pk.eyJ1IjoidXNlcm5hbWUiLCJhIjoiY2t...

Однако для серверных операций часто используется секретный токен sk.*, который позволяет создавать загрузочные сессии и инициировать обработку данных.

Важно учитывать, что Uploads API не предназначен для работы напрямую из браузера без промежуточного backend-сервиса, поскольку требует безопасного хранения секретного ключа.

Создание загрузочной сессии

Первый шаг — создание upload session через POST-запрос:

POST https://api.mapbox.com/uploads/v1/{username}

Тело запроса:

{
  "url": "https://example.com/data.geojson",
  "tileset": "username.my-dataset",
  "name": "my-dataset-upload"
}

Параметры:

  • url — публичный URL файла или S3 ссылка
  • tileset — идентификатор будущего tileset
  • name — человекочитаемое имя загрузки

Ответ API содержит уникальный идентификатор загрузки:

{
  "id": "cjuj5v7a100001fmx8s6f8s9d",
  "complete": false
}

Этот id используется для отслеживания статуса обработки.

Прямая загрузка через S3 credentials

В некоторых сценариях Uploads API возвращает временные AWS S3 credentials, позволяющие загрузить файл напрямую в облако Mapbox. Такой подход используется для больших файлов и снижает нагрузку на backend.

Структура credentials:

{
  "bucket": "mapbox",
  "key": "uploads/username/file.geojson",
  "accessKeyId": "...",
  "secretAccessKey": "...",
  "sessionToken": "...",
  "url": "https://mapbox.s3.amazonaws.com/uploads/..."
}

После получения этих данных файл загружается стандартным PUT-запросом в S3.

Асинхронная обработка данных

После загрузки файла начинается фаза обработки. Mapbox выполняет несколько внутренних операций:

  • валидация геометрии (self-intersections, invalid polygons)
  • нормализация координат
  • генерация векторных тайлов
  • построение пространственных индексов
  • оптимизация атрибутивных данных

Обработка выполняется асинхронно, поэтому Uploads API возвращает статусные данные.

Проверка статуса загрузки

Для отслеживания используется запрос:

GET https://api.mapbox.com/uploads/v1/{username}/{upload_id}

Пример ответа:

{
  "id": "cjuj5v7a100001fmx8s6f8s9d",
  "status": "processing",
  "tileset": "username.my-dataset"
}

Возможные состояния:

  • pending — ожидание обработки
  • processing — активная генерация tiles
  • complete — готово к использованию
  • failed — ошибка обработки

При статусе complete tileset становится доступным в Mapbox GL JS как источник данных.

Использование tileset в Mapbox GL JS

После завершения обработки данные подключаются как vector source:

map.addSource('custom-data', {
  type: 'vector',
  url: 'mapbox://username.my-dataset'
});

Далее источник используется в слоях:

map.addLayer({
  id: 'custom-layer',
  type: 'fill',
  source: 'custom-data',
  'source-layer': 'original-layer-name',
  paint: {
    'fill-color': '#3b9ddd',
    'fill-opacity': 0.6
  }
});

Ключевой момент заключается в том, что Uploads API не взаимодействует напрямую с Mapbox GL JS в runtime. Он лишь формирует tileset, который затем становится доступным через стандартную систему источников.

Ограничения и особенности форматов

Uploads API поддерживает несколько форматов входных данных:

  • GeoJSON
  • Shapefile (.zip)
  • KML
  • CSV с координатами
  • GPX (в некоторых конфигурациях)

Ограничения:

  • максимальный размер файла зависит от тарифа
  • геометрии должны быть валидными
  • координаты должны быть в WGS84 (EPSG:4326)
  • вложенные структуры GeoJSON могут требовать упрощения

При загрузке больших датасетов рекомендуется предварительная оптимизация:

  • упрощение геометрии (Douglas-Peucker)
  • удаление лишних атрибутов
  • разбиение на логические слои

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

Uploads API возвращает ошибки на нескольких уровнях:

  1. Ошибки создания upload session
  2. Ошибки загрузки в S3
  3. Ошибки валидации данных
  4. Ошибки генерации tileset

Типичный ответ ошибки:

{
  "message": "Invalid GeoJSON: Polygon ring is not closed",
  "error": "validation_error"
}

Ошибки обработки часто связаны с:

  • некорректной топологией геометрии
  • превышением лимитов на количество объектов
  • неподдерживаемыми типами геометрий
  • нарушением структуры FeatureCollection

Версионирование tileset и перезапись данных

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

Механизм позволяет безопасно обновлять карты без промежуточных состояний:

  • загрузка новой версии
  • обработка
  • автоматическое переключение источника

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

На производительность tileset влияет:

  • плотность геометрий
  • количество атрибутов
  • уровень генерации тайлов
  • пространственное распределение объектов

Оптимизация включает:

  • снижение детализации на низких зумах
  • агрегацию точек
  • использование кластеризации
  • разделение больших слоёв на несколько tileset’ов

Mapbox GL JS эффективно использует эти данные через WebGL-рендеринг, минимизируя нагрузку на клиент.

Интеграция с пайплайнами данных

Uploads API часто используется в автоматизированных системах:

  • CI/CD для геоданных
  • ETL-процессы GIS
  • обновление картографических слоёв в реальном времени
  • аналитические панели

Типичный пайплайн:

  1. сбор данных (сенсоры, API, GIS)
  2. преобразование в GeoJSON
  3. загрузка через Uploads API
  4. обновление tileset
  5. рендеринг в Mapbox GL JS

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

Оглавление