CERNS.IO Public API

Free real-time air quality, weather, and forecast data for 33,000+ cities. JSON. No signup.

Base URL

https://cerns.io/api/v1/public

Rate Limits

Free tier: 60 requests/minute per IP
Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Exceeding returns 429 Too Many Requests with Retry-After header.

Need more? Contact hello@cerns.io.

Endpoints

City Overview

GET /api/v1/public/city/{slug}

Full city data: weather + AQI + forecast in one call.

Param	Type	Description
`slug`	path	City slug (e.g. `bangkok`, `new-york`)

curl https://cerns.io/api/v1/public/city/bangkok

City AQI

GET /api/v1/public/city/{slug}/aqi

Current air quality index with pollutant breakdown.

curl https://cerns.io/api/v1/public/city/london/aqi

City Forecast

GET /api/v1/public/city/{slug}/forecast

24-hour weather + 7-day daily forecast, plus AQI forecast.

curl https://cerns.io/api/v1/public/city/tokyo/forecast

City AQI History

GET /api/v1/public/city/{slug}/history

Historical hourly AQI with PM2.5, PM10, and station count.

Param	Type	Default	Description
`hours`	query	48	Hours of history (1–168)

curl "https://cerns.io/api/v1/public/city/delhi/history?hours=72"

World AQI Ranking

GET /api/v1/public/ranking

Global city ranking by AQI (most or least polluted).

Param	Type	Default	Description
`order`	query	desc	`desc` = most polluted, `asc` = cleanest
`limit`	query	50	Number of cities (1–200)

curl "https://cerns.io/api/v1/public/ranking?order=desc&limit=20"

Nearby Cities

GET /api/v1/public/nearby/{slug}

Cities near a given city (by geographic distance).

Param	Type	Default	Description
`limit`	query	10	Number of results (1–20)

curl "https://cerns.io/api/v1/public/nearby/bangkok?limit=5"

Search

GET /api/v1/public/search

Search cities and stations by name.

Param	Type	Required	Description
`q`	query	yes	Search query (min 2 chars)
`limit`	query	no	Max results (default 10, max 30)

curl "https://cerns.io/api/v1/public/search?q=paris"

Locate (Geolocation)

GET /api/v1/locate

Find nearest city by GPS coordinates or IP geolocation.

Param	Type	Description
`lat`	query	GPS latitude (optional — falls back to IP)
`lon`	query	GPS longitude (optional — falls back to IP)

curl "https://cerns.io/api/v1/locate?lat=48.8566&lon=2.3522"

Response Format

All responses are JSON with Content-Type: application/json.

Errors return:

{
  "error": "city_not_found",
  "slug": "nonexistent-city"
}

Embeddable Widget

Add a live AQI badge to any website with a single <iframe>. No API key required.

GET /widget/{country_code}/{slug}

Self-contained AQI card — city name, AQI value, color, PM2.5, and a dofollow backlink to the city page.

Param	Type	Default	Description
`country_code`	path	—	ISO 3166-1 alpha-2 country code (e.g. `th`, `gb`, `in`)
`slug`	path	—	City slug (e.g. `bangkok`, `london`)
`theme`	query	auto	`auto` follows OS, `light`, or `dark`

<iframe
  src="https://cerns.io/widget/th/bangkok"
  width="350" height="60" frameborder="0"
  style="border:none;border-radius:10px;overflow:hidden">
</iframe>

City pages also have a built-in Embed button that generates the snippet automatically.

Attribution

Data from CERNS.IO. AQI calculated using US EPA standard. Weather models: GFS, ICON. AQI models: CAMS, SILAM. Station data from AQICN.

Please credit cerns.io when using this data.