运梦气象 API 参考

通过 API Key 调用运梦天气平台接口。本页是 OpenAPI 3.x 规范的可读化对照；机器消费请直接下载 /api-specs/weather-v1.yaml。

认证方式

所有 API 请求通过 HTTP 请求头传递 API Key 进行身份认证。

请求头格式

Authorization: Bearer sk-xxxxxxxxxxxxxxxx

API Key 以 sk- 为前缀
使用 Bearer 令牌类型
在 HTTP Authorization 请求头中传递

认证流程

用户在运梦天气平台管理后台创建 API Key
客户端在每次请求中携带 Authorization: Bearer sk-xxx 请求头
网关验证 API Key 有效性并转换为内部认证令牌
下游服务基于内部令牌完成用户身份识别

认证失败响应

{
  "code": 401,
  "success": false,
  "data": null,
  "msg": "API Key 无效或已被禁用"
}

API Key 应妥善保管，不要在客户端代码中硬编码。泄露后应立即在管理后台禁用并重新生成。

气象数据下载

同步等待下载完成，直接返回数据结果。会实际扣费，出错时自动退款。

方法: POST
路径: /api/energy-weather/search/weather/action/downloadSync
完整 URL: https://console.yun-meng.top/api/energy-weather/search/weather/action/downloadSync

请求参数 (JSON Body)

参数	类型	必填	说明
`lat`	number	是	纬度，范围 (-90, 90)
`lon`	number	是	经度，范围 (-180, 180)
`dataSourceId`	string	是	数据源标识（见下方数据源说明）
`stime`	string	是	开始时间，格式 `yyyy-MM-dd HH:mm`（与 /api-specs/weather-v1.yaml 严格一致）
`etime`	string	是	结束时间，格式 `yyyy-MM-dd HH:mm`
`fields`	string	是	下载字段列表（见下方字段说明）
`timezone`	string	是	时区偏移，例如东八区为 `"8"`

请求示例：

{
    "lon": 117.35184,
    "lat": 32.03253,
    "dataSourceId": "era5",
    "stime": "2022-01-01 00:00",
    "etime": "2022-01-01 23:00",
    "timezone": "8",
    "fields": ["tas"]
}

响应

Content-Type: application/json，统一 envelope（与 /api-specs/weather-v1.yaml 严格一致）：

{
    "code": 200,
    "success": true,
    "data": {
        "timeList": [
            "2022-01-01 00:00",
            "2022-01-01 01:00",
            "..."
        ],
        "tas": [
            6.344323730468773,
            5.634362792968773,
            "..."
        ]
    },
    "msg": "success",
    "errorCode": 0
}

字段	类型	说明
`code`	integer	HTTP 语义状态码，成功 200
`success`	boolean	业务成功标志
`data.timeList`	string	时间列表，格式 `yyyy-MM-dd HH:mm`
`data.<field>`	number	各请求字段的数值数组，与 `timeList` 一一对应（如 `data.tas`、`data.ws`）
`msg`	string	文案消息
`errorCode`	integer	业务错误码，0 表示无错

出错时 envelope code=400、success=false、msg 包含余额不足等提示；下载失败时自动退款。

调用示例

import requests

url = 'https://console.yun-meng.top/api/energy-weather/search/weather/action/downloadSync'
headers = {
    'Authorization': 'Bearer sk-your-api-key',
    'Content-Type': 'application/json',
}
data = {
    "lat": 32.03253,
    "lon": 117.35184,
    "dataSourceId": "era5",
    "stime": "2022-01-01 00:00",
    "etime": "2022-01-20 23:00",
    "fields": ["tas", "ws"],
    "timezone": "8"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

if result["success"]:
    data = result["data"]
    time_list = data["timeList"]
    tas = data["tas"]
    print(f"共 {len(time_list)} 条数据")
    print(f"第一条：{time_list[0]}，气温：{tas[0]}℃")
else:
    print("请求失败：", result["msg"])

可用字段 (fields)

字段代码	名称	单位	说明
`tas`	气温	℃	地面约 1.5–2 米处百叶箱中的温度
`hurs`	相对湿度	%	地面约 1.25–2 米的空气湿度
`sp`	气压	hPa	作用在单位面积上的大气压力
`pr`	降水量	mm/h	地面积聚的液态或固态降水深度
`uas`	纬向风	m/s	地面约 10 m 风的纬向分量（西风为正）
`vas`	经向风	m/s	地面约 10 m 风的经向分量（南风为正）
`ws`	地面风速	m/s	地面约 10 米的风速
`wd`	风向	°	风的来向，正北方向为 0°，顺时针方向为正
`rsds`	地表水平辐射	W/㎡	地表水平方向获得的太阳辐射
`dni`	法向直接辐射	W/㎡	在与太阳光线垂直的平面上接收到的直接辐射
`dhi`	散射辐射	W/㎡	以漫射形式到达地球表面的辐射能
`u100`	100 米纬向风速	m/s	距地面约 100 m 处纬向风速（西风为正），风能资源评估关键指标
`v100`	100 米经向风速	m/s	距地面约 100 m 处经向风速（南风为正）
`u10n`	10 米中性纬向风速	m/s	中性层结状态下距地面 10 m 处的纬向风速
`v10n`	10 米中性经向风速	m/s	中性层结状态下距地面 10 m 处的经向风速

数据源 (dataSourceId)

完整 enum 见 /api-specs/weather-v1.yaml；以下表格按公开数据源口径说明（详见数据源）。

代码	名称	数据源类型	说明
`era5`	欧洲中期天气中心 ERA5	历史再分析	ECMWF 第五代再分析（历史回测、资源评估）
`nasa`	美国国家航空航天局 MERRA-2	历史再分析	NASA GMAO 第二代再分析（历史回测、气候复盘）
`zg1`	中国数源 V1.0	历史	中国区历史气象数据源，按经纬度查询
`ger`	德国气象局	未来预报	德国气象局数值预报（短期预测、调度，未来 ~7 天）