canonical: https://jentic.com/apis/aqicn.org/aqicn

# AQICN Air Quality Index API

Jentic publishes the only available OpenAPI specification for AQICN Air Quality Index API, keeping it validated and agent-ready. AQICN provides real-time air quality index data for over 1,000 cities worldwide, including individual pollutant readings such as PM2.5, PM10, NO2, CO, SO2, and Ozone. The API supports city lookups by name, IP-based geolocation, latitude/longitude coordinates, station search, and bounding-box map queries. Authentication is via an API token passed as a query parameter.

## For AI agents

Read real-time air quality index and pollutant data for any city, coordinate, or map region worldwide.

## Scope

Does not handle weather forecasting, pollen data, or historical archives - use for real-time air quality index lookups only.

## Capabilities

- Look up the real-time AQI and pollutant breakdown for a named city
- Resolve the AQI for the user's current location using IP geolocation
- Fetch AQI for arbitrary latitude and longitude coordinates
- Search the AQICN station directory by name or keyword
- List monitoring stations and their AQI within a map bounding box

## Use cases

### City-Level Air Quality Lookup

Fetch the current AQI for a named city and surface the dominant pollutant alongside the index value. Travel and outdoor-activity products use this to give users a one-glance read on whether to go outside, change plans, or take protective measures. The /feed/{city} endpoint returns a single JSON object with the city's AQI, dominant pollutant, and individual readings.

Example prompt: Call GET /feed/{city} for the requested city name and return the AQI value plus the dominant pollutant in plain English.

### Coordinate-Based AQI for Mobile Apps

When a mobile app has the user's GPS coordinates, query AQICN by lat/lng to get the AQI from the closest monitoring station. Outdoor fitness and weather apps use this to show hyperlocal air quality without asking the user for their city. The /feed/geo:{lat};{lng} endpoint returns the nearest station's reading and identifies which station was used.

Example prompt: Call GET /feed/geo:{lat};{lng} with the user's coordinates and return the AQI, dominant pollutant, and the name of the nearest station.

### Map Overlay of Stations

Render a map of monitoring stations and their AQI values inside a visible bounding box. Air quality dashboards and environmental research tools use this to show regional patterns without making one call per station. The /map/bounds endpoint returns all stations within a lat/lng box in a single response.

Example prompt: Call GET /map/bounds with the user's current map viewport coordinates and return the list of stations with their AQI values for rendering.

### AI Agent Air Quality Briefings via Jentic

An assistant agent that drafts a daily morning briefing can call AQICN through Jentic to include today's air quality alongside weather and calendar context. The agent searches for the AQI lookup operation, loads the schema, and executes the city feed call without managing the API token. Jentic resolves the token from its credential vault.

Example prompt: Use Jentic search 'check the air quality in a city', load the schema for GET /feed/{city}, then execute with the user's home city and return the AQI for the briefing.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /feed/{city} | Get AQI for a city |
| GET | /feed/here | Get AQI for the IP geolocation |
| GET | /feed/geo:{lat};{lng} | Get AQI by coordinates |
| GET | /search | Search stations by name |
| GET | /map/bounds | List stations in a bounding box |

## Key resources

- **City Feed** — Look up real-time AQI and pollutant data by city name
- **Geo Feed** — Look up AQI by IP location or latitude/longitude coordinates
- **Search** — Search the AQICN station directory by name
- **Map** — List stations and AQI within a map bounding box

## Why Jentic

- **Setup:** Wiring AQICN by hand means learning its token-as-query-parameter scheme against the api.waqi.info host and building its geo and city feed paths yourself. Through Jentic you install once, import the AQICN Air Quality Index API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** AQICN puts the city or coordinates in the URL path (/feed/{city}, /feed/geo:{lat};{lng}) and every operation here is read-only, so you limit the agent to the lookup operations it needs, such as reading a city feed or searching stations. You choose the operations it may call, so the agent only runs the read operations you have added.
- **Credential handling:** Your AQICN token is stored once, encrypted, by your own Jentic One instance and appended as the token query parameter at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'check the air quality in a city', and Jentic returns the matching AQICN operation with its input schema so the agent calls the right endpoint without browsing docs.

## Related APIs

- **OpenWeatherMap API** — Pair OpenWeatherMap forecasts with AQICN air quality for combined outdoor-activity briefings.
- **WeatherAPI** — WeatherAPI exposes weather and basic air quality; combine with AQICN when station-level pollutant detail is needed.
- **BreezoMeter API** — Hyperlocal air quality and pollen API with sub-kilometre resolution, contrasted with AQICN's station-derived values.

## FAQ

### Why is there no official OpenAPI spec for AQICN Air Quality Index API?

AQICN does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call AQICN Air Quality Index API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the AQICN API use?

AQICN uses an API token passed as a query parameter named token on every request. Tokens are issued free for non-commercial use at aqicn.org/data-platform/token. Through Jentic, the token is stored encrypted in the vault and never enters the agent's context.

### Can I get historical air quality data with this API?

No. The endpoints in this spec return real-time and forecast values only. Historical archive access is offered separately by AQICN under their data platform - contact AQICN for bulk historical data.

### What pollutants are included in the AQI response?

City and geo feeds return individual readings for PM2.5, PM10, NO2, CO, SO2, and Ozone where the station reports them, plus the dominant pollutant identifier and weather context such as temperature and humidity.

### What are the rate limits for the AQICN API?

AQICN enforces a rate limit of around 1,000 requests per second per token in practice; the OpenAPI spec does not declare a fixed value. For heavy production use, contact AQICN to request a higher quota.

### How do I check the AQI in a city through Jentic?

Install Jentic with pip install jentic, search for 'check the air quality in a city', load the schema for GET /feed/{city}, then execute with the city name. Jentic injects the token automatically.

### Can I limit what my agent is allowed to do with the AQICN API?

Yes. Because you run Jentic One yourself, you decide which AQICN operations your agent may call, so you can add only the read lookups it needs, such as reading a city feed with GET /feed/{city} or searching stations with GET /search, and leave the rest out. Every AQICN operation here is read-only and takes the city or coordinates in the URL path, so an agent scoped to a single lookup cannot reach beyond retrieving air quality data. Your AQICN token is held by your own instance and added at execution time, so the agent never handles the credential directly.