接口参考

规范 V1.0 · 服务陆续开放中

以下 HTTP 接口为接口规范定义，字段命名、单位、累积口径与 CSV 数据规范完全一致。现阶段数据以 CSV 文件交付为主，HTTP 服务按客户接入节奏陆续开放——请以商务对接确认的交付方式为准。

通用约定

• 响应体统一为 { code, message, data } 结构，code = 0 表示成功；
• 时间参数一律为北京时间 ISO 8601 格式（含时区偏移）；起报时间（issue）为 UTC；
• 字段单位与 CSV 规范一致（K、Pa、J/m² 累积量），换算由调用方负责（见注意事项）。

接口清单

方法	路径	说明
GET	/api/v1/farms	场站列表（farm_id、经纬度）
GET	/api/v1/forecast/issues	可用起报时次列表
GET	/api/v1/forecast	查询预报数据（主接口）

查询预报数据

GET /api/v1/forecast

请求参数

参数	类型	必填	说明
farm_id	string	与经纬度二选一	场站编号，如 HuaR_093
lon	decimal	与 farm_id 二选一	经度，需与 lat 同时提供
lat	decimal	与 farm_id 二选一	纬度
issue	string	否	起报时间（UTC，yyyyMMddHH），缺省为最新起报
start	string	否	起始有效时间（北京时间，ISO 8601），缺省 +0h
end	string	否	截止有效时间，缺省 +360h
elements	string[]	否	字段子集，缺省返回全部 15 个数据字段
page / size	int	否	分页参数，缺省 size = 96（一天）

请求示例

curl "http://api.example.com/api/v1/forecast
     ?farm_id=HuaR_093
     &start=2026-08-27T20:00:00
     &end=2026-08-28T20:00:00
     &elements=t2m,spd100,tr"

响应示例（HTTP 200）

{
  "code": 0,
  "message": "ok",
  "data": {
    "farm_id": "HuaR_093",
    "lat": 36.35208,
    "lon": 102.95839,
    "issue_time_utc": "2026-08-27T12:00:00Z",
    "timezone": "UTC+8",
    "resolution_minutes": 15,
    "total": 96,
    "items": [
      {
        "date_time": "2026-08-27T20:00:00+08:00",
        "t2m": 289.08,
        "spd100": 2.83,
        "tr": 0.0
      }
    ]
  }
}

错误码

HTTP 状态	code	说明
400	40001	参数缺失或格式错误
404	40401	farm_id 或起报时次不存在
422	42201	坐标超出服务范围
500	50000	服务内部错误