IQAir AirVisual API
49
AI ReadinessFoundational (D+)49/100
Official vendor OpenAPI document · agent-readyData 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://jentic.com/install.sh?src=apis&api=%2Fapis%2Fiqair.com%2Fiqair" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fiqair.com%2Fiqair" | 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
Jentic AI Readiness Score
This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.
I
IQAir AirVisual API
- Foundational (D+)49/100
100
Foundational Compliance65
Developer Experience & Jentic Compatibility52
AI-Readiness & Agent Experience94
Agent Usability15
Security76
AI DiscoverabilityPowered by JenticScoring Framework 1.0.0 | Scoring Engine 0.4.0
Show dimension breakdown
100
Foundational Compliance
Base layer of spec validity and structural soundness.
Grade: A+Signals: 4
98%
Lint Results
Aggregated quality score from linter diagnostics, weighted by severity.
100%
Resolution Completeness
Percentage of `$ref` references that resolve successfully.
100%
Specification Validity
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
100%
Structural Integrity
Structural correctness score based on schema issues using logarithmic dampening.
65
Developer Experience & Jentic Compatibility
Clarity, completeness, and ingestion readiness for developers and tooling.
Grade: BSignals: 4
10%
Example Density
How richly the API is illustrated with examples.
100%
Example Validity
Percentage of examples that conform to their schemas.
50%
Response Coverage
Percentage of operations with complete response definitions (success, client error, server error).
100%
Tooling Readiness
Health of API ingestion, bundling, and resolution within Jentic pipelines.
52
AI-Readiness & Agent Experience
Semantic breadth, depth, and agent comprehension for AI systems.
Grade: C-Signals: 4
59%
Description Coverage
Coverage of descriptions across API elements.
0%
Error Standardization
Coverage of RFC 9457 Problem Details for error responses.
100%
OperationId Quality
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
50%
Summary Coverage
Coverage of summaries across operations/tags/info.
94
Agent Usability
Functional utility, complexity comfort, and AI orchestration readiness.
Grade: A+Signals: 1
94%
Complexity Comfort
Agent comfort level based on API operational and structural complexity.
15
Security
Trust, risk posture, and security compliance.
Grade: FSignals: 1
15%
Authentication Strength
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
76
AI Discoverability
Findability, semantic richness, and reasoning readiness.
Grade: A-Signals: 1
76%
Descriptive Richness
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
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.
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.
GET STARTED