pyepias 0.1.5
EPİAŞ (Turkish Electricity Market) transparency platform data API client
License: MIT
Requires Python: >=3.7
Keywords: epias electricity energy market turkey data api

# 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)

```bash
pip install pyepias
```

### From source

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

### Install dependencies only

```bash
pip install -r requirements.txt
```

## Quick Start

```python
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

```python
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!)

```python
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

```python
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

```python
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

```python
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

```python
EpiasClient(email: str, password: str)
```

**Parameters:**
- `email` (str): Your EPİAŞ account email
- `password` (str): Your EPİAŞ account password

#### Methods

##### download()

```python
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()

```python
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](https://seffaflik.epias.com.tr/) 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](https://github.com/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