Metadata-Version: 2.4
Name: volt-client
Version: 1.1.0
Summary: Python client for Volt Power Analytics API - Access energy market time series data
Author-email: Volt Power Analytics <support@voltanalytics.no>
License-Expression: MIT
Project-URL: Homepage, https://voltpoweranalytics.com
Project-URL: Documentation, https://github.com/Volt-Power-Analytics/volt-api/tree/main/docs
Project-URL: Repository, https://github.com/Volt-Power-Analytics/volt-api
Keywords: energy,api,time-series,power,market,data
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: polars>=0.20.0
Requires-Dist: requests>=2.28.0
Requires-Dist: orjson>=3.9.0
Provides-Extra: pandas
Requires-Dist: pandas>=2.0.0; extra == "pandas"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"

# Volt Client

Python client for the Volt Power Analytics API - Access energy market time series data.

## Installation

```bash
pip install volt-client
```

## Quick Start

```python
import os
from volt_client import VoltClient

# Initialize with your API key
client = VoltClient(api_key=os.environ["VOLT_API_KEY"])

# Get production data
df = client.get_actual(
    "prod biomass be entso-e mw min60 actual",
    start_date="2024-01-01",
    end_date="2024-12-31"
)
print(df.head())
```

## Features

- Simple Python interface for Volt Power Analytics API
- Support for historical data, forecasts, and forward curves
- Bulk queries for efficient data retrieval
- Timezone conversion and server-side aggregation
- Returns pandas DataFrames (or polars for better performance)

## Usage Examples

### Historical Data

```python
# Single curve
df = client.get_actual(
    "prod biomass be entso-e mw min60 actual",
    start_date="2024-01-01",
    end_date="2024-12-31",
    tz="Europe/Oslo",
    agg="daily",
    agg_func="avg"
)

# Multiple curves (bulk query - much faster)
df = client.get_actual(
    ["prod biomass be entso-e mw min60 actual",
     "prod wind onshore be entso-e mw min60 actual",
     "prod solar be entso-e mw min60 actual"],
    start_date="2024-01-01",
    end_date="2024-12-31"
)
```

### Forecast Data

```python
df = client.get_fcast(
    "price no1 volt emps mid-term fcast",
    start_date="2025-01-01",
    end_date="2025-12-31",
    freq="weekly"  # Returns percentiles: avg, p10, p25, p50, p75, p90
)
```

### Forward Curves

```python
df = client.get_closing("price future no1 nasdaq eur mwh close")
```

### Performance Tips

For large datasets, use polars mode (10x faster):

```python
client = VoltClient(api_key="...", use_polars=True)
df = client.get_actual(...)  # Returns polars DataFrame
```

## API Reference

| Method | Description |
|--------|-------------|
| `get_actual(curve, start, end)` | Get historical/actual data |
| `get_fcast(curve, start, end)` | Get forecast data |
| `get_closing(curve)` | Get forward curve prices |
| `search(area=None)` | Search available curves |
| `get_areas()` | List accessible areas |
| `get_groups()` | List accessible groups |

## Documentation

Full documentation: https://github.com/Volt-Power-Analytics/volt-api/tree/main/docs

## Support

Contact: support@voltanalytics.no
