气象数据

ERA5 历史气象数据下载完全指南 — 运梦气象 API 与 cdsapi 官方通道实战对比

2026-02-10 · 南京运梦科技算法团队 · 评审算法负责人

ERA5 数据下载流程示意图

摘要：本文从 ERA5 数据集本身的结构与变量出发，给出在 Python 工程中拿到一段地理范围、一段时间窗内某几个变量（如 2m 气温、10m 风、地面短波辐射）的两条主流通道：① 运梦气象 API（推荐，适合工程化集成）、② ECMWF CDS 官方 cdsapi（适合学术研究或大批量初始建库）。两条通道在排队、速率、字段命名、合规与运维成本上差异显著，本文给出可直接复制的代码 + 实测建议。

关键要点

ERA5 是 ECMWF 第五代再分析数据集，覆盖 1940 年至今、水平分辨率 0.25°（约 31 km）、时间步长 1 小时，是新能源历史回测与电量评估的事实标准。
下载有两条通道：运梦气象 API（推荐，适合工程化集成）与 ECMWF CDS 官方 cdsapi（适合学术研究或大批量初始建库）。
运梦气象 API 返回的 JSON 已按 CF 标准统一字段命名（tas/rsds 等），无需再写 t2m → tas 换名逻辑；CDS 下发的是 ECMWF 短名且单位需自行换算（如 ssrd 为 J·m⁻²，需 / 3600 转 W·m⁻²）。
ERA5 数据约滞后 T-5 天，属再分析体系固有限制；需要未来预报请用德国气象局（dataSourceId=ger）。
运梦气象 API 支持免登录试用，每日 5 次调用配额，个人 / 小团队可零成本验证。

ERA5 是 ECMWF（欧洲中期天气预报中心）的第五代再分析（reanalysis）数据集，覆盖 1940-01-01 至当前（约滞后 5 天）的全球网格化历史气象，水平分辨率 0.25°（约 31 km），时间分辨率 1 小时。再分析的含义是：把卫星观测、地面站、探空、雷达、浮标等多源观测，通过 ECMWF 的同化系统投影到一致的 3D 网格上，得到「物理一致、时空连续」的伪观测。再分析的精度通常优于直接的站点插值，是新能源行业做历史回测、容量配置、电量评估、长时间序列建模的事实标准。

常见误解：再分析不是「预报历史化」，而是「观测 + 模式」融合的结果；ERA5 的气温/风速字段在大多数地表平坦区域与气象站观测的偏差在 ±1 K / ±1 m·s⁻¹ 量级。

1.1 变量命名与 CF 标准

ERA5 沿用 CF（Climate and Forecast）变量命名约定，常用字段：

变量名	含义	单位	高度 / 层
`tas`	2m 气温	℃	2 m
`hurs`	2m 相对湿度	%	2 m
`sp`	地面气压	hPa	表面
`pr`	降水量	mm/h（每小时累计，与 mm 数值一致）	表面
`uas` / `vas`	10m 纬向 / 经向风	m·s⁻¹	10 m
`u100` / `v100`	100m 纬向 / 经向风	m·s⁻¹	100 m
`u10n` / `v10n`	10m 中性大气稳定度风	m·s⁻¹	10 m
`rsds`	地面入射短波辐射	W·m⁻²	表面
`dni`	直接法向辐照（DNI）	W·m⁻²	表面
`dhi`	散射水平辐照（DHI）	W·m⁻²	表面
`ws` / `wd`	派生：风速 / 风向	m·s⁻¹ / °	10 m / 100 m

⚠️ 注意 ECMWF 原始 GRIB 变量名（如 t2m、u10、ssrd）与 CF 名不完全一致；运梦气象 API 输出的字段口径与公开字段表保持一致，可避免在 NetCDF / GRIB 工具栈与业务系统之间反复换名。

1.2 时空范围

空间：全球 0.25° × 0.25° 网格（720 × 1440 cell）
时间：1940-01-01 至今，1 小时步长（也提供月平均，但本文聚焦小时级）
滞后：约 T-5 天（ECMWF 的 ERA5T 子集滞后更短，但稳定性略低，新能源生产环境一般使用稳定版 ERA5）

2. 通道一：运梦气象 API（推荐工程化集成）

运梦气象 API 把 ERA5 与德国气象局等已对外开放的数据源在内部仓库中预切片，并按经纬度同步下发（具体 dataSourceId 见 /api-specs/weather-v1.yaml 枚举）。下面给出最常用的「按经纬度点 + 时间段 + 变量集」下载示例。

2.1 接口签名

POST /api/energy-weather/search/weather/action/downloadSync
Host: console.yun-meng.top
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>

公开契约以 /api-specs/weather-v1.yaml 为准。

2.2 请求体

字段名与 OpenAPI 规范严格一致：

