SpotBot — IoT Smart Parking with ML-Powered Demand Forecasting

SpotBot is a full-stack smart parking platform for multi-zone facilities (modeled after Navi Mumbai International Airport). It combines a React web app, a Django REST API, IoT sensor integration, and a machine learning pipeline that predicts parking occupancy and drives dynamic pricing and area recommendations.

Not just a booking app — predictions are trained on historical occupancy data and served in real time through the API.

---

Highlights

• ML occupancy forecasting — Random Forest regressor predicts occupancy % per parking zone
• Data-driven recommendations — suggests the least crowded area for a chosen time window
• Dynamic pricing — booking price scales with predicted demand (occupancy tiers)
• End-to-end data science workflow — dataset → preprocessing → training → evaluation → model export → API inference
• IoT-ready — hardware channels and live sensor status via REST (/api/hardware/update/)
• Full product features — auth, reservations, admin dashboard, handicap verification, payment flow

---

Machine Learning & Data Science

Problem

Predict parking occupancy percentage for each zone given temporal context, so users can book where availability is highest and pricing reflects expected demand.

Dataset

Property	Value
File	backend/spotbot_historical_data.csv
Records	12,966 historical occupancy snapshots
Zones	6 parking areas (Area_A … Area_F)
Features	timestamp, area, day_of_week, hour, is_weekend, occupied_spots, available_spots
Target	occupancy_percentage (0–100%)

Preprocessing

• Load and validate schema with pandas
• One-hot encode parking zones (area → area_Area_A, area_Area_B, …)
• Drop leakage columns (occupied_spots, available_spots) from training features
• 80/20 train/test split (random_state=42)

Model

Item	Detail
Algorithm	Random Forest Regressor (scikit-learn)
Trees	200 estimators
Features	9 (temporal + one-hot area columns)
Metrics	R² = 0.89, MAE ≈ 7.6% occupancy points
Serialization	joblib → parking_model.pkl, model_features.pkl
Metadata	backend/model_metadata.json

Model performance

Training pipeline (train_model.py):

Metric	Value
R² score	0.887
MAE	7.64%

Extended analysis (generate_model_graphs.py, time-based 80/20 split):

Metric	Value
R² score	0.891
MAE	7.53%
RMSE	8.86%

Training

cd backend
.venv\Scripts\activate        # Windows
python train_model.py

Model analysis

cd backend
pip install matplotlib        # if not already installed
python generate_model_graphs.py

Charts are saved to backend/model_performance_graphs/ (copies in docs/ml/ for the README).

Inference (production path)

1. User selects a time block in the ML Dashboard (React)
2. Frontend calls POST /api/predict/ with start_time and end_time
3. Django loads the joblib model and builds feature rows per area (hour, day_of_week, is_weekend, one-hot area)
4. Model returns predicted_occupancy per zone
5. Dynamic price is computed from duration + occupancy tier:
   • < 40% occupancy → 0.8× multiplier
   • 40–80% → 1.0×
   • > 80% → 1.5× (surge-style pricing)
6. UI highlights the recommended area (lowest predicted occupancy)

The same prediction logic is reused at booking time to price reservations consistently.

---

Tech Stack

Layer	Technologies
Frontend	React 19, Vite 8, React Router 7, Tailwind CSS 4
Backend	Python 3.14, Django 6, Django REST Framework
Database	SQLite
ML / Data	pandas, NumPy, scikit-learn, joblib, matplotlib
IoT	REST hardware endpoints (ESP32-ready)

---

Architecture

Historical CSV  →  train_model.py  →  .pkl artifacts
                                              ↓
User (ML Dashboard)  →  POST /api/predict/  →  Random Forest inference
                                              ↓
                         Occupancy + dynamic price  →  Booking flow
                                              ↓
                    ESP32 sensors  →  POST /api/hardware/update/

---

Project Structure

SpotBot/
├── spotbot/          # React frontend (Vite)
├── backend/          # Django API + ML scripts
│   ├── api/          # REST endpoints, models, serializers
│   ├── train_model.py
│   ├── generate_model_graphs.py
│   └── spotbot_historical_data.csv
├── docs/ml/          # Model evaluation charts
└── package.json      # Root workspace scripts

---

Getting Started

Prerequisites

• Node.js 18+
• Python 3.12+

Backend

cd backend
python -m venv .venv
.venv\Scripts\activate          # Windows
pip install django djangorestframework django-cors-headers pandas scikit-learn joblib

python train_model.py             # train model (required for /api/predict/)
python manage.py migrate
python manage.py runserver

API runs at http://127.0.0.1:8000

Frontend

From the repo root:

npm install
npm run dev

App runs at http://localhost:5173 (proxies /api to Django on port 8000).

---

API Overview

Endpoint	Description
POST /api/predict/	ML occupancy predictions + dynamic pricing
POST /api/booking/	Create a reservation
GET /api/spots/	List parking spots
POST /api/hardware/update/	Ingest IoT sensor occupancy
GET /api/hardware/status/	Hardware channel status
POST /api/auth/login/	Session authentication

---

What I Built (Portfolio Summary)

• Designed an occupancy forecasting pipeline from raw CSV to deployed API inference
• Implemented feature engineering (temporal + categorical encoding) aligned between training and serving
• Integrated ML output into product UX: recommendations, surge pricing, and booking
• Built model evaluation visuals (actual vs predicted, error distribution, feature importance)
• Delivered a full-stack IoT parking platform, not an isolated notebook

---

License

MIT