IQAir AirVisual API
✓ Official Vendor SpecData EnrichmentData TransformationapiKey9 EndpointsREST
For Agents
Fetch real-time air quality, AQI, and weather data for any city or monitoring station worldwide, including the nearest station to GPS coordinates. Useful for health, travel, and environmental dashboards.
Use for: Get the current AQI for San Francisco, Find the nearest air quality station to my coordinates, Look up air pollution near my IP address right now, List all supported cities in California for an environmental dashboard
Not supported: Does not handle pollen, UV index, weather forecasting, or air quality predictions — use for current and recent air quality readings only.
IQAir's AirVisual API delivers real-time and historical air quality data sourced from a global network of government-grade and community monitoring stations. Nine endpoints cover the full hierarchy: list supported countries, states, and cities; fetch current AQI for a city or station; locate the nearest city or station to coordinates or the caller's IP; and pull a global ranking of the most-polluted cities. Authentication is via a key passed as a query parameter, with JSON responses including AQI on US and Chinese scales plus weather context.
Install Jentic One Beta
Connect the IQAir AirVisual API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the IQAir AirVisual API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with IQAir AirVisual API.
Retrieve real-time AQI on US and Chinese scales for any supported city
Locate the nearest monitoring station or city to a set of coordinates or the caller's IP
Browse the global hierarchy of supported countries, states, and cities
Fetch fine-grained air quality data for a specific named monitoring station
List monitoring stations within a chosen city for sensor-level reporting
Pull the IQAir global city pollution ranking to highlight worst-air locations
Combine AQI with current temperature, humidity, pressure, and wind in one response
Use Cases
Patterns agents use IQAir AirVisual API for, with concrete tasks.
★ Health-Aware Outdoor Activity Apps
Fitness and travel apps use the AirVisual API to warn users before they head outdoors when AQI in their city or near their GPS coordinates crosses a health threshold. The /nearest_city endpoint resolves coordinates to the closest monitored city in one call, returning AQI, main pollutant, and weather, suitable for push notifications and in-app banners.
Call GET /nearest_city with the user's lat and lon and the key parameter, then push a warning if pollution.aqius is greater than 100.
Smart Home and HVAC Triggers
Smart air purifiers, HVAC controllers, and home dashboards poll a fixed monitoring station via /station to decide when to ramp up filtration or close ventilation. The endpoint returns the latest pollution and weather readings in JSON, easy to feed into automation rules in Home Assistant, OpenHAB, or a custom hub.
Poll GET /station with the configured station, city, state, and country every 15 minutes and turn on the air purifier if pollution.aqius exceeds the threshold.
Global Pollution Reporting Dashboards
Newsrooms, NGOs, and ESG dashboards use /city_ranking to publish a daily list of the world's most-polluted cities, alongside /countries, /states, and /cities to build interactive drill-down views. Caching the static hierarchy lookups keeps quota usage on the free or paid tier under control.
Fetch GET /city_ranking once per day and render the top 50 entries as a sorted table with country, city, and aqius.
Agent Air-Quality Lookup via Jentic
An AI assistant answering questions like 'is the air bad in Delhi today?' can call IQAir through Jentic without juggling the city/state/country triplet manually. Jentic resolves the intent to /city or /nearest_city, fills in the parameters, and returns the AQI and weather in one structured response.
Use Jentic to search for 'get current air quality for a city', load the GET /city operation, and execute it with city, state, and country from the user's question.
Key Endpoints
9 endpoints — iqair's airvisual api delivers real-time and historical air quality data sourced from a global network of government-grade and community monitoring stations.
METHOD
PATH
DESCRIPTION
GET
/city
Get current AQI and weather for a specific city
GET
/nearest_city
Find the nearest supported city to coordinates or the caller's IP
GET
/station
Get AQI for a specific monitoring station
GET
/nearest_station
Find the nearest monitoring station to coordinates or IP
GET
/city_ranking
Retrieve the global ranking of most-polluted cities
GET
/countries
List all supported countries
GET
/states
List supported states within a country
GET
/cities
List supported cities within a state
GET
/city
Get current AQI and weather for a specific city
GET
/nearest_city
Find the nearest supported city to coordinates or the caller's IP
GET
/station
Get AQI for a specific monitoring station
GET
/nearest_station
Find the nearest monitoring station to coordinates or IP
GET
/city_ranking
Retrieve the global ranking of most-polluted cities
GET
/countries
List all supported countries
GET
/states
List supported states within a country
GET
/cities
List supported cities within a state
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
The IQAir key is stored encrypted in the Jentic vault and appended to the query string at execution, so the agent's context and logs never contain the raw key.
Intent-based discovery
Agents search by intent (e.g. 'find air quality near GPS coordinates') and Jentic returns the matching IQAir operation with its parameter schema, eliminating the need to read AirVisual docs.
Time to first call
Direct IQAir integration: half a day for HTTP client, key handling, and parameter chaining across countries, states, and cities. Through Jentic: under 30 minutes — search, load, execute.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using IQAir AirVisual API through Jentic.
What authentication does the IQAir AirVisual API use?
AirVisual uses an API key passed as the key query parameter on every request. Through Jentic, the key is stored in the encrypted vault and injected at execution time, so the agent never sees the raw secret.
Can I get AQI for a location by GPS coordinates?
Yes. GET /nearest_city accepts lat and lon parameters and returns the closest supported city's current AQI, main pollutant, and weather. GET /nearest_station does the same at station granularity.
What pollution scales does the IQAir API return?
Each city or station response includes pollution.aqius (US AQI) and pollution.aqicn (Chinese AQI), the main pollutant code, and the timestamp of the latest reading.
What are the rate limits for the IQAir AirVisual API?
Limits depend on plan: the free Community plan allows 10,000 calls per month at roughly five per minute, while paid plans scale into the millions and lift the per-minute cap. The spec does not enforce these in code; they are tracked at the IQAir account level.
How do I find the nearest monitoring station through Jentic?
Search Jentic for 'find nearest air quality station', load the GET /nearest_station operation, and execute it with lat and lon. Jentic injects the API key and returns the station's pollution and weather payload.
Does IQAir return weather data alongside AQI?
Yes. /city, /station, /nearest_city, and /nearest_station all include a weather block with temperature, humidity, pressure, and wind for the same location and timestamp.
GET STARTED