字段	类型	说明
`dataSourceId`	string	`era5`（欧洲中期天气中心，历史）/ `nasa`（美国国家航空航天局，历史）/ `zg1`（中国数源V1.0，历史）/ `ger`（德国气象局，预报）（小写）
`lat` / `lon`	number	WGS84 单点经纬度（v1 暂不支持 bbox，多点请并发调用）
`stime` / `etime`	string	起止时间，格式 `yyyy-MM-dd HH:mm`（按 `timezone` 解释）
`fields`	string	CF 字段名数组（tas/hurs/sp/pr/uas/vas/ws/wd/rsds/dni/dhi/u100/v100/u10n/v10n）
`timezone`	string	必填，时区偏移，例如 `8`

2.3 Python 完整示例（无第三方依赖）

import os
import time
import requests

API = "https://console.yun-meng.top/api/energy-weather/search/weather/action/downloadSync"
TOKEN = os.environ["YUNMENG_TOKEN"]  # 试用入口注册即得

payload = {
    "dataSourceId": "era5",
    "lat": 31.5, "lon": 118.5,           # 长三角任意一点
    "stime": "2024-01-01 00:00",
    "etime": "2024-12-31 23:00",
    "fields": ["tas", "uas", "vas", "u100", "v100", "rsds"],
    "timezone": "8",
}

t0 = time.time()
resp = requests.post(
    API,
    headers={"Authorization": f"Bearer {TOKEN}"},
    json=payload,
    timeout=600,
)
resp.raise_for_status()

result = resp.json()
if not result.get("success"):
    raise RuntimeError(result.get("msg", "查询失败"))

data = result["data"]
time_list = data["timeList"]
tas = data["tas"]
rsds = data["rsds"]

print(f"查询完成，耗时 {time.time() - t0:.1f}s，共 {len(time_list)} 条")
print(f"第一条：{time_list[0]}，气温={tas[0]}，地表短波辐射={rsds[0]}")

2.4 性能与限制

同步查询适合单点、少量字段、可控时间窗的工程化接入；返回体为 JSON envelope，data.timeList 与各字段数组一一对应
大时间窗或多字段请求建议切片为多个 stime/etime 子段并发拉取；异步任务接口尚未在 v1 OpenAPI 中对外承诺，请以 /api-specs/weather-v1.yaml 当前公开的 endpoint 为准
速率：试用账号 60 次/小时，付费账号无硬限速但按流量计费

2.5 字段保真性

API 返回的 JSON 已按公开字段表统一字段命名，不需要再写一层 t2m → tas 的换名逻辑。timeList 与每个字段数组按下标一一对应，在 Python 里可直接转成 DataFrame：

import pandas as pd

df = pd.DataFrame({
    "time": pd.to_datetime(data["timeList"]),
    "tas": data["tas"],
    "rsds": data["rsds"],
})
print(df.head())

3. 通道二：ECMWF CDS 官方 `cdsapi`（学术 / 大批量建库）

CDS（Climate Data Store）是 ECMWF 官方的 ERA5 原始下发通道，免费但有显著的工程化短板，仅作为对比说明。

3.1 安装与凭据

pip install cdsapi
# 在 ~/.cdsapirc 写入 UID + API key（CDS 网站注册后获取）

3.2 最小示例

import cdsapi

c = cdsapi.Client()
c.retrieve(
    "reanalysis-era5-single-levels",
    {
        "product_type": "reanalysis",
        "variable": [
            "2m_temperature",
            "10m_u_component_of_wind",
            "10m_v_component_of_wind",
            "surface_solar_radiation_downwards",
        ],
        "year": "2024",
        "month": [f"{m:02d}" for m in range(1, 13)],
        "day":   [f"{d:02d}" for d in range(1, 32)],
        "time":  [f"{h:02d}:00" for h in range(24)],
        "area":  [35, 115, 28, 122],   # north, west, south, east
        "format": "netcdf",
    },
    "era5_yrd_2024_cds.nc",
)

3.3 工程化短板（实测）

排队：CDS 队列高峰期（欧洲工作时间 10:00–18:00 UTC）等待时间 30 min – 6 h 不等；新能源日常拉取被排队拖死，CI 几乎无法 SLA
变量命名：用的是长字符串 "2m_temperature"，不是 CF 名；下载下来的 NetCDF 字段是 t2m，与业务代码命名再次对不上，需要本地维护一张换名表
单位：t2m 单位是 K，需要业务侧 -273.15 转换；辐射变量 ssrd 单位是 J·m⁻²（累积值），需 / 3600 才能得到 W·m⁻² 的平均功率密度
ToS：CDS 数据用于商业产品分发前需阅读 ECMWF licence；学术研究无障碍，商业接入建议法务把关
token 流程：CDS 凭据有有效期，CI/CD 维护成本与 Vault/KMS 不直接对接

