Minutely Precipitation Forecast

Returns minute-by-minute precipitation forecasts for the next two hours at a given location.

Update Frequency and Spatial Resolution

Minute-level precipitation data uses minute-by-minute sliding updates (publish cycle ~5 min), keeps 1-minute temporal resolution (starting from the current minute), has ~1 km spatial scale, and covers the next two hours by the minute. For details, see Variable Coverage.

Request

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

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

Request Example

curl "https://api.caiyunapp.com/v2.6/{token}/-74,40.7/minutely.json?lang=en_US&unit=imperial"

{
  "status": "ok", // response status
  "api_version": "v2.6", // API version
  "api_status": "active", // API service status
  "lang": "en_US", // response language
  "unit": "imperial", // unit system
  "tzshift": -14400, // timezone offset
  "timezone": "America/New_York", // timezone
  "server_time": 1712644911, // server time
  "location": [40.7, -74.0], // [latitude, longitude]
  "result": {
    "minutely": {
      "status": "ok", // minutely forecast status
      "datasource": "radar", // data source ("radar" within radar coverage)
      "precipitation_2h": [
        0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
        0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
        0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
        0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
        0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
        0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
        0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
        0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
        0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0
      ], // radar precipitation intensity for each minute of the next 2 hours (120 values)
      "precipitation": [
        0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
        0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
        0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
        0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
        0.0, 0.0, 0.0, 0.0
      ], // radar precipitation intensity for each minute of the next 1 hour (first 60 values)
      "accumulation": [0.0, 0.0], // hourly accumulated precipitation for the next 2 hours (2 values)
      "probability": [0.0, 0.0, 0.0, 0.0], // precipitation probability (0~1) for the next [0-30, 30-60, 60-90, 90-120] minutes
      "description": "The nearest area experiencing rain is to the north, 55 mi away" // natural-language precipitation description for the next 2 hours
    },
    "primary": 0,
    "forecast_keypoint": "The nearest area experiencing rain is to the north, 55 mi away" // forecast keypoint, identical to minutely.description
  }
}

Response Fields

JSONPath	Type	Description
$.result.minutely.datasource	string	Data source: radar within radar coverage
$.result.minutely.precipitation_2h	array<number>	Radar precipitation intensity for each minute of the next 2 hours (120 values); radar precipitation intensity (0~1) with unit=metric, mm/h with unit=metric:v2. See Precipitation Intensity
$.result.minutely.precipitation	array<number>	Radar precipitation intensity for each minute of the next 1 hour (the first 60 values of precipitation_2h), same units as above
$.result.minutely.accumulation	array<number>	Hourly accumulated precipitation for the next 2 hours: a length-2 array [hour1, hour2], computed from precipitation_2h as two 60-minute buckets with piecewise correction and a cap for extreme values; mm for metric / metric:v1 / metric:v2 / SI, inch for imperial. See Unit System
$.result.minutely.probability	array<number>	4 values: precipitation probability (0~1) for the next [0-30, 30-60, 60-90, 90-120] minutes respectively; conditionally present
$.result.minutely.description	string	Natural-language precipitation description for the next 2 hours; conditionally present

JSONPath	Type	Description
$.result.forecast_keypoint	string	Identical to minutely.description

description & forecast_keypoint

For the minutely endpoint, description and forecast_keypoint (at $.result.forecast_keypoint, result level) are identical: both describe precipitation/weather over the next ~2 hours, suitable for short-term precipitation or weather copy.

accumulation is not aligned with minutely / hourly precipitation

accumulation is not numerically consistent with precipitation / precipitation_2h or hourly precipitation, and should not be cross-checked for equality. For example, with metric / metric:v1, the per-minute series remains radar intensity while accumulation is computed after an internal conversion to mm/h; accumulation also applies piecewise correction and a cap; the hourly merge path uses a different conversion.

Notes

• If the token has no minutely permission, the entire minutely block is not returned.

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