Clarigrid

Clarigrid

欧州および米国のエネルギー市場データ向け統合 Python SDK です。

---

概要

Clarigrid は、複数のソースから欧州および米国のエネルギー市場データにアクセスし、正規化するための、単一で安定した Python インターフェースを提供します。すべてのデータは、列名と単位が統一された、タイムゾーン対応の pandas DataFrame として返されます。

組み込みの無料プロバイダー（API キー不要）には、Energy-Charts （欧州）、Energinet（DK1/DK2）、SMARD（DE）、Elia（BE）、NESO （GB）、Elexon/BMRS（GB）、ENTSOG（EU のガス）、Gas Networks Ireland が含まれます。 Fingrid（FI）、GIE AGSI/ALSI（欧州のガス）、TenneT（NL）も組み込み済みで、無料の API キーを使用します。 米国では、CAISO OASIS と NYISO が、認証不要の市場データおよびシステムデータを提供します。EIA-930 は、無料の EIA キーを使って、全国のバランシング・オーソリティ別の時間単位の負荷、予測、燃料別発電量、物理的な電力融通を提供します。 世界の過去の気象データと太陽光データは API キーなしで NASA POWER から利用でき、米国の公式な時間単位の予報は NOAA/NWS から利用できます。 ENTSO-E など、API キーで保護されたソースは、以下のAPI キーの設定の説明に従って設定できます。

---

インストール

pip install clarigrid

対話型セットアップウィザードおよび CLI ツールを利用する場合：

pip install clarigrid[auth]

---

クイックスタート

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("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")  # → 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
ie_gas = cg.get_gas_demand("IE", "2025-01-01", "2025-01-07")  # → gni
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",
)
nws_forecast = cg.get_weather(
    "39.7456,-97.0892",
    "2026-09-17",
    "2026-09-18",
    source="nws",
)

---

API キーの設定

一部のプロバイダー（ENTSO-E、TenneT）では、上流のデータソースから発行された個人用 API キーが必要です。Clarigrid では、これらのキーを 2 通りの方法で指定できます。

オプション 1 — ClarigGrid アカウント（推奨）

すべてのプロバイダーキーをclarigrid.energy/savedにまとめて保存できます。SDK は単一の ClarigGrid API キーを使って、キーを自動的に取得します。

初回セットアップ（対話型）：

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

ヘッドレス／CI 環境： 環境変数を 1 つ設定するだけで、ブラウザーは必要ありません：

export CLARIGRID_API_KEY=your-clarigrid-uuid

SDK は CLARIGRID_API_KEY を使用して、各セッションで最初に connect() を呼び出したときに、保存済みのすべてのプロバイダーキーを clarigrid.energy から取得します。

CLARIGRID_API_KEY の取得方法：

1. clarigrid.energy にログインします
2. clarigrid.energy/saved でプロバイダーの API キーを追加します
3. 対話型ターミナルで cg.connect("entsoe") を一度実行します。ブラウザーを使ったログイン処理が行われ、CLARIGRID_API_KEY がローカルに保存されます。

---

オプション 2 — キーを手動で入力（アカウント不要）

clarigrid.energy のアカウントを使わない場合は、プロバイダーキーを直接設定します。キーは ~/.config/clarigrid/.env に保存されます（権限：600）。

環境変数（CI での使用を推奨）：

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

設定ファイル — ~/.config/clarigrid/.env に追加します：

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

ゾーンのルーティング

cg.connect() を呼び出すたびに、プロバイダーと、その機能に対応するゾーンのカバレッジが内部ルーターに登録されます。get_prices("DE") を呼び出すと、ルーターはそのゾーンとデータセットに最適な接続済みプロバイダーを自動的に選択します。

複数回の connect() 呼び出しで、カバレッジが蓄積されます。2 つのプロバイダーが同じゾーン／データセットの組み合わせをカバーする場合は、後から呼び出した connect() が優先されます。

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")

接続済みのプロバイダーが、要求されたゾーン／データセットをカバーしていない場合は、分かりやすいエラーが発生します：

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

ルーティングを回避して、特定のプロバイダーを強制的に使用するには：

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

---

出力形式

すべての関数は、次の構成の pandas.DataFrame を返します。

