Clarigrid

Clarigrid

Unified Python SDK for European and U.S. energy market data.

[PyPI] [Python] [License]

What it is

Clarigrid provides a single, stable Python interface to access and normalise European and U.S. energy market data from multiple sources. All data comes back as timezone-aware pandas DataFrames with consistent column names and units.

Built-in free providers (no API key required) include Energy-Charts (Europe), Energinet (DK1/DK2), SMARD (DE), Elia (BE), NESO (GB), Elexon/BMRS (GB), ENTSOG (EU gas), and Gas Networks Ireland. Fingrid (FI), GIE AGSI/ALSI (European gas), and TenneT (NL) are also built in and use free API keys. For the United States, CAISO OASIS and NYISO provide no-auth market and system data. EIA-930 provides nationwide hourly balancing-authority load, forecasts, fuel generation, and physical interchange with a free EIA key. Global historical meteorology and solar data are available from NASA POWER without an API key; official U.S. hourly forecasts are available from NOAA/NWS. ENTSO-E and other key-protected sources can be configured as described in API key setup below.

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, generationcg.connect("elia")    # BE load, generationcg.connect("neso")    # GB load, embedded generationcg.connect("elexon")  # GB prices, generation mixcg.connect("entsog")  # EU gas flows (any TSO zone)cg.connect("energycharts")  # European prices, power, forecasts and flowscg.connect("energinet")  # DK1/DK2 prices, power, forecasts, flows and CO2cg.connect("redata")  # ES load, generation, capacity and cross-border flowscg.connect("rte")  # FR load, generation, forecasts, exchanges and CO2cg.connect("fingrid")  # FI power, forecasts, flows, balancing and CO2 (free key)cg.connect("gie")  # European gas storage and LNG inventory (free key)cg.connect("gni")  # IE daily gas demand by sector (no key)cg.connect("eia")  # US balancing-authority load, generation and flows (free key)cg.connect("caiso")  # CAISO day-ahead hub prices (no key)cg.connect("nyiso")  # NYISO prices, load, forecasts and fuel mix (no key)cg.connect("nasapower")  # Global daily/hourly weather and solar data (no key)cg.connect("nws")  # Official U.S. hourly weather forecasts (no key)
# 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")  # → smardload   = cg.get_load("BE",   "2025-01-01", "2025-01-07")  # → eliagen    = cg.get_generation("GB", "2025-01-01", "2025-01-07")  # → elexongas    = cg.get_gas_flows("BE-TSO-0001", "2025-01-01", "2025-01-07")  # → entsogie_gas = cg.get_gas_demand("IE", "2025-01-01", "2025-01-07")  # → gnius_load = cg.get_load("CAISO", "2025-01-01", "2025-01-07")  # → eia (CISO)np15 = cg.get_prices("CISO_NP15", "2025-01-01", "2025-01-07")  # → caisonyc = cg.get_prices("NYISO_NYC", "2025-01-01", "2025-01-07")  # → nyisoweather = cg.get_weather(    "40.7128,-74.0060",    "2025-01-01",    "2025-01-07",    source="nasapower",)nws_forecast = cg.get_weather(    "39.7456,-97.0892",    "2026-09-17",    "2026-09-18",    source="nws",)

API key setup

Some providers (ENTSO-E, TenneT) require a personal API key issued by the upstream data source. Clarigrid supports two ways to supply these keys.

Option 1 — ClarigGrid account (recommended)

Store all your provider keys in one place at clarigrid.energy/saved. The SDK then fetches them automatically using a single ClarigGrid API key.

First-time setup (interactive):

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

Or use the CLI:

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

Headless / CI environments: set one environment variable and no browser is ever needed:

export CLARIGRID_API_KEY=your-clarigrid-uuid

The SDK uses CLARIGRID_API_KEY to fetch all your stored provider keys from clarigrid.energy on the first connect() call of each session.

How to get a CLARIGRID_API_KEY:

1. Log in at clarigrid.energy
2. Add your provider API keys at clarigrid.energy/saved
3. Run cg.connect("entsoe") once in an interactive terminal — the browser flow logs you in and stores your CLARIGRID_API_KEY locally.

Option 2 — Manual key entry (no account needed)

If you prefer not to use a clarigrid.energy account, set provider keys directly. Keys are stored in ~/.config/clarigrid/.env (permissions: 600).

Environment variable (recommended for CI):

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

Config file — add to ~/.config/clarigrid/.env:

ENTSOE_API_KEY="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"TENNET_API_KEY="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Zone routing

Each call to cg.connect() registers a provider and its capability-specific 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 both cover the same zone/dataset pair, the later connect() call wins.

cg.connect("neso")    # covers GB: load, generationcg.connect("elexon")  # covers GB: prices, generation — overwrites generation slot
# Now: GB prices → elexon, GB load → neso, GB generation → elexonprices = 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:

Price currency is stored in df.attrs["currency"] (for example "EUR", "GBP", or "USD"):

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

European zone codes follow the ENTSO-E bidding zone convention (BE, DE_LU, FR ...). U.S. electricity uses EIA/NERC balancing-authority codes (CISO, ERCO, PJM, NYIS) and explicit market hubs (CISO_NP15). Common aliases (DE → DE_LU, CAISO → CISO, ERCOT → ERCO) resolve automatically.