结论：研究、回测、批量建库阶段用 CDS 没问题；走到生产 / 工程化 / SLA 阶段，推荐通过运梦气象 API 把这层运维琐事屏蔽掉。

4. 实战：从下载到光伏功率回测

拿到 ERA5 字段数组只是起点。下面给出一个最小 Demo：把上文返回的 JSON 转成时间序列 → 读取 GHI → 反推光伏阵列出力（仅作示意，不替代专业 PV 模拟）。

import numpy as np
import pandas as pd

df = pd.DataFrame({
    "time": pd.to_datetime(data["timeList"]),
    "rsds": data["rsds"],
}).set_index("time")

# GHI：运梦 API 的 rsds 已按 W·m⁻² 返回
ghi = df["rsds"].to_numpy()

# 简化 PV 出力：P = η · A · GHI（忽略温度修正、入射角、损耗）
eta   = 0.18           # 组件效率
area  = 100.0          # 100 m²
power = eta * area * np.clip(ghi, 0, None)  # 单位 W

# 简单按小时累计 → 每月电量（kWh）
df["power_W"] = power
monthly = df.resample("ME")["power_W"].sum() / 1000
print(monthly.head())

真正做光伏功率预测推荐用 pvlib，加入逆变器模型、组件温度、入射角损失、阴影。本 Demo 仅作 ERA5 字段拿到后第一步落地演示。

5. 选型决策树

你的目标？
├── 学术研究 / 一次性回测建库         → CDS（免费、容忍排队）
├── 工程化集成 / 日级别拉取            → 运梦气象 API
├── 准实时 (≤ 5 天滞后) 商用产品       → 运梦气象 API（CDS 滞后不稳）
└── 全球大范围 (≥ 1 国) × 全变量回填   → 两者结合：CDS 离线初始化 + 运梦 API 增量更新

6. 常见问题

Q1：运梦气象 API 的 ERA5 字段单位与 CDS 一致吗？ A：运梦 API 已做单位归一 —— tas 是 ℃、rsds 是 W·m⁻²、pr 是 mm/h（每小时累计降水深度，与 mm 数值一致）。CDS 用的是 ECMWF 短名（如 t2m、ssrd），且 t2m 为开尔文（K）、ssrd 为累积 J·m⁻²，命名与单位都不同（详见 §3.3）。

Q2：能否拿到 ERA5 的更高分辨率（< 0.25°）？ A：ERA5 原生 0.25°；如需 10 km 级，可参考 ECMWF-HRES（~9km）等更高分辨率模式，或自行做 WRF / RegCM 降尺度。

Q3：ERA5 在中国区是否会有偏差？ A：地表平坦区域偏差较小（±1 K / ±1 m·s⁻¹）；西部高原、复杂地形、城市热岛区域偏差会放大。建议结合本地气象站做偏差订正（BC / quantile mapping）。

Q4：滞后 5 天意味着什么？ A：今天是 T 日，能下到的最新数据是 T-5 日左右。这是再分析体系本身的限制（卫星 / 站点观测同化窗口需要时间），不是 API 限制。预报场景请用德国气象局（未来 ~7 天，dataSourceId=ger）。

Q5：API 试用要钱吗？ A：免登录试用，每日 5 次调用配额（按 IP + guestId + User-Agent 综合识别），个人 / 小团队零成本验证。注册正式账号后可叠加「连续体验计划」：连续 90 天内，每天首次成功调用后补发 2 积分至账户（积分不可提现，仅用于天气 API 调用抵扣）。系统内余额一律以积分显示，充值环节才涉及人民币换算；实时积分以控制台钱包为准。

7. 参考与延伸阅读

Hersbach, H., Bell, B., Berrisford, P., et al. (2020). The ERA5 global reanalysis. Quarterly Journal of the Royal Meteorological Society, 146(730), 1999–2049. DOI: 10.1002/qj.3803
ERA5 数据集（CDS）：Copernicus Climate Change Service (C3S) Climate Data Store. DOI: 10.24381/cds.adbb2d47
Olauson, J. (2018). ERA5: The new champion of wind power modelling? Renewable Energy, 126, 322–331. DOI: 10.1016/j.renene.2018.03.056
Urraca, R., Huld, T., Gracia-Amillo, A., et al. (2018). Evaluation of global horizontal irradiance estimates from ERA5 and COSMO-REA6 reanalyses using ground and satellite-based data. Solar Energy, 164, 339–354. DOI: 10.1016/j.solener.2018.02.059

8. 下一步

准备工程化接入？看运梦气象 API ERA5 产品页。
需要光伏功率预测落地能力？看光伏功率预测产品页。
想看完整字段表与 OpenAPI 规范？下载 /api-specs/weather-v1.yaml。

免费试用 →

相关阅读