Hourly Forecast

Returns hour-by-hour weather forecast data for a given location, including temperature, apparent temperature, wind, precipitation, cloud cover, weather phenomenon, and air quality.

Update Frequency and Spatial Resolution

Hourly forecast data uses near-term high-frequency refresh (~5-15 min), while other lead times are cycle-based (~hourly); spatial resolution is ~9-13 km (precipitation-related fields can be refined to ~1 km in the first 2 hours), and coverage is hourly for the next fifteen days. For details, see Variable Coverage.

Request

http

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

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`	Response language; falls back to `zh_CN` when unmatched. See Language
`unit`	No	`metric`	`metric`, `metric:v1`, `metric:v2`, `SI`, `imperial`	Unit system; any other value returns 422. See Unit System
`alert`	No	`false`	`true`, `false`	With `alert=true` and an alert-enabled token, the response includes a `result.alert` block. See Alert
`callback`	No	—	—	JSONP wrapper
`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

bash

curl "https://api.caiyunapp.com/v2.6/{token}/101.6656,39.2072/hourly?hourlysteps=1"

json

{
  "status": "ok", // response status
  "api_version": "v2.6", // API version
  "api_status": "active", // API service status
  "lang": "zh_CN", // response language
  "unit": "metric", // unit system
  "tzshift": 28800, // timezone offset
  "timezone": "Asia/Shanghai", // timezone
  "server_time": 1653552908, // server time
  "location": [39.2072, 101.6656], // [latitude, longitude]
  "result": {
    "hourly": {
      "status": "ok",
      "description": "Over the next 24 hours, cloudy", // natural-language description of weather changes over the next 24 hours (empty string if generation fails)
      "precipitation": [ // precipitation data
        {
          "datetime": "2022-05-26T16:00+08:00",
          "value": 0, // precipitation amount
          "probability": 0 // precipitation probability (0~100)
        }
      ],
      "temperature": [ // surface 2m temperature
        {
          "datetime": "2022-05-26T16:00+08:00",
          "value": 27
        }
      ],
      "apparent_temperature": [ // apparent temperature
        {
          "datetime": "2022-05-26T16:00+08:00",
          "value": 24.6
        }
      ],
      "wind": [ // surface 10m wind speed and direction
        {
          "datetime": "2022-05-26T16:00+08:00",
          "speed": 9, // wind speed
          "direction": 104 // wind direction
        }
      ],
      "humidity": [ // surface 2m relative humidity
        {
          "datetime": "2022-05-26T16:00+08:00",
          "value": 0.12
        }
      ],
      "cloudrate": [ // cloud cover
        {
          "datetime": "2022-05-26T16:00+08:00",
          "value": 0
        }
      ],
      "skycon": [ // weather phenomenon
        {
          "datetime": "2022-05-26T16:00+08:00",
          "value": "CLEAR_DAY"
        }
      ],
      "pressure": [ // ground-level atmospheric pressure
        {
          "datetime": "2022-05-26T16:00+08:00",
          "value": 84020.8379904
        }
      ],
      "visibility": [ // surface horizontal visibility
        {
          "datetime": "2022-05-26T16:00+08:00",
          "value": 25
        }
      ],
      "dswrf": [ // downward shortwave radiation flux
        {
          "datetime": "2022-05-26T16:00+08:00",
          "value": 736.87204608
        }
      ],
      "air_quality": { // air quality
        "aqi": [ // AQI
          {
            "datetime": "2022-05-26T16:00+08:00",
            "value": {
              "chn": 78, // China standard AQI
              "usa": 54 // US standard AQI
            }
          }
        ],
        "pm25": [ // PM2.5 concentration
          {
            "datetime": "2022-05-26T16:00+08:00",
            "value": 14
          }
        ]
      }
    },
    "primary": 0,
    "forecast_keypoint": "Over the next 24 hours, cloudy" // forecast keypoint (identical to hourly.description)
  }
}

Response Fields

JSONPath	Type	Description
`$.result.hourly.temperature[].value`	number	Surface 2m temperature
`$.result.hourly.apparent_temperature[].value`	number	Apparent temperature
`$.result.hourly.pressure[].value`	number	Ground-level atmospheric pressure
`$.result.hourly.humidity[].value`	number	Surface 2m relative humidity (0-1)
`$.result.hourly.wind[].direction`	number	Surface 10m wind direction (entries are `{datetime, speed, direction}`, no nested `value`)
`$.result.hourly.wind[].speed`	number	Surface 10m wind speed (same entry structure)
`$.result.hourly.precipitation[].value`	number	Precipitation
`$.result.hourly.precipitation[].probability`	number	Precipitation probability (0~100, unit `%`); continuous values only in the first 2 hours (rewritten from radar probabilities)
`$.result.hourly.cloudrate[].value`	number	Cloud cover (0.0-1.0)
`$.result.hourly.dswrf[].value`	number	Downward shortwave radiation flux (W/M2)
`$.result.hourly.visibility[].value`	number	Surface horizontal visibility
`$.result.hourly.skycon[].value`	string	Weather phenomenon
`$.result.hourly.air_quality.pm25[].value`	number	PM2.5 concentration (μg/m3)
`$.result.hourly.air_quality.aqi[].value.chn`	number	China standard AQI, see Air Quality Index
`$.result.hourly.air_quality.aqi[].value.usa`	number	US standard AQI, see Air Quality Index
`$.result.hourly.description`	string	Natural-language description of weather changes over the next 24 hours; an empty string if generation fails

JSONPath	Type	Description
`$.result.forecast_keypoint`	string	Natural-language description, identical to `hourly.description`

description & forecast_keypoint

For the hourly endpoint, description (under result.hourly) and forecast_keypoint (under result) are identical: both describe weather over the next 24 hours and can be used for display or summary.

Notes

Array entries start from the current whole hour, and their length equals the effective hourlysteps; datetime is an ISO string in the target location's timezone (e.g. 2022-05-26T16:00+08:00).
Values of hourlysteps that are not multiples of 24 may fail.

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

Hourly Forecast ​

Update Frequency and Spatial Resolution ​

Request ​

Path Parameters ​

Query Parameters ​

Request Example ​

Response Fields ​

Notes ​

Errors ​