Air Quality Observations

Access Restriction

This API is a premium service available only to enterprise tier developers. Please contact Caiyun Sales to purchase.

Data

• Spatial resolution: observation stations in mainland China
• Update frequency: hourly
• See Coverage

Station Observations

Request

GET https://api.caiyunapp.com/v1/aqi/latest

Query Parameters

Name	Required	Default	Range	Description
token	Yes	—	—	API token; see Authentication

Request Example

curl "https://api.caiyunapp.com/v1/aqi/latest?token={token}"

Response Example

{
  "status": "ok",
  "category": "aqi_latest_obs_city",
  "result": {
    "0000A03460": {
      "lon": 117.4067,
      "lat": 40.0583,
      "area": "天津市",
      "position_name": "北环路",
      "province_name": "天津市",
      "station_code": "0000A03460",
      "time_point": "2021-12-29T14:00:00Z+08:00",
      "aqi": 21,
      "pm25": 3,
      "pm10": 15,
      "co": 0.5,
      "so2": 6,
      "o3": 66,
      "no2": 5,
      "quality": "优",
      "primary_pollutant": null
    }
    // ...
  }
}

Response Fields

JSONPath	Type	Description
$.status	string	Request status
$.category	string	Data category
$.result	object	Station data keyed by station ID
$.result.*.lon	number	Longitude
$.result.*.lat	number	Latitude
$.result.*.area	string	City
$.result.*.position_name	string	Station name
$.result.*.province_name	string	Province
$.result.*.station_code	string	Station code
$.result.*.time_point	string	Observation time
$.result.*.aqi	number	AQI
$.result.*.pm25	number	PM2.5, μg/m³
$.result.*.pm10	number	PM10, μg/m³
$.result.*.co	number	CO, mg/m³
$.result.*.so2	number	SO₂, μg/m³
$.result.*.o3	number	O₃, μg/m³
$.result.*.no2	number	NO₂, μg/m³
$.result.*.quality	string	Air quality category
$.result.*.primary_pollutant	string/null	Primary pollutant

City Rankings

Request

GET http://api.caiyunapp.com/v1/aqi/ranking

Query Parameters

Name	Required	Default	Range	Description
token	Yes	—	—	API token; see Authentication
number	No	100	1~200	Number of cities
field	No	pm25	pm25, pm10, o3, co, no2, so2, aqi	Ranking field
type	No	asc	asc, desc	Sort direction

Request Example

curl "http://api.caiyunapp.com/v1/aqi/ranking?number=10&type=desc&field=pm25&token={token}"

Response Example

{
  "status": "ok",
  "category": "aqi_latest_obs_city_ranking",
  "result": [
    {
      "lon": 129.5029,
      "lat": 48.471,
      "area": "伊春市",
      "position_name": "汤旺河国家公园(对照点)",
      "province_name": "黑龙江省",
      "station_code": "0000A02254",
      "time_point": "2021-12-29T14:00:00Z+08:00",
      "aqi": 4,
      "pm25": 0,
      "pm10": 2,
      "co": 0.4,
      "so2": 6,
      "o3": 70,
      "no2": 1,
      "quality": "优",
      "primary_pollutant": null
    }
  ]
}

Response Fields

JSONPath	Type	Description
$.status	string	Request status
$.category	string	Data category
$.result	array<object>	Ranked city entries
$.result[].lon	number	Longitude
$.result[].lat	number	Latitude
$.result[].area	string	City
$.result[].position_name	string	Station name
$.result[].province_name	string	Province
$.result[].station_code	string	Station code
$.result[].time_point	string	Observation time
$.result[].aqi	number	AQI
$.result[].pm25	number	PM2.5, μg/m³
$.result[].pm10	number	PM10, μg/m³
$.result[].co	number	CO, mg/m³
$.result[].so2	number	SO₂, μg/m³
$.result[].o3	number	O₃, μg/m³
$.result[].no2	number	NO₂, μg/m³
$.result[].quality	string	Air quality category
$.result[].primary_pollutant	string/null	Primary pollutant