name: eptr2-consumption-data description: Query Turkish electricity consumption and demand forecast data including real-time consumption, UECM (settlement consumption/Uzlaştırmaya Esas Çekiş Miktarı), and load plan forecasts. Use when asking about electricity demand, consumption patterns, load forecasting, or UECM data in Turkey. Triggers on: elektrik tüketimi, talep tahmini, yük planı, UEÇM, consumption forecast. allowed-tools: Read, Bash(python:*)

Turkish Electricity Consumption Data with eptr2

Overview

This skill helps you query electricity consumption and demand forecast data from Turkey's EPIAS Transparency Platform using the eptr2 Python library.

Quick Start

from eptr2 import EPTR2

# Initialize with environment variables
eptr = EPTR2(use_dotenv=True, recycle_tgt=True)

# Get real-time consumption
rt_cons = eptr.call("rt-cons", start_date="2024-07-29", end_date="2024-07-29")
print(rt_cons)

Available Consumption Endpoints

Composite Function for Consumption Analysis

The composite function combines load plan, UECM, and real-time consumption:

from eptr2.composite import get_hourly_consumption_and_forecast_data

df = get_hourly_consumption_and_forecast_data(
    eptr,
    start_date="2024-07-29",
    end_date="2024-07-29",
    verbose=True  # Print progress
)

Output Columns

Understanding Consumption Data Types

Load Plan (Yük Planı)

• What: Day-ahead demand forecast published by TEIAS
• When: Available before delivery day
• Use: Planning and forecasting

Real-Time Consumption (Gerçek Zamanlı Tüketim)

• What: Actual measured consumption in near real-time
• When: Available ~15 minutes after each hour
• Use: Monitoring, real-time decisions

UECM (Uzlaştırmaya Esas Çekiş Miktarı)

• What: Official settlement consumption after meter reconciliation
• When: Available after settlement period (~T+10 days)
• Use: Settlement, billing, final analysis

Common Use Cases

1. Compare Forecast vs Actual

from eptr2.composite import get_hourly_consumption_and_forecast_data

df = get_hourly_consumption_and_forecast_data(
    eptr,
    start_date="2024-07-15",
    end_date="2024-07-15"
)

# Calculate forecast error
df['forecast_error'] = df['consumption'] - df['load_plan']
df['forecast_error_pct'] = (df['forecast_error'] / df['load_plan']) * 100

print(f"Average Forecast Error: {df['forecast_error'].mean():.2f} MWh")
print(f"MAPE: {df['forecast_error_pct'].abs().mean():.2f}%")

2. Daily Consumption Pattern

import pandas as pd

df = get_hourly_consumption_and_forecast_data(
    eptr,
    start_date="2024-07-15",
    end_date="2024-07-15"
)

df['dt'] = pd.to_datetime(df['dt'])
df['hour'] = df['dt'].dt.hour

# Peak consumption hour
peak_hour = df.loc[df['consumption'].idxmax()]
print(f"Peak Hour: {peak_hour['hour']}:00")
print(f"Peak Consumption: {peak_hour['consumption']:.2f} MWh")

3. Monthly Consumption Trends

df = get_hourly_consumption_and_forecast_data(
    eptr,
    start_date="2024-07-01",
    end_date="2024-07-31"
)

total_consumption = df['consumption'].sum()
print(f"Total July Consumption: {total_consumption:,.0f} MWh")
print(f"Daily Average: {total_consumption / 31:,.0f} MWh")

Date Format

Always use ISO format: YYYY-MM-DD (e.g., "2024-07-29")

Data Availability Notes

Authentication

Set credentials in .env file:

EPTR_USERNAME=your_email@example.com
EPTR_PASSWORD=your_password

For More Details

• See examples.md for additional code examples