Clarigrid

For the interactive setup wizard and CLI tools:

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) cg.connect("energycharts") # European prices, power, forecasts and flows cg.connect("energinet") # DK1/DK2 prices, power, forecasts, flows and CO2 cg.connect("redata") # ES load, generation, capacity and cross-border flows cg.connect("rte") # FR load, generation, forecasts, exchanges and CO2 cg.connect("fingrid") # FI power, forecasts, flows, balancing and CO2 (free key) cg.connect("gie") # European gas storage and LNG inventory (free 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) # 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 us_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") # → caiso nyc = cg.get_prices("NYISO_NYC", "2025-01-01", "2025-01-07") # → nyiso weather = cg.get_weather( "40.7128,-74.0060", "2025-01-01", "2025-01-07", source="nasapower", )

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)

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

clarigrid setup # guided wizard for all providers clarigrid 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

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-xxxxxxxxxxxx export 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"

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

Multipleconnect()calls accumulate coverage. If two providers both cover the same zone/dataset pair, thelaterconnect()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")

All functions return apandas.DataFramewith:

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) │ └── entsog.py # ENTSOG Transparency Platform (EU gas) └── utils/ ├── time.py # parse_dt, normalise_index └── validation.py # resolve_zone, validate_date_range

External providers subclassDataProvider, declare theirzones()andcapabilities(), and self-register on import. Providers whose capabilities have different geographical coverage can additionally overridecapability_zones():