Weather Alerts

Alert Independent API

We recommend the independent v3 Alert API; alerts in v2 are in maintenance mode and will not gain new features.

Weather alert data: add the alert=true parameter to any weather data endpoint (Realtime, Minutely, Hourly, Daily, Combined) to get the currently active alerts for the requested location in result.alert.

Alert information is synchronized with the Central Meteorological Bureau and is returned by matching the requested coordinates to administrative divisions (province/city/district levels); grid spatial resolution does not apply. Province-level alerts of non-municipality provinces are not returned; when a lower-level division has issued an alert of the same type (same first 2 digits of the type code), the upper-level alert of that type is not returned. For details, see Variable Coverage.

Request

GET https://api.caiyunapp.com/v2.6/{token}/{longitude},{latitude}/{endpoint}?alert=true

{endpoint} is one of realtime, minutely, hourly, daily, weather.

Path Parameters

Parameter	Description
token	API token; the token must have alert permission for the response to include result.alert
longitude	Longitude of the target location
latitude	Latitude of the target location

Note: in the URL path, longitude comes first, latitude second (e.g. 116.3176,39.9760); the location field in the response is in [latitude, longitude] order.

Query Parameters

Name	Required	Default	Range	Description
alert	No	false	true/false	Only with alert=true and an alert-enabled token does the response include result.alert
lang	No	zh_CN	zh_CN/zh_TW/en_US/en_GB/ja	Language of natural-language descriptions; falls back to zh_CN when unmatched. See Languages
unit	No	metric	metric/metric:v1/metric:v2/SI/imperial	Unit system; any other value returns 422. See Units
callback	No	-	-	JSONP callback name

Step parameters specific to each endpoint (e.g. dailysteps, hourlysteps) are documented on the corresponding endpoint pages.

Request Example

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

{
  "status": "ok",
  "api_version": "v2.6",
  "api_status": "active",
  "lang": "zh_CN",
  "unit": "metric",
  "tzshift": 28800,
  "timezone": "Asia/Shanghai",
  "server_time": 1640759880,
  "location": [39.976, 116.3176],
  "result": {
    "alert": {
      "status": "ok",
      "content": [
        {
          "province": "Beijing",
          "status": "alerting",
          "code": "0501",
          "description": "Haidian District Meteorological Observatory issued a blue gale alert at 07:25 on the 29th. From now until 16:00 on the 29th, Haidian District will see northerly winds of force 3-4, with gusts of force 6-7. Please take precautions.",
          "regionId": "101010200",
          "county": "none",
          "pubtimestamp": 1640733900,
          "latlon": [39.959912, 116.298056],
          "city": "Haidian District",
          "alertId": "11010841600000_20211229072633",
          "title": "Haidian District Meteorological Observatory issued a blue gale alert [IV/General]",
          "adcode": "110108",
          "source": "National Early Warning Information Release Center",
          "location": "Haidian District, Beijing",
          "request_status": "ok"
        }
      ],
      "adcodes": [
        {
          "adcode": 110000,
          "name": "Beijing"
        },
        {
          "adcode": 110108,
          "name": "Haidian District"
        }
      ]
    },
    "realtime": {
      //
    },
    "primary": 0
  }
}

Response Fields

JSONPath $.result.alert.	Description
status	Status of the alert data block
content[].province	Province, e.g. "Fujian Province"
content[].city	City, e.g. "Sanming"
content[].county	County, e.g. "none"
content[].status	Alert status, always "alerting"（预警中）
content[].code	4-digit alert code: first 2 digits are the type, last 2 digits are the level, e.g. "0902"
content[].description	Original alert description text
content[].regionId	Region ID, e.g. "101010200"
content[].pubtimestamp	Publish time, unix seconds, e.g. 1587443583
content[].latlon	Location of the issuing agency, [latitude, longitude]
content[].alertId	Alert ID, e.g. "35040041600001_20200421123203"
content[].title	Alert title, e.g. "Sanming Meteorological Observatory issued a yellow thunderstorm alert [III/Relatively Severe]"
content[].adcode	Administrative division code, e.g. "350400"
content[].source	Issuing source, e.g. "National Early Warning Information Release Center"
content[].location	Place, e.g. "Sanming, Fujian Province"
content[].request_status	Request status, always "ok"
adcodes	Administrative divisions of the requested location, [{adcode, name}]; always returned (even when there are no alerts)

Notes:

• The expire_time field is not returned.
• When there are no alerts, result.alert is {"status": "ok", "content": [], "adcodes": [...]}.
• When the alert upstream fails, content is [] and adcodes is null.

Encoding Rules

The alert code is taken from the code field: the first two digits of the alert code are the alert type, and the last two digits are the alert level. For example, "code": "0901" decomposes into the structure alert type code + alert level code, giving a blue thunderstorm alert.

Alert Type Codes

Alert Type	Type Code
Typhoon（台风）	01
Rainstorm（暴雨）	02
Snowstorm（暴雪）	03
Cold Wave（寒潮）	04
Gale（大风）	05
Sandstorm（沙尘暴）	06
Heat Wave（高温）	07
Drought（干旱）	08
Thunderstorm（雷电）	09
Hail（冰雹）	10
Frost（霜冻）	11
Fog（大雾）	12
Haze（霾）	13
Road Icing（道路结冰）	14
Forest Fire Risk（森林火险）	15
Thunderstorm Gale（雷雨大风）	16
Spring Sand & Dust Weather Trend Alert（春季沙尘天气趋势预警）	17
Sand & Dust（沙尘）	18

Alert Level Codes

Alert Level	Level Code
White（白色）	00
Blue（蓝色）	01
Yellow（黄色）	02
Orange（橙色）	03
Red（红色）	04

Errors

Error responses have the following structure. See Error Messages for HTTP status codes and their meanings.

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