Documentation

The Clarigrid Python SDK

Single, stable Python interface to access and normalise European energy market data from multiple sources. All data returns as timezone-aware pandas DataFrames with consistent column names and units.

Free providers — no API key required

SMARD (DE)Elia (BE)NESO (GB)Elexon / BMRS (GB)ENTSOG (EU gas)

ENTSO-E and TenneT require a personal API key from the upstream provider.

Install

pip install clarigrid

For the interactive setup wizard and CLI tools:

pip install clarigrid[auth]

Quick start

import clarigrid as cg

# Free providers — no key required.
cg.connect("smard")   # DE prices, load, generation
cg.connect("elia")    # BE load, generation
cg.connect("neso")    # GB load, embedded generation
cg.connect("elexon")  # GB prices, generation mix
cg.connect("entsog")  # EU gas flows (any TSO zone)

# Optional: set output timezone (default is UTC).
cg.set_timezone("Europe/Brussels")

# Fetch data — provider is chosen automatically by zone.
prices = cg.get_prices("DE", "2025-01-01", "2025-01-07")  # → smard
load   = cg.get_load("BE",   "2025-01-01", "2025-01-07")  # → elia
gen    = cg.get_generation("GB", "2025-01-01", "2025-01-07")  # → elexon
gas    = cg.get_gas_flows("BE-TSO-0001", "2025-01-01", "2025-01-07")  # → entsog

API key setup

Some providers (ENTSO-E, TenneT) require a personal API key from the upstream data source. Two ways to supply these keys:

Clarigrid account Recommended

Store all provider keys at clarigrid.energy/saved. SDK fetches them automatically using a single Clarigrid API key.

Interactive setup

import clarigrid as cg
cg.connect("entsoe")
# Opens browser → log in at clarigrid.energy → keys fetched automatically.

CLI

clarigrid setup          # guided wizard for all providers
clarigrid connect entsoe # authenticate a single provider

Headless / CI

export CLARIGRID_API_KEY=your-clarigrid-uuid

Set CLARIGRID_API_KEY and no browser is ever needed — SDK fetches all stored provider keys on the first connect() call.

How to get a CLARIGRID_API_KEY:

Log in at clarigrid.energy
Add provider API keys at clarigrid.energy/saved
Run cg.connect("entsoe") once — browser flow stores key locally

Manual key entry no account needed

Set provider keys directly. Keys stored in ~/.config/clarigrid/.env (permissions: 600).

Environment variable

export ENTSOE_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export TENNET_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Config file

# ~/.config/clarigrid/.env
ENTSOE_API_KEY="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
TENNET_API_KEY="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Zone routing

Each cg.connect() registers a provider and its zone coverage in an internal router. When you call get_prices("DE"), the router picks the best connected provider for that zone and dataset automatically.

Multiple connect() calls accumulate coverage. If two providers cover the same zone/dataset pair, the later call wins.

cg.connect("neso")    # covers GB: load, generation
cg.connect("elexon")  # covers GB: prices, generation — overwrites generation slot

# Now: GB prices → elexon, GB load → neso, GB generation → elexon
prices = cg.get_prices("GB", "2025-01-01", "2025-01-02")
load   = cg.get_load("GB",   "2025-01-01", "2025-01-02")

If no connected provider covers the requested zone/dataset, a helpful error is raised:

ZoneNotCoveredError: No connected provider has 'prices' data for zone 'BE'.
  Consider: cg.connect('entsoe')

To bypass routing and force a specific provider:

df = cg.get_load("GB", "2025-01-01", "2025-01-07", source="neso")

Output format

All functions return a pandas.DataFrame with consistent schema:

Property	Value
Index	DatetimeIndex named utc_time, tz-aware
Timezone	UTC by default; change with cg.set_timezone()
Price column	price_mwh
Load column	load_mw
Generation columns	fuel-type specific, e.g. solar_mw, wind_onshore_mw, nuclear_mw
Gas flow column	flow_kwh_d

Price currency stored in df.attrs["currency"] ("EUR" or "GBP"):

df = cg.get_prices("DE", "2025-01-01", "2025-01-07")
print(df.attrs["currency"])  # 'EUR'

Zone codes follow the ENTSO-E bidding zone convention (BE, DE_LU, FR …). Common aliases like DE → DE_LU are resolved automatically.

Timezone

cg.set_timezone("Europe/Brussels")   # all subsequent calls return Brussels time
cg.set_timezone("UTC")               # revert to default

df = cg.get_load("BE", "2025-01-01", "2025-01-07")
# df.index is tz-aware in Europe/Brussels

Data is always fetched and cached as UTC. Timezone conversion is applied at the output boundary only.

Caching

Responses cached locally at ~/.clarigrid/cache/ as Parquet files (requires pip install clarigrid[cache]), keyed by provider + dataset + zone + date range. Historical data cached indefinitely; live data expires after 1 hour by default.

from clarigrid.core import cache

cache.info()           # DataFrame showing cached entries
cache.clear()          # clear all
cache.clear("smard")   # clear one provider
cache.set_live_ttl(1800)  # change live-data TTL to 30 min

Disable caching per call:

df = cg.get_prices("DE", "2025-01-01", "2025-01-07", use_cache=False)