IQAir APIiqair.com ↗
Access real-time AQI rankings, city-level pollutant breakdowns, forecasts, weather, pollen indices, and geographic map clusters via the IQAir API.
What is the IQAir API?
This API exposes 4 endpoints covering global and city-level air quality data from IQAir, including AQI rankings for up to 122 cities, pollutant concentrations, hourly and daily forecasts, and geographic map clusters. The get_city_air_quality endpoint returns the most granular data: per-pollutant AQI and concentration values, weather conditions, pollen indices, and health recommendations for a specific city identified by URL slugs.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/04ba50aa-6be3-40a9-8d23-947dfaf5a46d/get_world_air_quality' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace iqair-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: IQAir SDK — real-time air quality monitoring, bounded and re-runnable."""
from parse_apis.iqair_air_quality_api import IQAir, CityNotFound
client = IQAir()
# Get global air quality overview — top polluted and cleanest cities
overview = client.worldoverviews.get()
for city in overview.top10_polluted_cities[:3]:
print(f"Polluted: {city.city} ({city.country}) — AQI {city.aqi}, rank #{city.rank}")
# Live city rankings — all tracked cities sorted by AQI
top_city = client.rankedcities.list(limit=1).first()
if top_city:
print(f"Most polluted right now: {top_city.city}, {top_city.country} — AQI {top_city.aqi}")
# Drill into a specific city's full air quality detail using URL slugs
try:
detail = client.citydetails.get(country="usa", state="new-york", city="new-york-city")
print(f"City: {detail.details.name}, {detail.details.country}")
for pollutant in detail.pollutants:
print(f" {pollutant.pollutant_name}: {pollutant.concentration} {pollutant.unit} (AQI {pollutant.aqi})")
except CityNotFound as exc:
print(f"City not found: {exc.city}")
# Map clusters for geographic visualization
for cluster in client.mapclusters.list(zoom=2, limit=5):
print(f"Cluster {cluster.geohash}: {cluster.stations_count} stations, AQI {cluster.aqi}")
print("exercised: worldoverviews.get / rankedcities.list / citydetails.get / mapclusters.list")
Global air quality overview returning the top 15 most polluted and top 15 cleanest major cities worldwide. Each city entry includes current AQI, geographic identifiers, and a URL slug path usable with get_city_air_quality. Data updates hourly.
No input parameters required.
{
"type": "object",
"fields": {
"top10CleanestCities": "array of ranked city objects ordered by AQI ascending",
"top10PollutedCities": "array of ranked city objects ordered by AQI descending"
},
"sample": {
"data": {
"top10CleanestCities": [
{
"id": "uf7aCpduMf3Lg4de2",
"aqi": 11,
"url": "/thailand/chiang-mai/chiang-mai",
"city": "Chiang Mai",
"rank": 1,
"state": "Chiang Mai",
"country": "Thailand",
"flagURL": "https://cdn.airvisual.net/flags/thailand.jpg",
"updatedAt": "2026-06-11T07:00:00.000Z",
"followersCount": 15215513
}
],
"top10PollutedCities": [
{
"id": "sbxNsWrjrnPT36jH9",
"aqi": 166,
"url": "/uganda/central-region/kampala",
"city": "Kampala",
"rank": 1,
"state": "Central Region",
"country": "Uganda",
"flagURL": "https://cdn.airvisual.net/flags/uganda.jpg",
"updatedAt": "2026-06-11T07:00:00.000Z",
"followersCount": 12318
}
]
},
"status": "success"
}
}About the IQAir API
Global Rankings and City Listings
Two endpoints provide worldwide air quality overviews. get_world_air_quality returns the top 15 most polluted and top 15 cleanest major cities, each with current AQI and a URL slug usable as input to get_city_air_quality. get_live_city_ranking extends this to up to 122 cities, sorted by AQI descending, and adds fields like followersCount, flagURL, rank, and per-city updatedAt timestamps. Both endpoints update hourly.
City-Level Detail
get_city_air_quality accepts three required URL slug parameters — city, state, and country — which map directly to the url field returned by the ranking endpoints. The response includes a details object with coordinates, current AQI, hourly and daily forecast arrays, and weather conditions. A pollutants array lists each measured pollutant with pollutantName, aqi, concentration, unit, and description. The recommendations object provides health guidance covering outdoor exercise, window ventilation, mask use, and air purifier operation.
Map Visualization Data
get_map_data accepts an optional bbox parameter (comma-separated minLng,minLat,maxLng,maxLat) and a zoom level from 1 to 20. The response is a markers array where each entry is a geographic cluster containing a geohash, stationsCount, coordinates, and aggregated aqi. Higher zoom values produce more granular clusters suitable for building regional air quality heatmaps. Omitting bbox returns a global view.
The IQAir API is a managed, monitored endpoint for iqair.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when iqair.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official iqair.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Display a ranked table of the world's most polluted cities using AQI values from
get_live_city_ranking. - Build a city air quality dashboard showing pollutant concentrations (PM2.5, NO2, O3, etc.) via the
pollutantsarray inget_city_air_quality. - Render an interactive air quality map using geographic clusters and AQI values from
get_map_datawith bounding box and zoom inputs. - Surface health recommendations (exercise, masks, ventilation) to users based on current AQI from
get_city_air_quality. - Power hourly and daily AQI forecast charts using the forecast arrays in the
detailsobject ofget_city_air_quality. - Trigger air quality alerts when AQI exceeds a threshold by polling
get_live_city_rankingfor monitored cities. - Combine pollen index data from
get_city_air_qualitywith weather conditions for seasonal health applications.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does IQAir have an official developer API?+
What does `get_city_air_quality` return beyond a single AQI number?+
pollutants array with individual AQI, concentration, and unit for each measured pollutant; a details object with coordinates, current conditions, hourly and daily forecast arrays, and weather data; pollen indices; and a recommendations object with guidance on exercise, windows, masks, and air purifiers.How many cities are covered by `get_live_city_ranking`, and can I filter by region?+
Does the API expose historical air quality data?+
How fresh is the data, and what are the update intervals?+
get_world_air_quality and get_live_city_ranking) update hourly. get_city_air_quality exposes a per-city updatedAt timestamp in the response so you can verify data freshness for a specific location before acting on it.