Metadata-Version: 2.4
Name: pyepias
Version: 0.1.3
Summary: EPİAŞ (Turkish Electricity Market) transparency platform data API client
Home-page: https://www.cagrigungor.com
Author: Hasan Çağrı Güngör
Author-email: iletisim@cagrigungor.com
License: MIT
Keywords: epias electricity energy market turkey data api
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: pandas>=1.2.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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, week, month, custom range)
- 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
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
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

```python
from datetime import datetime
from pyepias import EpiasClient

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

# Define custom date range
start_date = datetime(2024, 1, 1)
end_date = datetime(2024, 1, 10)

# Get data for custom range
data = client.download(period=(start_date, end_date))
```

### 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.3 (Latest)
- 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
