Weather Alerts

Risk Notice (v2 Alerts Only)

Weather data is cached on a latitude/longitude grid, while alerts are published by administrative division. Administrative boundaries are irregular polygons and do not align with the grid; near boundary areas, due to grid caching, the response may include alerts for a neighboring (non-local) division. Switch to the v3 Alert API to avoid this issue.

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

http

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

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

Path Parameters

Parameter	Description
`token`	API token; see Authentication. 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`/`ug`/`bo`	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

bash

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

json

{
  "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	Type	Description
`$.result.alert.status`	string	Status of the alert data block
`$.result.alert.content[].province`	string	Province, e.g. "Fujian Province"
`$.result.alert.content[].city`	string	City, e.g. "Sanming"
`$.result.alert.content[].county`	string	County, e.g. "none"
`$.result.alert.content[].status`	string	Alert status, always "alerting"（预警中）
`$.result.alert.content[].code`	string	4-digit alert code: first 2 digits are the type, last 2 digits are the level, e.g. "0902"
`$.result.alert.content[].description`	string	Original alert description text
`$.result.alert.content[].regionId`	string	Region ID, e.g. "101010200"
`$.result.alert.content[].pubtimestamp`	number	Publish time, unix seconds, e.g. 1587443583
`$.result.alert.content[].latlon`	`array<number>`	Location of the issuing agency, `[latitude, longitude]`
`$.result.alert.content[].alertId`	string	Alert ID, e.g. "35040041600001_20200421123203"
`$.result.alert.content[].title`	string	Alert title, e.g. "Sanming Meteorological Observatory issued a yellow thunderstorm alert [III/Relatively Severe]"
`$.result.alert.content[].adcode`	string	Administrative division code, e.g. "350400"
`$.result.alert.content[].source`	string	Issuing source, e.g. "National Early Warning Information Release Center"
`$.result.alert.content[].location`	string	Place, e.g. "Sanming, Fujian Province"
`$.result.alert.content[].request_status`	string	Request status, always "ok"
`$.result.alert.adcodes`	`array<object>`	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.

json

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

Weather Alerts ​

Request ​

Path Parameters ​

Query Parameters ​

Request Example ​

Response Fields ​

Encoding Rules ​

Alert Type Codes ​

Alert Level Codes ​

Errors ​