预警数据

访问限制

本部分 API 属于增值服务，不适用于免费赠送额度，如需数据请升级至付费套餐。

预警独立 API

建议使用独立的 v3 预警 API；v2 预警仅处于维护状态，不再增加新功能。

气象预警数据：在任意一个天气数据接口（实况、分钟级、小时级、天级、综合接口）上附加 alert=true 参数，即可在响应的 result.alert 中获取目标位置当前生效的预警。

预警信息同中央气象台同步，按请求经纬度匹配行政区划（省/市/区县层级）返回，不适用栅格空间分辨率。非直辖市的省级预警不返回；下级已发布同类型（类型码前 2 位相同）预警时，上级的同类型预警不返回。详情见 时空变量覆盖情况。

请求

GET https://api.caiyunapp.com/v2.6/{token}/{经度},{纬度}/{接口}

其中 {接口} 为 realtime、minutely、hourly、daily、weather 之一。

路径参数

参数	说明
token	API 认证凭证，详见 认证与鉴权；token 需具备预警权限，响应才会附带 result.alert
经度	目标地点经度
纬度	目标地点纬度

注意：URL 路径中经度在前、纬度在后（如 116.3176,39.9760）；响应中的 location 字段为 [纬度, 经度] 顺序。

查询参数

参数	必填	默认值	取值范围	说明
alert	否	false	true/false	传 alert=true 且 token 具备预警权限时，响应才附带 result.alert
lang	否	zh_CN	zh_CN/zh_TW/en_US/en_GB/ja	自然语言描述的语言，未匹配时回落 zh_CN，见 语言
unit	否	metric	metric/metric:v1/metric:v2/SI/imperial	单位制，其他取值返回 422，见 单位制
callback	否	—	—	JSONP 回调函数名

各接口特有的步长参数（如 dailysteps、hourlysteps）见对应接口文档。

请求示例

curl "https://api.caiyunapp.com/v2.6/{token}/116.3176,39.9760/realtime?alert=true"

{
  "status": "ok", // 返回状态
  "api_version": "v2.6", // API 版本
  "api_status": "active", // API 状态
  "lang": "zh_CN",
  "unit": "metric",
  "tzshift": 28800,
  "timezone": "Asia/Shanghai",
  "server_time": 1640759880,
  "location": [39.976, 116.3176],
  "result": {
    "alert": {
      "status": "ok", // 预警信息的状态
      "content": [
        {
          "province": "北京市", // 省份
          "status": "预警中", // 预警状态
          "code": "0501", // 预警代码
          "description": "海淀区气象台29日07时25分发布大风蓝色预警,预计，当前至29日16时，海淀区将有3、4级偏北风，阵风6、7级，请注意防范。", // 预警描述
          "regionId": "101010200", // 地区 ID
          "county": "无", // 县区
          "pubtimestamp": 1640733900, // 发布时间戳
          "latlon": [39.959912, 116.298056], // 发布单位所在地 [纬度, 经度]
          "city": "海淀区", // 城市
          "alertId": "11010841600000_20211229072633", // 预警 ID
          "title": "海淀区气象台发布大风蓝色预警[IV/一般]", // 预警标题
          "adcode": "110108", // 区域代码
          "source": "国家预警信息发布中心", // 预警信息来源
          "location": "北京市海淀区", // 地点
          "request_status": "ok" // 请求状态
        }
      ],
      "adcodes": [
        {
          "adcode": 110000, // 区域代码
          "name": "北京市" // 区域名称
        },
        {
          "adcode": 110108, // 区域代码
          "name": "海淀区" // 区域名称
        }
      ]
    },
    "realtime": {
      // 实时信息
    },
    "primary": 0 // 主要信息
  }
}

响应字段

JSONPath	类型	说明
$.result.alert.status	string	预警数据块的状态
$.result.alert.content[].province	string	省，如 "福建省"
$.result.alert.content[].city	string	市，如 "三明市"
$.result.alert.content[].county	string	县，如 "无"
$.result.alert.content[].status	string	预警状态，只会返回 "预警中"
$.result.alert.content[].code	string	预警代码，4 位：前 2 位为类型、后 2 位为级别，如 "0902"
$.result.alert.content[].description	string	预警描述原文
$.result.alert.content[].regionId	string	地区 ID，如 "101010200"
$.result.alert.content[].pubtimestamp	number	发布时间，unix 秒，如 1587443583
$.result.alert.content[].latlon	array<number>	发布单位所在地 [纬度, 经度]
$.result.alert.content[].alertId	string	预警 ID，如 "35040041600001_20200421123203"
$.result.alert.content[].title	string	预警标题，如 "三明市气象台发布雷电黄色预警[Ⅲ 级/较重]"
$.result.alert.content[].adcode	string	区域代码，如 "350400"
$.result.alert.content[].source	string	发布单位，如 "国家预警信息发布中心"
$.result.alert.content[].location	string	地点，如 "福建省三明市"
$.result.alert.content[].request_status	string	请求状态，恒为 "ok"
$.result.alert.adcodes	array<object>	请求位置的行政区划数组 [{adcode, name}]，恒输出（无预警时也会返回）

备注：

• 响应不返回 expire_time 字段。
• 无预警时，result.alert 为 {"status": "ok", "content": [], "adcodes": [...]}。
• 预警上游异常时，content 为 [] 且 adcodes 为 null。

编码规则

预警代码取自 code 字段，预警代码的前两位是预警信息类型，预警代码的后两位是预警级别。举例："code": "0901”，可以分解出结构：预警类型编码＋预警级别编码，于是我们得到雷电蓝色预警。

类型编码对照表

预警级别	级别编码
台风	01
暴雨	02
暴雪	03
寒潮	04
大风	05
沙尘暴	06
高温	07
干旱	08
雷电	09
冰雹	10
霜冻	11
大雾	12
霾	13
道路结冰	14
森林火险	15
雷雨大风	16
春季沙尘天气趋势预警	17
沙尘	18

级别编码对照表

预警级别	级别编码
白色	00
蓝色	01
黄色	02
橙色	03
红色	04

错误

接口错误统一返回如下结构，HTTP 状态码与含义详见 错误信息。

{
  "status": "failed",
  "error": "token is invalid",
  "api_version": "2.6"
}