Clarigrid

Clarigrid

用于欧洲和美国能源市场数据的统一 Python SDK。

---

项目简介

Clarigrid 提供统一、稳定的 Python 接口，用于访问和规范化来自多个数据源的欧洲和美国能源市场数据。所有数据均以时区感知的 pandas DataFrame 返回，列名和单位保持一致。

内置的免费数据提供方（无需 API 密钥）包括 Energy-Charts （欧洲）、Energinet（DK1/DK2）、SMARD（DE）、Elia（BE）、NESO （GB）、Elexon/BMRS（GB）、ENTSOG（欧盟天然气）和 Gas Networks Ireland。 Fingrid（FI）、GIE AGSI/ALSI（欧洲天然气）和 TenneT（NL）也已内置， 并使用免费的 API 密钥。 在美国，CAISO OASIS 和 NYISO 提供无需身份验证的市场和系统数据。EIA-930 提供全国范围内按小时统计的平衡责任区负荷、预测、燃料发电量和物理交换数据，需要免费的 EIA 密钥。 NASA POWER 提供全球历史气象和太阳能数据，无需 API 密钥；NOAA/NWS 提供美国官方逐小时预测。 ENTSO-E 和其他需要密钥的来源可按下文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 支持两种方式来提供这些密钥。

选项 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 环境：**设置一个环境变量即可，无需打开浏览器：

export CLARIGRID_API_KEY=your-clarigrid-uuid

SDK 会在每个会话首次调用 connect() 时，使用 CLARIGRID_API_KEY 从 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() 会累积覆盖范围。如果两个数据提供方都支持同一区域 / 数据集组合，则以后调用的 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	带有 2.5%/97.5% 置信界限的每日全国负荷预测	CH	无
redata	五分钟负荷/预测；每日平均发电量、占比和物理潮流；装机容量	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）	美国、属地及邻近水域（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。坐标会四舍五入至上游规定的四位小数精度，结果会统一转换为 UTC， SDK 会提供 MET Norway 要求的识别用 User-Agent。该端点仅提供当前预报； 此数据提供方不会获取历史模型数据。重复使用时必须遵循 MET Norway 署名要求。

EirGrid 使用官方的 Smart Grid Dashboard JSON 数据源，提供爱尔兰共和国和北爱尔兰系统需求的 15 分钟数据。 该数据源无需密钥，时间戳会根据仪表板的 UTC 值统一处理， 重复使用时必须遵循 EirGrid Group 开放数据许可，并注明 Supported by EirGrid Group Data。 SFOE 使用瑞士联邦能源办公室版本化的 Energy Dashboard 公共 API 获取 SDSC 全国用电量预测。源数据以每日 GWh 为单位，并以考虑夏令时的每日平均 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。

版权所有 (c) 2026 Alexander Hoogsteyn。