Smart Parking API (v2)

Базовый URL: https://api.parktrack.live

API предоставляет доступ к системе интеллектуального поиска парковок, которая агрегирует данные из различных источников (камеры, внешние API и будущие интеграции) для определения текущей и прогнозируемой занятости парковок.

---

Основные принципы

1. Модульная архитектура

API разделён на независимые модули:

• Основные сущности (cameras, parking_zones)
• Данные во времени (occupancy, forecasts)
• Навигация (routing)
• Доступ и авторизация (auth, users, subscriptions, partners)
• Интеграции (data_sources)

Это позволяет масштабировать систему без ломки существующего функционала.

---

2. Обратная совместимость (MVP-first)

Существующие эндпоинты (cameras, parking_zones) сохраняются, чтобы не ломать текущие интеграции.

Новая функциональность добавляется в отдельных разделах.

---

3. Разделение данных по времени

В системе явно разделены:

• Статические данные → камеры, зоны
• Динамические данные → занятость (история и текущее состояние)
• Предсказания → прогнозы

---

4. Поддержка нескольких источников данных

Система проектируется с учётом разных источников:

• Камеры (MVP)
• Парктроники (в будущем)
• Навигационные данные (в будущем)
• Данные об оплатах (в будущем)

Каждый источник может иметь разный уровень достоверности.

---

Формат времени

Все временные значения передаются в формате UTC ISO 8601:

2025-10-08T09:12:00Z

---

Авторизация

Большинство эндпоинтов требуют заголовок:

Authorization: Bearer <token>

Типы токенов:

• Системный токен
• Пользовательский токен
• Партнёрский токен

---

Общие ошибки

Код	Тип	Описание
400	Bad Request	Невалидный JSON или типы данных
401	Unauthorized	Отсутствует или неверный токен
403	Forbidden	Недостаточно прав
404	Not Found	Ресурс не найден
415	Unsupported Media Type	Используй application/json
422	Unprocessable Entity	Ошибка валидации
500	Internal Server Error	Ошибка сервера
503	Service Unavailable	Сервис временно недоступен

Пример ответа с ошибкой:

{
  "error_description": "Unsupported Media Type: expected application/json"
}

---

Разделы API

Основные сущности

• Cameras
• Parking Zones

Данные о занятости

• Occupancy (история и текущее состояние)
• Forecasts (прогнозы)

Навигация

• Routing (поиск парковки и построение маршрутов)

Доступ

• Auth
• Users
• Subscriptions
• Partners

Интеграции

• Data Sources

Дополнительно

• Feedback
• Admin
• Analytics
• System

---

Версионирование

Текущая версия API: v1 (MVP+)

В будущем изменения будут вводиться без ломки существующих эндпоинтов.

---

Планируемые расширения

• ML-прогнозирование занятости парковок
• Выбор оптимальной парковки с учётом ETA
• Реалтайм-мониторинг камер и распознавания
• Интеграция с внешними источниками данных (навигация, каршеринг, оплаты)

---