Metadata-Version: 2.4
Name: volt-client
Version: 1.7.0
Summary: Python client for Volt Power Analytics API - Access energy market time series data
Author-email: Volt Power Analytics <support@voltanalytics.no>
License: 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: pandas>=2.0.0
Requires-Dist: pyarrow>=14.0.0
Requires-Dist: requests>=2.30.0
Requires-Dist: urllib3>=2.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
)

# Many curves in one request: wide, one column per curve
df = client.get_fcast(
    [
        "cap installed wind onshore no1 volt long-term base mw m fcast",
        "cap installed wind onshore no2 volt long-term base mw m fcast",
    ],
    start_date="2025-01-01",
    end_date="2030-01-01",
    as_of="2025-06-01",  # each curve resolves to its latest vintage on or before this date
)

# Same request long-form, keeping each curve's own as_of
df = client.get_bulk_fcast(
    [
        "cap installed wind onshore no1 volt long-term base mw m fcast",
        "cap installed wind onshore no2 volt long-term base mw m fcast",
    ],
    start_date="2025-01-01",
    end_date="2030-01-01",
)
df.groupby("curve_name")["as_of"].first()
```

Bulk requests take at most 100 curves (30 when any curve is hourly or finer and `freq` doesn't
aggregate it to daily or coarser). Curves the key
cannot access, or without data in the window, are left out of the result rather than raising.

### 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_fcast([curves], start, end)` | Forecast data for many curves, wide (one column per curve) |
| `get_bulk_fcast(curves, start, end)` | Forecast data for many curves, long-form with per-curve `as_of` |
| `get_closing(curve)` | Get forward curve prices |
| `get_bulk_closing(curves, as_of_start, as_of_end)` | Forward curve development for many curves |
| `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
