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

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

Path Parameters

Parameter	Description
token	API token
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	Values	Description
lang	No	zh_CN	zh_CN, zh_TW, en_US, en_GB, ja	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

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

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

JSONPath $.result.	Description
forecast_keypoint	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.

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