Timezone

cg.set_timezone("Europe/Brussels")   # all subsequent calls return Brussels timecg.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 are cached locally at ~/.clarigrid/cache/ as Parquet files (requires pip install clarigrid[cache]), keyed by provider + dataset + zone + date range. Historical data is cached indefinitely; live data expires after 1 hour by default.

from clarigrid.core import cache
cache.info()           # DataFrame showing cached entriescache.clear()          # clear allcache.clear("smard")   # clear one providercache.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)

CLI reference

Requires pip install clarigrid[auth].

clarigrid setup                    # guided wizard — configure all providersclarigrid connect <source>         # authenticate a single providerclarigrid auth --show              # list configured sources (keys masked)clarigrid auth --clear <source>    # remove key for a specific sourceclarigrid auth --clear --all       # remove all stored keys

API reference

All data functions accept:

• source="name" — override the router for this call only
• use_cache=False — bypass the local cache

Built-in providers

MET Norway uses the official Locationforecast 2.0 compact forecast. Pass a global point as lat,lon and optionally an integer altitude in metres. Coordinates are rounded to the upstream four-decimal limit, results are normalized to UTC, and the SDK supplies the identifying User-Agent required by MET Norway. The endpoint serves current forecasts only; historical model data is not fetched by this provider. Reuse requires MET Norway attribution.

EirGrid uses the official Smart Grid Dashboard JSON feed for 15-minute Republic of Ireland and Northern Ireland system demand. The feed is keyless, timestamps are normalized from the dashboard's UTC values, and reuse requires the attribution Supported by EirGrid Group Data under the EirGrid Group Open Data Licence. SFOE uses the Swiss Federal Office of Energy's versioned Energy Dashboard public API for the SDSC national electricity-consumption forecast. Source values are daily GWh and are exposed as DST-aware daily-average MW in load_forecast_min_mw, load_forecast_mw, and load_forecast_max_mw. Reuse is commercial and non-commercial with mandatory source attribution under the opendata.swiss terms.

Keys for entsoe and tennet are issued by the respective upstream provider. Store them via a clarigrid.energy account or set them manually as described in API key setup.

Architecture

clarigrid/├── __init__.py           # public surface: connect, get_prices, set_timezone, …├── _auth.py              # KeyState machine, auth flows, provider key registry├── _keystore.py          # ~/.config/clarigrid/.env  read/write (chmod 600)├── _browser_flow.py      # browser-based OAuth flow (localhost callback server)├── cli.py                # clarigrid CLI (setup, connect, auth)├── core/│   ├── api.py            # top-level functions — routing + normalisation│   ├── router.py         # ZoneRouter — (zone, capability) → provider│   ├── session.py        # runtime state: router, connected map, output TZ│   ├── normalise.py      # canonical column names + unit normalisation│   ├── registry.py       # register_provider / get_provider│   ├── interface.py      # DataProvider ABC ← providers implement this│   ├── cache.py          # filesystem Parquet cache│   ├── config.py         # legacy key store (~/.clarigrid/keys.toml)│   ├── exceptions.py     # exception hierarchy│   └── types.py          # shared constants, zone aliases├── providers/│   ├── smard.py          # Bundesnetzagentur SMARD (DE)│   ├── energycharts.py   # Fraunhofer ISE Energy-Charts (Europe)│   ├── energinet.py      # Energinet Energi Data Service (DK1/DK2)│   ├── redata.py         # Red Electrica REData (ES)│   ├── rte.py            # RTE Eco2mix (FR)│   ├── elia.py           # Elia Open Data (BE)│   ├── neso.py           # NESO Data Portal (GB)│   ├── elexon.py         # Elexon BMRS (GB)│   ├── eia.py            # EIA-930 balancing-authority operations (US)│   ├── caiso.py          # CAISO OASIS day-ahead prices (US)│   ├── nyiso.py          # NYISO prices, load, forecasts and fuel mix (US)│   ├── nasapower.py      # NASA POWER meteorology and solar data (global)│   ├── nws.py            # NOAA/NWS hourly grid forecasts (US)│   ├── metno.py          # MET Norway global point forecasts│   └── entsog.py         # ENTSOG Transparency Platform (EU gas)└── utils/    ├── time.py           # parse_dt, normalise_index    └── validation.py     # resolve_zone, validate_date_range

Plugin system

External providers subclass DataProvider, declare their zones() and capabilities(), and self-register on import. Providers whose capabilities have different geographical coverage can additionally override capability_zones():

from clarigrid.core.interface import DataProviderfrom clarigrid.core.registry import register_providerimport pandas as pd
class NordpoolProvider(DataProvider):    def zones(self) -> set[str]:        return {"NO1", "NO2", "SE1", "SE2", "DK1", "DK2", "FI"}
    def capabilities(self) -> set[str]:        return {"prices"}
    def get_prices(self, zone, start, end, **kwargs) -> pd.DataFrame: ...
register_provider("nordpool", NordpoolProvider())

After cg.connect("nordpool"), calls to cg.get_prices("NO1", …) route to this provider automatically.

Development

git clone https://github.com/clarigrid/clarigridcd clarigridpip install -e ".[dev]"pytestruff check .mypy clarigrid

License

Apache 2.0 — see LICENSE.

Copyright (c) 2026 Alexander Hoogsteyn.