Realtime Weather

Returns realtime weather at the current moment for a given location, including temperature, humidity, cloud cover, weather phenomenon, wind, pressure, apparent temperature, precipitation, air quality, and life indices.

Update Frequency and Spatial Resolution

Real-time weather data uses minute-level continuous refresh (typically every 1-5 min) and has ~1 km spatial scale (local variation depends on station coverage). For details, see Variable Coverage.

Request

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

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/realtime.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": 1712644976,
  "location": [40.7, -74.0], // [latitude, longitude]
  "result": {
    "realtime": {
      "status": "ok",
      "temperature": 44.19, // surface 2m temperature
      "humidity": 0.61, // surface 2m relative humidity (0-1)
      "cloudrate": 0.42, // total cloud cover (0.0-1.0)
      "skycon": "PARTLY_CLOUDY_NIGHT", // weather phenomenon
      "visibility": 17.6, // surface horizontal visibility
      "dswrf": 0.0, // downward shortwave radiation flux
      "wind": {
        "speed": 4.46, // surface 10m wind speed
        "direction": 245.74 // surface 10m wind direction
      },
      "pressure": 101561.59, // ground-level atmospheric pressure
      "apparent_temperature": 39.56, // apparent temperature
      "precipitation": {
        "local": {
          "status": "ok",
          "datasource": "radar", // local precipitation data source ("radar" within radar coverage)
          "intensity": 0.0 // local precipitation intensity
        },
        "nearest": { // returned only within radar coverage
          "status": "ok",
          "distance": 55.3, // distance to the nearest precipitation
          "intensity": 0.125 // precipitation intensity at the nearest location
        }
      },
      "air_quality": {
        "pm25": 0, // PM25 concentration (μg/m3)
        "pm10": 0, // PM10 concentration (μg/m3)
        "o3": 0, // ozone concentration (μg/m3)
        "so2": 0, // sulfur dioxide concentration (μg/m3)
        "no2": 0, // nitrogen dioxide concentration (μg/m3)
        "co": 0, // carbon monoxide concentration (mg/m3)
        "aqi": {
          "chn": 0, // China standard AQI
          "usa": 0 // US standard AQI
        },
        "description": { "usa": "", "chn": "missing" }
      },
      "life_index": { // life indices
        "ultraviolet": { "index": 0.0, "desc": "None" },
        "comfort": { "index": 12, "desc": "Damp & Cold" }
      }
    },
    "primary": 0
  }
}

Response Fields

JSONPath	Type	Description
$.result.realtime.temperature	number	Surface 2m temperature
$.result.realtime.apparent_temperature	number	Apparent temperature
$.result.realtime.pressure	number	Ground-level atmospheric pressure
$.result.realtime.humidity	number	Surface 2m relative humidity (0-1)
$.result.realtime.wind.direction	number	Surface 10m wind direction
$.result.realtime.wind.speed	number	Surface 10m wind speed
$.result.realtime.precipitation.local.datasource	string	Local precipitation data source: radar within radar coverage
$.result.realtime.precipitation.local.intensity	number	Local precipitation intensity: radar precipitation intensity (0~1) with unit=metric, mm/h with unit=metric:v2; see Precipitation Intensity
$.result.realtime.precipitation.nearest.distance	number	Distance to the nearest precipitation; returned only within radar coverage
$.result.realtime.precipitation.nearest.intensity	number	Precipitation intensity at the nearest location; returned only within radar coverage, same unit semantics as precipitation.local.intensity
$.result.realtime.cloudrate	number	Total cloud cover (0.0-1.0)
$.result.realtime.dswrf	number	Downward shortwave radiation flux (W/M2)
$.result.realtime.visibility	number	Surface horizontal visibility
$.result.realtime.skycon	string	Weather phenomenon
$.result.realtime.life_index.comfort.desc	string	See Life Index
$.result.realtime.life_index.ultraviolet.desc	string	See Life Index
$.result.realtime.air_quality.pm25	number	PM25 concentration (μg/m3)
$.result.realtime.air_quality.pm10	number	PM10 concentration (μg/m3)
$.result.realtime.air_quality.o3	number	Ozone concentration (μg/m3)
$.result.realtime.air_quality.no2	number	Nitrogen dioxide concentration (μg/m3)
$.result.realtime.air_quality.so2	number	Sulfur dioxide concentration (μg/m3)
$.result.realtime.air_quality.co	number	Carbon monoxide concentration (mg/m3)
$.result.realtime.air_quality.aqi.chn	number	China standard AQI, see Air Quality Index
$.result.realtime.air_quality.aqi.usa	number	US standard AQI, see Air Quality Index

Notes

• precipitation.nearest is returned only within radar coverage; outside radar coverage the nearest block is not returned.
• Air quality concentration units: pm25/pm10/o3/so2/no2 in μg/m3, co in mg/m3; aqi includes both China standard (chn) and US standard (usa), see Air Quality Index.

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