Combined Weather

The combined endpoint packs realtime, minutely, hourly, and daily data into one request; minutely is returned only with Enterprise plan permission. With alert=true and an alert-enabled token, it also includes alert data.

Update Frequency and Spatial Resolution

The combined weather endpoint follows the update frequency and spatial resolution of each included data type. For details, see Variable Coverage.

Data Type	Update Frequency	Spatial Resolution
Real-time weather data	Minute-cadence rolling updates (typically every 1-5 min)	~1 km scale (varies by station coverage)
Minute-level precipitation data	Minute-by-minute sliding updates (publish cycle ~5 min; temporal resolution 1 min)	~1 km scale
Hourly forecast data	Near-term rolling updates (publish cycle ~5-15 min); other lead times use cycle-based batch updates (~hourly)	~9-13 km scale (precip-related fields can be refined to ~1 km in first 2 hours)
Daily forecast data	Batch updates (typically 2-4 runs/day)	~9-13 km scale (aggregated from hourly data)

Alert information is synchronized with the Central Meteorological Bureau and is returned by alert area and administrative division. Grid spatial resolution does not apply.

Request

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

Path Parameters

Parameter	Description
token	API token; see Authentication
longitude	Longitude of the target location
latitude	Latitude of the target location

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

Query Parameters

Name	Required	Default	Range	Description
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
alert	No	false	true/false	With alert=true and an alert-enabled token, the response includes result.alert. See Weather Alerts
callback	No	—	—	JSONP callback name
dailysteps	No	5	1~16	Number of days to return; normally 1~15, and dailysteps=16 requires dailystart=-1. The effective limit depends on your plan, and requests beyond it are truncated to the plan's limit
dailystart	No	0	-1, 0	Only -1 and 0 are supported (-1 goes back one day); any other value returns 422
hourlysteps	No	48	1~360	Number of hours to return; a multiple of 24 is recommended. The effective limit depends on your plan, and requests beyond it are truncated to the plan's limit

Request Example

curl "https://api.caiyunapp.com/v2.6/{token}/116.3176,39.9760/weather?alert=true&dailysteps=1&hourlysteps=24"

{
  "status": "ok",
  "api_version": "v2.6",
  "api_status": "active",
  "lang": "zh_CN",
  "unit": "metric",
  "tzshift": 28800,
  "timezone": "Asia/Shanghai",
  "server_time": 1640758065,
  "location": [39.976, 116.3176],
  "result": {
    "alert": {
      //
    },
    "realtime": {
      //
    },
    "minutely": {
      //
    },
    "hourly": {
      //
    },
    "daily": {
      //
    },
    "primary": 0,
    "forecast_keypoint": "Over the next two hours, no rain is expected. Enjoy the outdoors without any weather concerns"
  }
}

Response Fields

JSONPath	Type	Description
$.result.realtime	object	Realtime data block; see Realtime Weather
$.result.minutely	object	Minutely data block; see Minutely Precipitation Forecast; returned only with Enterprise plan permission
$.result.hourly	object	Hourly data block; see Hourly Forecast
$.result.daily	object	Daily data block; see Daily Forecast
$.result.alert	object	Alert data block (returned with alert=true and alert permission); see Weather Alerts
$.result.primary	number	Always 0
$.result.forecast_keypoint	string	Key forecast text; see the note below

description & forecast_keypoint

For the combined endpoint they differ:

• result.hourly.description: weather-change description for the next 24 hours, identical to the hourly endpoint's description.
• result.forecast_keypoint: usually the minute-level precipitation text for the next 2 hours; however, when there is no radar coverage for the minute-level data, or when the minute-level forecast has no rain but rain is expected within the next 24 hours, the hourly 24-hour text is used instead.

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"
}