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

Request Example

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