canonical: https://jentic.com/apis/iqair.com/iqair # IQAir AirVisual API 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. ## For AI 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. ## Scope Does not handle pollen, UV index, weather forecasting, or air quality predictions - use for current and recent air quality readings only. ## Capabilities - 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 ### 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. Example prompt: 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. Example prompt: 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. Example prompt: 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. Example prompt: 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 | 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 | ## Key resources - **Geographic Hierarchy** — List supported countries, states, and cities for navigation and validation - **City Air Quality** — Retrieve current AQI and weather for a named city or the nearest one to coordinates or IP - **Station Air Quality** — List or query individual monitoring stations within a city - **City Ranking** — Fetch the IQAir global ranking of most-polluted cities ## Why Jentic - **Setup:** Wiring IQAir by hand means registering for a key, appending it to the query string on api.airvisual.com/v2, and walking the country, state, and city lists to resolve a station before reading air quality. Through Jentic you install once, import IQAir AirVisual from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** IQAir is a set of read-only lookups where the city, station, or coordinate travels as a query parameter, so scope the agent to the operations it needs, such as reading air quality near a set of coordinates. It stays a lookup client and cannot reach anything beyond the operations you allow. - **Credential handling:** Your IQAir key is stored once, encrypted, by your own Jentic One instance and injected into the query string at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'find air quality near GPS coordinates', and Jentic returns the matching IQAir operation with its input schema, so the agent calls the right endpoint without reading the AirVisual docs. ## Related APIs - **World Air Quality Index API** — Free worldwide AQI data aggregated from public monitoring networks. - **AirNow API** — Official U.S. EPA AirNow data for U.S. and partner countries. - **BreezoMeter API** — Air-quality, pollen, and wildfire data with minute-level resolution. - **Google API** — Maps Geocoding to convert addresses into coordinates for AirVisual lookups. ## FAQ ### 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. ### Can I limit what my agent is allowed to do with the IQAir AirVisual API? Yes. The IQAir AirVisual API is a set of read-only lookups where the city, station, or coordinates travel as query parameters, and because your Jentic One instance is self-hosted, your own rules decide which of these operations the agent may call. You can scope it to just the endpoints it needs, such as GET /nearest_city for reading air quality near a set of coordinates, while withholding others like /city_ranking or the /countries, /states, and /cities hierarchy lookups. It stays a lookup client and cannot reach anything beyond the operations and credentials you allow.