プロパティ	値
インデックス	utc_time という名前の、タイムゾーン対応 DatetimeIndex
タイムゾーン	デフォルトは UTC。cg.set_timezone() で変更できます
価格列	price_mwh
負荷列	load_mw
発電列	燃料種別ごと。例：solar_mw、wind_onshore_mw、nuclear_mw
ガスフロー列	flow_kwh_d
ガス貯蔵	在庫は *_mwh、日次レートは *_mwh_d
LNG 在庫	*_thousand_m3、払い出し量は *_mwh_d
国境間フロー列	符号付き MW。輸入は正、輸出は負
設備容量	*_capacity_mw。貯蔵エネルギーは *_energy_mwh
周波数	frequency_hz
再生可能エネルギー比率	*_pct

価格の通貨は df.attrs["currency"] に格納されます（例："EUR"`、 "GBP"、"USD"``）。

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

欧州のゾーンコードは、ENTSO-E の入札ゾーン規則（BE、DE_LU、 FR など）に従います。米国の電力では、EIA/NERC の需給調整機関コード（CISO、 ERCO、PJM、NYIS）と明示的な市場ハブ（CISO_NP15）を使用します。 一般的な別名（DE → DE_LU、CAISO → CISO、ERCOT → ERCO）は 自動的に解決されます。

---

タイムゾーン

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

データは常に UTC として取得され、キャッシュされます。タイムゾーン変換は 出力時にのみ適用されます。

---

キャッシュ

レスポンスは ~/.clarigrid/cache/ に Parquet ファイルとしてローカルに キャッシュされます（pip install clarigrid[cache] が必要です）。キャッシュの キーには、プロバイダー、データセット、ゾーン、日付範囲が使われます。過去の データは無期限にキャッシュされ、ライブデータはデフォルトで 1 時間後に期限切れになります。

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

呼び出しごとにキャッシュを無効にするには、次のようにします。

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

---

CLI リファレンス

pip install clarigrid[auth] が必要です。

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 リファレンス

関数	説明
cg.connect(provider)	プロバイダーに接続します。キーで保護されたソースの認証を処理します
cg.set_timezone(tz)	出力タイムゾーンを設定します（IANA 文字列。デフォルトは "UTC"）
cg.get_prices(zone, start, end, market="day_ahead", node=None)	電力価格 → price_mwh。ノード別市場では、オプションでノードを指定できます
cg.get_load(zone, start, end)	実際の総負荷 → load_mw
cg.get_generation(zone, start, end)	燃料種別ごとの発電量 → *_mw 列
cg.get_generation_forecast(zone, start, end)	風力／太陽光発電の予測 → *_forecast_mw
cg.get_load_forecast(zone, start, end)	負荷予測 → load_forecast_mw
cg.get_physical_flows(zone, start, end)	符号付きの国境間物理フロー（MW）
cg.get_commercial_schedule(zone, start, end)	符号付きの商用取引量（MW）
cg.get_installed_capacity(zone, start, end)	技術別の設備出力（MW）
cg.get_frequency(zone, start, end)	系統周波数 → frequency_hz
cg.get_renewable_share(zone, start, end)	再生可能エネルギー比率（パーセント）
cg.get_co2_intensity(zone, start, end)	電力の炭素強度（gCO2/kWh）
cg.get_co2_forecast(zone, start, end)	炭素強度の予測（gCO2/kWh）
cg.get_gas_flows(zone, start, end)	ガスの物理フロー → flow_kwh_d
cg.get_capacity(zone, start, end)	確定済みの技術的ガス容量 → capacity_kwh_d
cg.get_gas_demand(zone, start, end)	部門別の日次ガス需要（GWh）
cg.get_gas_storage(zone, start, end)	ガスの在庫、容量、注入量、払出量
cg.get_lng_inventory(zone, start, end)	LNG タンクの在庫とターミナルの払い出し量
cg.get_weather(zone, start, end)	気象観測値／予報
cg.status()	接続済みのプロバイダー、ゾーン、機能を表示します
cg.set_api_key(provider, key)	プロバイダーのキーをローカルに保存します
cg.list_providers()	登録済みのプロバイダー名をすべて一覧表示します
cg.register_provider(name, instance)	外部プロバイダーを登録します

すべてのデータ関数で、次の引数を使用できます。

• source="name" — この呼び出しに限り、ルーターを上書きします
• use_cache=False — ローカルキャッシュをバイパスします

---

組み込みプロバイダー

名前	データ	ゾーン	認証
energycharts	価格、需要、発電量、予測、設備容量、越境フロー、周波数、再生可能エネルギー比率	欧州各国およびオープンライセンスの価格ゾーン	なし
energinet	価格、需要、発電量、予測、物理フロー、実績／予測 CO2	DK1、DK2	なし
elhub	生産グループ別の時間単位の計量済み消費量と発電量	NO1–NO5	なし
pse	15 分単位の電力システム需要の実績と予測	PL	なし
eirgrid	15 分単位のシステム需要実績	IE、GB-NIR	なし
sfoe	95％信頼区間の下限と上限を含む、日単位の全国需要予測	CH	なし
redata	5 分単位の需要／予測、日平均の発電量・比率・物理フロー、設備容量	ES	なし
rte	需要、発電量、需要予測、物理／商用取引、発電比率、CO2	FR	なし
fingrid	需要、発電量、予測、フロー、NTC、設備容量、周波数、CO2、インバランス、需給調整	FI	無料 API キー
gie	地下ガス貯蔵および LNG ターミナル在庫の日次データ	欧州、各国、施設	無料 API キー
gni	部門別のガス需要の日次データ	IE	なし
eia	時間単位の需要、予測、燃料別発電量、物理的な電力融通、発電比率	米国の需給調整機関および地域	無料 API キー
caiso	NP15、SP15、ZP26 または明示的に指定したノードの前日市場 LMP	California ISO	なし
nyiso	前日市場ゾーン別 LBMP、需要の実績／予測、電源構成、比率	New York ISO および NYISO の需要ゾーン	なし
nasapower	日次／時間単位の気象データ、降水量、風、日射量	世界各地の地点（lat,lon）	なし
nws	気温、湿度、風、雲量、降水確率の時間単位予測	米国、領土、隣接水域（lat,lon）	なし
metno	気温、気圧、湿度、雲量、風、降水量の予測	世界各地の地点（lat,lon）	なし
smard	価格、需要、発電量	DE、AT、LU ＋ TSO サブゾーン	なし
elia	需要、発電量	BE	なし
neso	需要、分散型発電量、CO2 の実績／予測、発電比率	GB	なし
elexon	価格、電源構成	GB	なし
entsog	ガスフロー、設備容量	すべての ENTSOG 運用事業者	なし
entsoe	価格、需要、発電量	すべての ENTSO-E 入札ゾーン	ENTSOE_API_KEY
tennet	(データ取得は近日対応予定)	NL	TENNET_API_KEY

MET Norway は公式の Locationforecast 2.0 コンパクト予報を使用します。世界各地の地点を lat,lon で指定し、必要に応じてメートル単位の整数値 altitude を渡してください。座標は上流の小数点以下 4 桁という制限に合わせて丸められ、結果は UTC に正規化されます。また、SDK は MET Norway が求める識別用 User-Agent を設定します。このエンドポイントが提供するのは現在の予報のみであり、このプロバイダーでは過去のモデルデータを取得しません。データを再利用するには、MET Norway のクレジット表記が必要です。

EirGrid は、アイルランド共和国と北アイルランドのシステム需要（15 分単位）の公式 Smart Grid Dashboard JSON フィードを使用します。このフィードはキー不要で、タイムスタンプはダッシュボードの UTC 値を基に正規化されます。データを再利用するには、 EirGrid Group Open Data Licence に基づき、Supported by EirGrid Group Data のクレジット表記が必要です。 SFOE は、SDSC の全国電力消費量予測に関するスイス連邦エネルギー庁のバージョン管理された Energy Dashboard 公開 API を使用します。ソースの値は日次 GWh であり、DST を考慮した日平均 MW として load_forecast_min_mw、load_forecast_mw、load_forecast_max_mw に公開されます。opendata.swiss の利用条件に基づき、出典の明記を条件として、商用・非商用の再利用が可能です。 entsoe と tennet のキーは、それぞれの上流プロバイダーから発行されます。 clarigrid.energy のアカウントを通じて保存するか、 API キーの設定の説明に従って手動で設定してください。

---

アーキテクチャ

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

プラグインシステム

外部プロバイダーは DataProvider をサブクラス化し、zones() と capabilities() を宣言して、インポート時に自動登録します。機能によって 対象となる地域が異なるプロバイダーは、capability_zones() を追加で オーバーライドできます。

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())

cg.connect("nordpool") を呼び出した後は、cg.get_prices("NO1", …) の呼び出しが 自動的にこのプロバイダーにルーティングされます。

---

開発

git clone https://github.com/clarigrid/clarigrid
cd clarigrid
pip install -e ".[dev]"
pytest
ruff check .
mypy clarigrid

---

ライセンス

Apache 2.0 — LICENSE を参照してください。

Copyright (c) 2026 Alexander Hoogsteyn.