LoadCast

An end-to-end system for forecasting hourly electricity consumption on the Turkish grid: data collection from the EPİAŞ Transparency Platform, weather integration, a LightGBM-based forecasting model, and a live dashboard.

Live: loadcast.omerharmankaya.com

The model targets beating EPİAŞ's own official load plan (load_plan) across all segments — weekdays, weekends, and official holidays included.

Results

Segment	Model (MAPE %)	EPİAŞ official plan (MAPE %)
Overall	2.19	2.63
Holidays (LOHO, 47 days)	4.58	5.02

Holiday forecasting is done with a hybrid engine that combines the official holiday calendar with holiday profiles learned from the data (model/holiday_profile.py). See backend/model/FAZ*_SONUC.md for detailed experiment logs.

Architecture

EPİAŞ API ──┐
            ├──> SQLite ──> feature engineering ──> LightGBM ──> model_forecast
Open-Meteo ─┘                                                     │
                                                                  v
                                                   FastAPI ──> React dashboard

Components

Directory	Responsibility
backend/pipeline/	EPİAŞ data ingestion (eptr2), normalization, SQLite schema
backend/weather/	Population-weighted temperature for 6 cities from Open-Meteo
backend/model/	Feature engineering, training, forecasting, holiday engine, validation
backend/api/	FastAPI — dashboard and portfolio embed endpoints
frontend/	React + TypeScript + Vite, lightweight-charts

Data layer

Seven tables in SQLite: hourly consumption, generation, price, EPİAŞ load plan, weather, model forecasts, and intraday run logs.

An important detail: EPİAŞ's real-time consumption data (rt-cons) arrives incomplete when first published and is revised upward for ~6 hours. For this reason, accuracy metrics are only computed over "matured" hours (MATURITY_HOURS = 6).

Model

LightGBM regression. Main features: calendar (hour, day, month, cyclical encoding), population-weighted temperature and its derivatives, holiday indicators, and holiday profiles learned from the data.

Critical constraint: EPİAŞ's own load plan (lep) is never fed into the model as a feature — it is used only as a comparison benchmark. The goal is not to replicate the official plan, but to independently beat it.

Setup

Backend

cd backend
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

Put your EPİAŞ Transparency Platform credentials in a .env file at the project root (this file is not tracked by git):

EPTR_USERNAME=your@email.com
EPTR_PASSWORD=your_password

Initial data backfill and model training:

python3 pipeline/backfill.py
python3 weather/weather_backfill.py
python3 model/train.py

Run the API:

uvicorn backend.api.main:app --reload --port 8010

Frontend

cd frontend
npm install
npm run dev

The API address is configured via VITE_API_BASE (default http://localhost:8010).

Configuration

All environment-specific settings are provided via environment variables; there are no hardcoded values in the code.

Variable	Description	Default
EPTR_USERNAME / EPTR_PASSWORD	EPİAŞ Transparency Platform login	—
ALLOWED_ORIGINS	CORS-allowed origins (comma-separated)	http://localhost:5173,http://localhost:3000
VITE_API_BASE	API root used by the frontend	http://localhost:8010

API

Endpoint	Returns
GET /api/current	Consumption/generation/price for the latest hour
GET /api/series	Time series of consumption, official plan, and model forecast
GET /api/live-comparison	Model vs. official comparison for the latest matured hour
GET /api/day/{day}	Hourly breakdown and deviations for a single day
GET /api/accuracy	Segment-level MAPE table
GET /api/generation, /api/price	Generation and price time series
GET /api/embed/*	Simplified endpoints for portfolio embedding

Automation

Runs on scheduled jobs in production: hourly data sync, daily weather forecast fetching, nightly model training and forecast generation, and intraday forecast updates twice a day.

model/check_live.py validates the health of the live system — including data freshness, forecast coverage, and weather data integrity.

Data sources

• EPİAŞ Transparency Platform — via the eptr2 client (requires an account)
• Open-Meteo — historical and forecast temperature (no key required)