Clarigrid
Read-only electricity, gas, and weather data with structured provenance and units.
Open source Repository Open in the app JSON README (API)
About
Read-only electricity, gas, and weather data with structured provenance and units.
Details
- Kind
- MCP servers
- Topic
- Maps, weather & travel
- Publisher
- energy.clarigrid
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.2.0
- Stars
- 3
- Last push
- 2026-07-29T19:27:42Z
- Repository state
- ativo
- Language
- Python
- License
- NOASSERTION
- Added
- 2026-08-29 03:01:32
- Updated
- 2026-08-29 03:01:32
- Origin id
energy.clarigrid/clarigrid
README
# Clarigrid
Unified Python SDK for European and U.S. energy market data.
[](https://pypi.org/project/clarigrid/)
[](https://pypi.org/project/clarigrid/)
[](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), and **ENTSOG** (EU gas).
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.
ENTSO-E and other key-protected sources can be configured as described in
[API key setup](#api-key-setup) below.
---
## Install
```bash
pip install clarigrid
```
For the interactive setup wizard and CLI tools:
```bash
pip install clarigrid[auth]
```
---
## Quick start
```python
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",
)
```
---
## 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](https://clarigrid.energy/saved). The SDK then
fetches them automatically using a single **ClarigGrid API key**.
**First-time setup (interactive):**
```python
import clarigrid as cg
cg.connect("entsoe")
# Opens browser → log in at clarigrid.energy → keys fetched automatically.
```
Or use the CLI:
```bash
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:
```bash
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](https://clarigrid.energy)
2. Add your provider API keys at [clarigrid.energy/saved](https://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):
```bash
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"
```
## 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.
```python
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:
```python
df = cg.get_load("GB", "2025-01-01", "2025-01-07", source="neso")
```
---
## Output format
All functions return a `pandas.DataFrame` with:
| 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` |
| Gas storage | inventory in `*_mwh`; daily rates in `*_mwh_d` |
| LNG inventory | `*_thousand_m3`; send-out in `*_mwh_d` |
| Cross-border columns | signed MW; imports positive, exports negative |
| Installed capacity | `*_capacity_mw`; storage energy uses `*_energy_mwh` |
| Frequency | `frequency_hz` |
| Renewable shares | `*_pct` |
Price currency is stored in `df.attrs["currency"]` (for example ``"EUR"``,
``"GBP"``, or ``"USD"``):
```python
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
```python
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 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.
```python
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:
```python
df = cg.get_prices("DE", "2025-01-01", "2025-01-07", use_cache=False)
```
---
## CLI reference
Requires `pip install clarigrid[auth]`.
```bash
clarigrid setup # guided wizard — configure all providers
clarigrid connect <source> # authenticate a single provider
clarigrid auth --show # list configured sources (keys masked)
clarigrid auth --clear <source> # remove key for a specific source
clarigrid auth --clear --all # remove all stored keys
```
---
## API reference
| Function | Description |
|---|---|
| `cg.connect(provider)` | Connect provider; handles auth for key-guarded sources |
| `cg.set_timezone(tz)` | Set output timezone (IANA string, default `"UTC"`) |
| `cg.get_prices(zone, start, end, market="day_ahead", node=None)` | Electricity prices → `price_mwh`; optional node for nodal markets |
| `cg.get_load(zone, start, end)` | Actual total load → `load_mw` |
| `cg.get_generation(zone, start, end)` | Generation per fuel type → `*_mw` columns |
| `cg.get_generation_forecast(zone, start, end)` | Wind/solar generation forecast → `*_forecast_mw` |
| `cg.get_load_forecast(zone, start, end)` | Load forecast → `load_forecast_mw` |
| `cg.get_physical_flows(zone, start, end)` | Signed cross-border physical flows in MW |
| `cg.get_commercial_schedule(zone, start, end)` | Signed commercial exchanges in MW |
| `cg.get_installed_capacity(zone, start, end)` | Installed power by technology in MW |
| `cg.get_frequency(zone, start, end)` | System frequency → `frequency_hz` |
| `cg.get_renewable_share(zone, start, end)` | Renewable share in percent |
| `cg.get_co2_intensity(zone, start, end)` | Electricity carbon intensity in gCO2/kWh |
| `cg.get_co2_forecast(zone, start, end)` | Forecast carbon intensity in gCO2/kWh |
| `cg.get_gas_flows(zone, start, end)` | Gas physical flows → `flow_kwh_d` |
| `cg.get_capacity(zone, start, end)` | Firm technical gas capacity → `capacity_kwh_d` |
| `cg.get_gas_storage(zone, start, end)` | Gas inventory, capacity, injection and withdrawal |
| `cg.get_lng_inventory(zone, start, end)` | LNG tank inventory and terminal send-out |
| `cg.get_weather(zone, start, end)` | Weather observations / forecasts |
| `cg.status()` | Print connected providers, zones, capabilities |
| `cg.set_api_key(provider, key)` | Store a provider key locally |
| `cg.list_providers()` | List all registered provider names |
| `cg.register_provider(name, instance)` | Register an external provider |
All data functions accept:
- `source="name"` — override the router for this call only
- `use_cache=False` — bypass the local cache
---
## Built-in providers
| Name | Data | Zones | Auth |
|---|---|---|---|
| `energycharts` | prices, load, generation, forecasts, capacity, cross-border flows, frequency, renewable share | European countries and openly licensed price zones | None |
| `energinet` | prices, load, generation, forecasts, physical flows, actual/forecast CO2 | DK1, DK2 | None |
| `redata` | five-minute load/forecast; daily-average generation, shares and physical flows; installed capacity | ES | None |
| `rte` | load, generation, load forecasts, physical/commercial exchanges, generation shares and CO2 | FR | None |
| `fingrid` | load, generation, forecasts, flows, NTC, capacity, frequency, CO2, imbalance and balancing | FI | Free API key |
| `gie` | daily underground gas storage and LNG terminal inventory | Europe, countries, facilities | Free API key |
| `eia` | hourly load, forecast, fuel generation, physical interchange and generation shares | U.S. balancing authorities and regions | Free API key |
| `caiso` | day-ahead LMP at NP15, SP15, ZP26 or an explicit node | California ISO | None |
| `nyiso` | day-ahead zonal LBMP, actual/forecast load, fuel mix and shares | New York ISO and NYISO load zones | None |
| `nasapower` | daily/hourly meteorology, precipitation, wind and solar radiation | Global point locations (`lat,lon`) | None |
| `smard` | prices, load, generation | DE, AT, LU + TSO sub-zones | None |
| `elia` | load, generation | BE | None |
| `neso` | load, embedded generation, actual/forecast CO2, generation shares | GB | None |
| `elexon` | prices, generation mix | GB | None |
| `entsog` | gas flows, capacity | All ENTSOG operators | None |
| `entsoe` | prices, load, generation | All ENTSO-E bidding zones | `ENTSOE_API_KEY` |
| `tennet` | *(data fetching coming soon)* | NL | `TENNET_API_KEY` |
Keys for `entsoe` and `tennet` are issued by the respective upstream provider.
Store them via a [clarigrid.energy](https://clarigrid.energy) account or
set them manually as described in [API key setup](#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)
│ └── 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()`:
```python
from clarigrid.core.interface import DataProvider
from clarigrid.core.registry import register_provider
import 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
```bash
git clone https://github.com/clarigrid/clarigrid
cd clarigrid
pip install -e ".[dev]"
pytest
ruff check .
mypy clarigrid
```
---
## License
Apache 2.0 — see [LICENSE](LICENSE).
Copyright (c) 2026 Alexander Hoogsteyn.