Dataset API

Dataset API в экосистеме Mapbox представляет собой серверный REST-интерфейс для хранения, редактирования и управления геоданными в формате GeoJSON. Данные организуются в виде датасетов (datasets), каждый из которых содержит набор объектов Feature с геометрией и свойствами.

Ключевая особенность Dataset API — работа на уровне отдельных геообъектов, а не тайлов. Это делает его удобным для сценариев, где требуется частое обновление точечных или полигональных данных без пересборки тайлсетов.

Dataset API не является частью Mapbox GL JS напрямую, но тесно интегрируется с ним через GeoJSON source.

Модель данных Dataset API

Каждый dataset представляет собой коллекцию GeoJSON Feature-объектов:

  • FeatureCollection — контейнер верхнего уровня

  • Feature — отдельный объект с:

    • geometry (Point, LineString, Polygon)
    • properties (произвольные атрибуты)
    • id (уникальный идентификатор)

Пример структуры:

{
  "type": "Feature",
  "id": "poi-123",
  "geometry": {
    "type": "Point",
    "coordinates": [69.2401, 41.2995]
  },
  "properties": {
    "name": "Object A",
    "category": "warehouse"
  }
}

Dataset хранит такие объекты независимо от визуализации и тайловой структуры.

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

Все запросы к Dataset API требуют access token. Он передаётся через query parameter:

https://api.mapbox.com/datasets/v1/{username}?access_token=YOUR_TOKEN

или в конкретных операциях:

https://api.mapbox.com/datasets/v1/{username}/{dataset_id}/features/{feature_id}?access_token=YOUR_TOKEN

Dataset API работает поверх HTTP методов:

  • GET — получение данных
  • POST — создание dataset или feature
  • PUT — полное обновление feature
  • PATCH — частичное обновление (в некоторых реализациях ограничено)
  • DELETE — удаление dataset или feature

Создание и управление датасетами

Создание dataset

POST /datasets/v1/{username}?access_token=TOKEN

Body:

{
  "name": "logistics_points",
  "description": "Склады и точки доставки"
}

Ответ возвращает dataset_id, который используется далее для операций.

Получение списка datasets

GET /datasets/v1/{username}?access_token=TOKEN

Возвращает массив доступных наборов данных с метаданными.

Удаление dataset

DELETE /datasets/v1/{username}/{dataset_id}?access_token=TOKEN

Удаляет весь набор данных вместе с объектами.

Работа с Feature-объектами

Добавление объекта

PUT /datasets/v1/{username}/{dataset_id}/features/{feature_id}?access_token=TOKEN

Body:

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [69.2401, 41.2995]
  },
  "properties": {
    "name": "Warehouse 12",
    "capacity": 3400
  }
}

Feature с указанным feature_id создаётся или заменяется полностью.

Получение объекта

GET /datasets/v1/{username}/{dataset_id}/features/{feature_id}?access_token=TOKEN

Возвращает один GeoJSON Feature.

Получение всех объектов

GET /datasets/v1/{username}/{dataset_id}/features?access_token=TOKEN

Возвращает FeatureCollection.

Удаление объекта

DELETE /datasets/v1/{username}/{dataset_id}/features/{feature_id}?access_token=TOKEN

Удаляет конкретный геообъект без затрагивания остальных данных.

Обновление данных и стратегия синхронизации

Dataset API не обеспечивает автоматическую синхронизацию с картой. Обновления должны быть явно загружены в Mapbox GL JS.

Типовой сценарий:

  1. Обновление feature через Dataset API
  2. Повторная загрузка GeoJSON
  3. Обновление источника карты

Интеграция с Mapbox GL JS

Dataset API сам по себе не отображает данные. Визуализация происходит через GeoJSON source в Mapbox GL JS.

Создание источника карты

map.addSource('dataset-source', {
  type: 'geojson',
  data: 'https://api.mapbox.com/datasets/v1/username/dataset_id/features?access_token=TOKEN'
});

Источник напрямую привязан к HTTP-ответу Dataset API.

Отображение слоя

map.addLayer({
  id: 'dataset-layer',
  type: 'circle',
  source: 'dataset-source',
  paint: {
    'circle-radius': 6,
    'circle-color': '#ff5200'
  }
});

Все объекты dataset отображаются как геометрии GeoJSON.

Обновление данных на карте

Dataset API не пушит изменения в Mapbox GL JS автоматически, поэтому используется ручное обновление источника.

Перезагрузка данных

const source = map.getSource('dataset-source');

fetch('https://api.mapbox.com/datasets/v1/username/dataset_id/features?access_token=TOKEN')
  .then(res => res.json())
  .then(data => {
    source.setData(data);
  });

Метод setData полностью заменяет содержимое источника.

Ограничения Dataset API

Dataset API ориентирован на умеренные объёмы данных и имеет ряд ограничений:

  • Не предназначен для больших геоданных (миллионы объектов)
  • Отсутствует пространственная индексация на клиенте
  • Ограничена производительность при частых обновлениях
  • Не заменяет vector tiles pipeline

Для высоконагруженных сценариев используется Tilesets API и предварительная генерация тайлов.

Типовые сценарии применения

Динамические точки интереса

Dataset API подходит для систем, где точки регулярно добавляются или изменяются:

  • логистика и трекинг
  • диспетчеризация транспорта
  • оперативные метки событий

Редактируемые карты

Dataset может выступать как backend для:

  • пользовательских аннотаций
  • редактируемых слоёв
  • внутренних GIS-инструментов

Интеграция с внешними сервисами

Часто Dataset API используется как промежуточное хранилище между:

  • CRM системами
  • IoT платформами
  • backend сервисами аналитики

Данные синхронизируются через серверные скрипты, после чего обновляются на карте через GeoJSON source.

Структура типового цикла обновления данных

  1. Внешний сервис формирует новые координаты объектов
  2. Backend отправляет PUT или POST в Dataset API
  3. Mapbox GL JS периодически запрашивает GeoJSON
  4. Source обновляется через setData
  5. Слой перерисовывается на клиенте

Работа с идентификаторами объектов

Feature ID играет ключевую роль в обновлении данных:

  • одинаковый id → замена объекта
  • новый id → добавление нового объекта
  • отсутствие id → невозможность точечного обновления

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

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

При работе с Dataset API и Mapbox GL JS важны следующие практики:

  • минимизация частоты setData
  • агрегация обновлений на сервере
  • ограничение количества Feature в одном dataset
  • использование кластеризации на стороне Mapbox GL JS
  • кэширование GeoJSON ответов

Безопасность доступа

Access token определяет уровень доступа:

  • public tokens — только чтение
  • secret tokens — полный доступ к Dataset API

Использование secret token на клиенте недопустимо, так как даёт возможность модификации данных.

Связь Dataset API с другими компонентами Mapbox

Dataset API часто используется вместе с:

  • GeoJSON sources в Mapbox GL JS
  • Tilesets API для публикации больших наборов данных
  • Mapbox Studio для визуального редактирования
  • Server-side обработкой геоданных

Dataset API выступает как промежуточный слой между сырой геоинформацией и визуализацией на карте.

Оглавление