IQAir AirVisual API

Name: IQAir AirVisual API
Brand: IQAir AirVisual API
Availability: InStock

✓ 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.

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.

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 | sh

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 instance

Jentic 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

GET STARTED

Start building with IQAir AirVisual API

Explore with Jentic

View OpenAPI Document

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

Why Jentic?

Three things that make agents converge on Jentic-routed access.

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.

Time to first call

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.