文档中心
0. 数据集说明
API 快速上手 · 要素字典 · 数据格式与同步 · 权限与配额 · 常见问题。所有数据带数据版本（dataVersion）与来源（source），可复算、可追溯。
1. 快速上手
公开接口无需登录（门户与摘要类）；逐点序列、同步与管理接口需要登录会话或令牌。
# 服务元信息与规模 curl -s https://tian.yao.energy/api/v1/weather/meta # 数据集目录（按要素聚合） curl -s "https://tian.yao.energy/api/v1/weather/products/catalog?days=7" # 场景数据集（含口径与质量门槛） curl -s https://tian.yao.energy/api/v1/weather/scenarios # 设备极端天气预警（未来 72h） curl -s https://tian.yao.energy/api/v1/weather/scenarios/extreme_weather # 逐点序列（需登录会话） curl -s -b "session=…" \ "https://tian.yao.energy/api/v1/weather/series?areaId=cn_410100&element=temp&source=ecmwf-ifs"
统一响应信封：
{code, message, data, traceId}；code=0 表示成功，traceId 可用于问题定位。2. 要素字典
| 要素 | 含义 | 单位 | 说明 |
|---|---|---|---|
temp | 2 米气温 | °C | 距地 2m 空气温度 |
humidity | 2 米相对湿度 | % | 0–100 |
dew_point | 露点温度 | °C | 空气冷却至饱和的温度 |
apparent_temp | 体感温度 | °C | 平台派生量 |
wind_speed | 10 米风速 | km/h | 源为 m/s 时已归一为 km/h |
wind_speed_100m | 100 米风速（轮毂高度） | km/h | 风电核心要素 |
wind_gust | 10 米阵风 | km/h | 设备安全与大风预警 |
wind_speed_hub | 轮毂高度风速 | km/h | 派生量 |
capacity_factor | 容量系数（0–1） | 1 | 风功率代理指标，非发电量 |
power_density | 风功率密度 | W/m² | 派生量 |
irradiance | 短波辐射（水平面总辐射） | W/m² | 光伏核心要素 |
direct_radiation / diffuse_radiation | 直接 / 散射辐射 | W/m² | — |
precip | 降水量 | mm | 逐时 |
precip_prob | 降水概率 | % | 集合分布自算 |
cloud_cover | 总云量 | % | — |
pressure / pressure_msl | 地面气压 / 海平面气压 | hPa | 同名不同义，已拆 id |
cape | 对流有效位能 | J/kg | 强对流判据 |
vpd | 饱和水汽压差 | kPa | 派生量 |
完整要素清单与每源支持能力见 /api/v1/weather/meta 的 elements 与 sources 字段。
3. 数据格式与同步
- JSON API：逐点序列 / 概率序列 / 场景数据集；时间一律 UTC（展示层换算北京时）。
- CSV / JSON 导出：数据面「查询」页可导出，文件内带
dataVersion、exportedAt。 - 企业实例增量同步：
/api/v1/weather/sync/manifest与/sync/series，按实例令牌分权、游标不透明。 - 网闸文件包：物理隔离环境使用 manifest + 校验 + 签名 的文件包（离线投递）。
4. 权限与配额
| 接口类别 | 鉴权 | 说明 |
|---|---|---|
| 摘要类（meta / catalog / quality / scenarios） | 公开只读 | 门户与质量页使用 |
| 逐点序列 / 概率 / 网格 | 登录会话（OIDC） | 401 时跳统一登录 |
| 数据接入（ingest） | 按源令牌（X-Ingest-Token） | 采集管道写入使用 |
| 企业同步 | 实例令牌 | 管理面可创建与吊销 |
| 管理接口（admin） | 会话 + 管理角色 / 服务器侧令牌 | 所有操作留痕到审计 |
配额：数据源侧受各自许可与配额约束（如 CMA 数据按授权配额）。平台侧对单源限流与退避有内置保护；如需更高配额请联系我们。
5. 常见问题
为什么某个区域查不到数据？
数据按区域分级采集：省级代表点每 3 小时、地市/区县每 6 小时。若该区域显示「待采集」，说明已登记但尚未开采；缺失时平台如实标注，不做插值或补零。
为什么不同源的值不一样？
多源数值预报本身存在差异，平台不混算、不取平均；每条序列带 source，可用数据面「对比分析」页看同一区域同一要素的多源曲线与偏差（MAE/Bias/RMSE）。
dataVersion 是什么？
一次采集产生一个数据版本，同一条序列可按版本复现历史；版本号形如 dv-20261028T081500Z。
预报精度如何？
平台用站点观测做真值标定，逐源逐要素给出 MAE/Bias/RMSE 与样本量，公开在数据质量页与管理面；样本不足如实标注。
能否私有化部署到企业内网？
可以。企业内网部署 Yao 实例，通过实例令牌增量同步中央层数据（不透明游标），物理隔离环境走网闸文件包。
如何申请账号与配额？
联系 datacenter@yao.energy，说明用途、区域范围与调用量，我们会评估后开通。