# Iqair Airvisual

IQAir AirVisual provides global air quality data through its API, offering real-time and historical information on air pollution levels.

- **Category:** developer tools
- **Auth:** API_KEY
- **Composio Managed App Available?** N/A
- **Tools:** 10
- **Triggers:** 0
- **Slug:** `IQAIR_AIRVISUAL`
- **Version:** 20260223_00

## Tools

### Get Air Quality Forecast Data

**Slug:** `IQAIR_AIRVISUAL_GET_AIR_QUALITY_FORECAST_DATA`

Tool to retrieve air quality forecast data for a specified city, state, and country. Use after confirming location details.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `city` | string | Yes | City name (e.g., 'Los Angeles'). |
| `state` | string | Yes | State or region name (e.g., 'California'). |
| `country` | string | Yes | Country name (e.g., 'USA'). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Cities

**Slug:** `IQAIR_AIRVISUAL_GET_CITIES`

Tool to list supported cities in a specified state and country. Use when you need to retrieve cities for a given state/country.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `state` | string | Yes | State name as returned by the 'Get States' action. Use exact state names like 'California', 'Texas', 'New York'. |
| `country` | string | Yes | Country name as returned by the 'Get Countries' action. Use exact country names like 'USA', 'India', 'Germany', 'Canada'. Note: 'USA' is used instead of 'United States'. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get City Air Quality

**Slug:** `IQAIR_AIRVISUAL_GET_CITY_AIR_QUALITY`

Tool to retrieve air quality data for a specific city. Use when you need current pollution and weather data by specifying city, state, and country.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `city` | string | Yes | Name of the city to retrieve air quality for. Must match IQAir's supported city names exactly (e.g., 'Los Angeles', 'New York City', 'Paris'). |
| `state` | string | Yes | Name of the state, province, or region containing the city. Use full name, not abbreviations (e.g., 'California' not 'CA', 'Ile-de-France' for Paris). |
| `country` | string | Yes | Name of the country containing the city. Use full country name (e.g., 'USA', 'France', 'Australia'). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get supported countries

**Slug:** `IQAIR_AIRVISUAL_GET_COUNTRIES`

Tool to list all supported countries. Use when you need to know which countries are supported by the AirVisual API.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Historical AQI Data

**Slug:** `IQAIR_AIRVISUAL_GET_HISTORICAL_AQI_DATA`

Tool to retrieve historical air quality data for a city. Use after confirming city, state, and country when you need AQI readings over time.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `end` | string | No | End datetime in ISO8601 format (inclusive). |
| `city` | string | Yes | City name |
| `start` | string | No | Start datetime in ISO8601 format (inclusive). |
| `state` | string | Yes | State or province name |
| `country` | string | Yes | Country name |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Nearest City Air Quality

**Slug:** `IQAIR_AIRVISUAL_GET_NEAREST_CITY_AIR_QUALITY`

Tool to retrieve air quality data for the nearest city based on latitude/longitude or IP. Use when you have precise location data or want to geolocate an IP for air quality.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ip` | string | No | IPv4 address to geolocate; if neither lat/lon nor ip provided, server uses caller's IP. |
| `lat` | number | No | Latitude in decimal degrees; must be between -90 and 90. Must be provided with lon. |
| `lon` | number | No | Longitude in decimal degrees; must be between -180 and 180. Must be provided with lat. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Nearest Station Air Quality

**Slug:** `IQAIR_AIRVISUAL_GET_NEAREST_STATION_AIR_QUALITY`

Tool to get nearest station air quality. Use when you have GPS coordinates and need closest station’s AQI.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `lat` | number | Yes | Latitude in decimal degrees, must be between -90 and 90 |
| `lon` | number | Yes | Longitude in decimal degrees, must be between -180 and 180 |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get States

**Slug:** `IQAIR_AIRVISUAL_GET_STATES`

Tool to list supported states in a specified country. Use when you need to retrieve states/provinces for a given country.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `country` | string | Yes | Country name as returned by the 'Get Countries' action. Use exact country names like 'USA', 'India', 'Germany', 'Canada'. Note: 'USA' is used instead of 'United States'. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Station by ID

**Slug:** `IQAIR_AIRVISUAL_GET_STATION_BY_ID`

Fetches current air quality and weather data for a specific location by station/city/state/country names. Falls back to city-level data if the Stations API requires premium access. Returns current AQI (US and China scales), weather conditions, and geographic location. Use Get Countries, Get States, and Get Cities actions to find valid location names.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `city` | string | Yes | City's English name. Must match IQAir's supported city names exactly (use Get Cities action to find valid names). |
| `state` | string | Yes | State or region's English name. Must match IQAir's supported state names exactly (use Get States action to find valid names). |
| `country` | string | Yes | Country's English name. Must match IQAir's supported country names exactly (use Get Countries action to find valid names). |
| `station` | string | Yes | Station's English name. Note: Station name is used as an identifier but is passed through to fallback city data. The actual station-specific endpoint requires premium API access. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get World AQI Rankings

**Slug:** `IQAIR_AIRVISUAL_GET_WORLD_RANKING`

Retrieves air quality ranking data. With premium API access, returns a global ranking of cities by AQI. With standard (free) API access, automatically falls back to returning the nearest city's air quality as a single-item ranking list. Use lat/lon coordinates or an IP address to specify location for the fallback behavior. Returns city name, location, and current AQI values (US EPA and Chinese MEP standards).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ip` | string | No | IPv4 address for geolocation (e.g., '8.8.8.8'). Used to determine location when lat/lon are not provided. Optional - if omitted, uses caller's IP. |
| `lat` | number | No | Latitude in decimal degrees (-90 to 90). When provided with 'lon', returns air quality for the nearest city to these coordinates. Optional - if omitted, uses server's IP geolocation. |
| `lon` | number | No | Longitude in decimal degrees (-180 to 180). Must be provided together with 'lat'. Optional - if omitted, uses server's IP geolocation. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |