ordinex-energy

A thin Python client for the Ordinex Energy Intelligence API - point-in-time-safe, walk-forward-validated energy market factors over one REST API.

Install

pip install ordinex-energy          # core client
pip install ordinex-energy[pandas]  # + pandas DataFrame support

If the PyPI release is not available yet, install it directly from this repo:

pip install "git+https://github.com/svandam1988/energy-market-DaaS.git#subdirectory=clients/python"

Quickstart

from ordinex_energy import OrdinexEnergyClient

client = OrdinexEnergyClient(api_key="your-api-key")

# A validated factor, as a plain list of dicts
rows = client.factors(factor="storage_percentile", subject="NW2_EPG0_SWO_R48_BCF")

# ...or as a pandas DataFrame (requires the [pandas] extra)
df = client.factors(factor="wti_brent_spread", as_dataframe=True)

# Cross-sectional snapshots
client.factors_latest(factor="ercot_spark_spread")
client.rankings("storage_percentile", order="desc", limit=5)
client.screen("ercot_spark_spread", min_value=-50, max_value=0)

# Raw series - automatically paginated, you always get the full result
wti = client.series(series_id="RWTC", as_dataframe=True)

# ENTSO-E (EU) raw series
client.eu_capacity(in_domain_eic="10Y1001A1001A82H", out_domain_eic="10YDK-1--------W")

# What a factor is backed by, and how much confidence the evidence supports
client.factor_metadata(factor="storage_percentile")
client.factor_regimes("ercot_spark_spread")

# Your own usage
client.usage()

Bulk point-in-time export

Backtests should not page through thousands of requests. export_factors streams a whole date-bounded slice in one call. Every row has period (the date it describes) and known_at (the earliest date it could have been known, period plus the factor's reporting lag).

# Everything knowable on 2025-06-30, as a DataFrame
df = client.export_factors(factor="ercot_spark_spread", as_of="2025-06-30", as_dataframe=True)

# Walk-forward without leakage: cut folds on known_at, not period
full = client.export_factors(factor="storage_percentile", as_dataframe=True)
train = full[full["known_at"] <= "2024-12-31"]

# Very large exports: write straight to disk
client.export_factors(start_date="2023-01-01", path="factors.csv")

Notes: values are not revision-versioned (point-in-time here means publication timing, not "the value as first published"); a request matching more than 1,000,000 rows is refused with a 422 asking you to narrow it; only public factors and servable subjects are exported.

Pagination

/v1/series, /v1/factors, and the /v1/eu/* routes are paginated by the API itself (limit/offset, capped at 5000 rows/page) to bound response size. This client handles that transparently - every method above returns the complete matching result as one Python list (or DataFrame); you never need to loop over pages yourself.

Errors

A non-2xx response raises OrdinexEnergyAPIError, with .status_code and .detail set from the real response:

from ordinex_energy import OrdinexEnergyAPIError

try:
    client.factors_latest(factor="not-a-real-factor")
except OrdinexEnergyAPIError as exc:
    print(exc.status_code, exc.detail)  # 404 "factor 'not-a-real-factor' not found"

A 429 (rate limit) is retried automatically (honoring the server's Retry-After header) up to max_retries times (default 3) before raising.

Development

pip install -e .[dev,pandas]
pytest