pyepias

UNOFFICIAL LIBRARY - NOT AFFILIATED WITH EPİAŞ

This is an UNOFFICIAL third-party library and is NOT officially associated with EPİAŞ (Enerji Piyasaları İşletme A.Ş.). Use at your own risk.

A Python client library for accessing EPİAŞ (Turkish Electricity Market) transparency platform data.

Overview

pyepias provides a simple and intuitive interface to fetch electricity market data from the EPİAŞ (Enerji Piyasaları İşletme A.Ş.) transparency platform. This library handles authentication and data retrieval, making it easy to access market clearing prices and other electricity market data.

Features

• Automatic authentication with EPİAŞ platform
• Fetch Market Clearing Price (MCP) data
• Support for multiple time periods:
  • today: Today's full 24-hour data (when published)
  • week: Last 7 complete days
  • month: Last 30 complete days
  • Custom date ranges: Any start/end date combination
• Built-in statistical analysis
• Pandas DataFrame integration
• JSON export support

Installation

From PyPI (when published)

pip install pyepias

From source

git clone https://github.com/hasancagrigungor/pyepias.git
cd pyepias
pip install -e .

Install dependencies only

pip install -r requirements.txt

Quick Start

from pyepias import EpiasClient

# Initialize the client with your EPİAŞ credentials
client = EpiasClient("your@email.com", "your_password")

# Get today's market clearing prices (full 24 hours)
data = client.download(period="today")
print(data)

Usage Examples

Get data for different time periods

from pyepias import EpiasClient

client = EpiasClient("your@email.com", "your_password")

# Today's data (full 24 hours)
today_data = client.download(period="today")

# Last week's data
week_data = client.download(period="week")

# Last month's data
month_data = client.download(period="month")

Custom date range (any dates!)

from datetime import datetime
from pyepias import EpiasClient

client = EpiasClient("your@email.com", "your_password")

# Example 1: Single specific date
single_date = datetime(2024, 1, 15)
data = client.download(period=(single_date, single_date))

# Example 2: Date range (e.g., 7 days)
start_date = datetime(2024, 1, 1)
end_date = datetime(2024, 1, 7)
data = client.download(period=(start_date, end_date))

# Example 3: Entire month
jan_data = client.download(period=(datetime(2024, 1, 1), datetime(2024, 1, 31)))

# Example 4: Recent dates using timedelta
from datetime import timedelta
end = datetime.now() - timedelta(days=1)
start = end - timedelta(days=10)
data = client.download(period=(start, end))

# Example 5: Cross-year range
data = client.download(period=(datetime(2023, 12, 25), datetime(2024, 1, 5)))

Get JSON output instead of DataFrame

from pyepias import EpiasClient

client = EpiasClient("your@email.com", "your_password")

# Get data as JSON string
json_data = client.download(
    period="today",
    output_format="json"
)
print(json_data)

Get statistical summary

from pyepias import EpiasClient

client = EpiasClient("your@email.com", "your_password")

# Get statistics for the last week
stats = client.stats(period="week")

print(f"Average Price (TL): {stats['mean_price_tl']:.2f}")
print(f"Min Price (TL): {stats['min_price_tl']:.2f}")
print(f"Max Price (TL): {stats['max_price_tl']:.2f}")
print(f"Total Records: {stats['total_records']}")

Data analysis with pandas

from pyepias import EpiasClient
import matplotlib.pyplot as plt

client = EpiasClient("your@email.com", "your_password")

# Get last month's data
df = client.download(period="month")

# Analyze the data
print(df.describe())

# Plot the data
df.plot(x='date', y='price', kind='line', title='Market Clearing Prices')
plt.ylabel('Price (TL/MWh)')
plt.show()

API Reference

EpiasClient

Main client class for interacting with EPİAŞ transparency platform.

Constructor

EpiasClient(email: str, password: str)

Parameters:

• email (str): Your EPİAŞ account email
• password (str): Your EPİAŞ account password

Methods

download()

download(
    period: Union[str, Tuple[datetime, datetime]] = "today",
    output_format: str = "dataframe"
) -> Union[pd.DataFrame, str, None]

Download Market Clearing Price (MCP) data.

Parameters:

• period: Time period for data retrieval
  • "today": Today's data
  • "week": Last 7 days
  • "month": Last 30 days
  • (start_date, end_date): Custom date range as tuple of datetime objects
• output_format: Output format - "dataframe" or "json"

Returns:

• pd.DataFrame, str, or None: Market data in requested format

stats()

stats(
    period: Union[str, Tuple[datetime, datetime]] = "today"
) -> Optional[Dict[str, float]]

Get statistical summary of market clearing prices.

Parameters:

• period: Time period (same as download)

Returns:

• dict: Dictionary containing statistical measures:
  • mean_price_tl: Average price in TL
  • min_price_tl: Minimum price in TL
  • max_price_tl: Maximum price in TL
  • median_price_tl: Median price in TL
  • std_price_tl: Standard deviation of price in TL
  • total_records: Number of records
  • mean_price_eur: Average price in EUR (if available)
  • mean_price_usd: Average price in USD (if available)

Requirements

• Python >= 3.7
• requests >= 2.25.0
• pandas >= 1.2.0

About EPİAŞ

EPİAŞ (Enerji Piyasaları İşletme A.Ş.) is the operator of Turkish electricity markets. The transparency platform provides public access to various electricity market data including market clearing prices, production data, consumption data, and more.

Note: You need to register on the EPİAŞ Transparency Platform to obtain credentials for using this library.

Author

Hasan Çağrı Güngör

• Email: iletisim@cagrigungor.com
• Website: https://www.cagrigungor.com
• GitHub: @hasancagrigungor

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Disclaimer

This library is not officially associated with EPİAŞ. Use at your own risk and make sure to comply with EPİAŞ terms of service.

Changelog

v0.1.5 (Latest)

• TODAY'S DATA: Full 24 hours! - EPİAŞ publishes complete day data
• Fetches real-time data that returns all 24 hours when available
• Improved date handling for partial days
• Week and month now use full completed days only
• Enhanced custom date range examples in documentation
• All features tested and working correctly

v0.1.4

• Fixed data retrieval by fetching day-by-day (API limitation)
• Use yesterday's date as latest to ensure data availability
• All periods (today, week, month) now working correctly

v0.1.3

• Added prominent UNOFFICIAL disclaimer at the top

v0.1.2

• Removed emojis from documentation

v0.1.1

• Updated GitHub repository URL
• Updated homepage URL

v0.1.0 (Initial Release)

• Basic client implementation
• Market Clearing Price (MCP) data retrieval
• Support for multiple time periods
• Statistical analysis features
• JSON and DataFrame output formats