{ "openapi": "3.0.3", "info": { "title": "IQAir AirVisual API", "description": "The IQAir AirVisual API provides real-time and forecast air quality and weather data worldwide. It offers endpoints for listing supported countries, states, and cities, retrieving air quality data for specific locations or nearest stations, and ranking cities by air quality index.", "version": "2.0.0", "contact": { "name": "IQAir", "url": "https://www.iqair.com" } }, "servers": [ { "url": "https://api.airvisual.com/v2", "description": "IQAir AirVisual API v2" } ], "paths": { "/countries": { "get": { "tags": ["Countries"], "summary": "List supported countries", "description": "Returns a list of all countries supported by the AirVisual API.", "operationId": "listCountries", "parameters": [ { "name": "key", "in": "query", "required": true, "description": "Your API key", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountriesResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/states": { "get": { "tags": ["States"], "summary": "List supported states", "description": "Returns a list of all supported states within a specified country.", "operationId": "listStates", "parameters": [ { "name": "key", "in": "query", "required": true, "description": "Your API key", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": true, "description": "Country name", "schema": { "type": "string" }, "example": "USA" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatesResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/cities": { "get": { "tags": ["Cities"], "summary": "List supported cities", "description": "Returns a list of all supported cities within a specified state and country.", "operationId": "listCities", "parameters": [ { "name": "key", "in": "query", "required": true, "description": "Your API key", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": true, "description": "State name", "schema": { "type": "string" }, "example": "California" }, { "name": "country", "in": "query", "required": true, "description": "Country name", "schema": { "type": "string" }, "example": "USA" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CitiesResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/city": { "get": { "tags": ["Cities"], "summary": "Get city air quality data", "description": "Returns air quality and weather data for a specified city, including current conditions, forecasts, and history.", "operationId": "getCity", "parameters": [ { "name": "key", "in": "query", "required": true, "description": "Your API key", "schema": { "type": "string" } }, { "name": "city", "in": "query", "required": true, "description": "City name", "schema": { "type": "string" }, "example": "Los Angeles" }, { "name": "state", "in": "query", "required": true, "description": "State name", "schema": { "type": "string" }, "example": "California" }, { "name": "country", "in": "query", "required": true, "description": "Country name", "schema": { "type": "string" }, "example": "USA" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CityDataResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/nearest_city": { "get": { "tags": ["Cities"], "summary": "Get nearest city air quality data", "description": "Returns air quality data for the nearest city based on IP geolocation or provided GPS coordinates.", "operationId": "getNearestCity", "parameters": [ { "name": "key", "in": "query", "required": true, "description": "Your API key", "schema": { "type": "string" } }, { "name": "lat", "in": "query", "required": false, "description": "Latitude coordinate. If not provided, IP-based geolocation is used.", "schema": { "type": "number", "format": "double" }, "example": 34.0522 }, { "name": "lon", "in": "query", "required": false, "description": "Longitude coordinate. If not provided, IP-based geolocation is used.", "schema": { "type": "number", "format": "double" }, "example": -118.2437 } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CityDataResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/stations": { "get": { "tags": ["Stations"], "summary": "List monitoring stations in a city", "description": "Returns a list of active air quality monitoring stations within a specified city.", "operationId": "listStations", "parameters": [ { "name": "key", "in": "query", "required": true, "description": "Your API key", "schema": { "type": "string" } }, { "name": "city", "in": "query", "required": true, "description": "City name", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": true, "description": "State name", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": true, "description": "Country name", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StationsListResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/station": { "get": { "tags": ["Stations"], "summary": "Get station air quality data", "description": "Returns air quality and weather data for a specific monitoring station.", "operationId": "getStation", "parameters": [ { "name": "key", "in": "query", "required": true, "description": "Your API key", "schema": { "type": "string" } }, { "name": "station", "in": "query", "required": true, "description": "Station name", "schema": { "type": "string" } }, { "name": "city", "in": "query", "required": true, "description": "City name", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": true, "description": "State name", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": true, "description": "Country name", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StationDataResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/nearest_station": { "get": { "tags": ["Stations"], "summary": "Get nearest station air quality data", "description": "Returns air quality data for the nearest monitoring station based on IP geolocation or provided GPS coordinates.", "operationId": "getNearestStation", "parameters": [ { "name": "key", "in": "query", "required": true, "description": "Your API key", "schema": { "type": "string" } }, { "name": "lat", "in": "query", "required": false, "description": "Latitude coordinate. If not provided, IP-based geolocation is used.", "schema": { "type": "number", "format": "double" } }, { "name": "lon", "in": "query", "required": false, "description": "Longitude coordinate. If not provided, IP-based geolocation is used.", "schema": { "type": "number", "format": "double" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StationDataResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/city_ranking": { "get": { "tags": ["Rankings"], "summary": "Get city air quality ranking", "description": "Returns a sorted array of major cities worldwide ranked from highest to lowest AQI.", "operationId": "getCityRanking", "parameters": [ { "name": "key", "in": "query", "required": true, "description": "Your API key", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CityRankingResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "query", "name": "key", "description": "API key passed as a query parameter." } }, "schemas": { "GeoLocation": { "type": "object", "properties": { "type": { "type": "string", "description": "GeoJSON type", "example": "Point" }, "coordinates": { "type": "array", "items": { "type": "number", "format": "double" }, "description": "Longitude and latitude coordinates", "example": [-118.2437, 34.0522] } } }, "PollutantUnit": { "type": "object", "properties": { "conc": { "type": "number", "description": "Pollutant concentration" }, "aqius": { "type": "integer", "description": "AQI value based on US EPA standard" }, "aqicn": { "type": "integer", "description": "AQI value based on China MEP standard" } } }, "Weather": { "type": "object", "properties": { "ts": { "type": "string", "format": "date-time", "description": "Timestamp" }, "tp": { "type": "number", "description": "Temperature in Celsius" }, "pr": { "type": "number", "description": "Atmospheric pressure in hPa" }, "hu": { "type": "number", "description": "Humidity percentage" }, "ws": { "type": "number", "description": "Wind speed in m/s" }, "wd": { "type": "number", "description": "Wind direction as angle (N=0, E=90, S=180, W=270)" }, "ic": { "type": "string", "description": "Weather icon code" } } }, "Pollution": { "type": "object", "properties": { "ts": { "type": "string", "format": "date-time", "description": "Timestamp" }, "aqius": { "type": "integer", "description": "AQI value based on US EPA standard" }, "mainus": { "type": "string", "description": "Main pollutant for US AQI (p2=PM2.5, p1=PM10, o3=Ozone, n2=NO2, s2=SO2, co=CO)" }, "aqicn": { "type": "integer", "description": "AQI value based on China MEP standard" }, "maincn": { "type": "string", "description": "Main pollutant for Chinese AQI" }, "p2": { "$ref": "#/components/schemas/PollutantUnit" }, "p1": { "$ref": "#/components/schemas/PollutantUnit" }, "o3": { "$ref": "#/components/schemas/PollutantUnit" }, "n2": { "$ref": "#/components/schemas/PollutantUnit" }, "s2": { "$ref": "#/components/schemas/PollutantUnit" }, "co": { "$ref": "#/components/schemas/PollutantUnit" } } }, "Current": { "type": "object", "properties": { "weather": { "$ref": "#/components/schemas/Weather" }, "pollution": { "$ref": "#/components/schemas/Pollution" } } }, "Forecast": { "type": "object", "properties": { "ts": { "type": "string", "format": "date-time", "description": "Timestamp" }, "aqius": { "type": "integer", "description": "AQI value based on US EPA standard" }, "aqicn": { "type": "integer", "description": "AQI value based on China MEP standard" }, "tp": { "type": "number", "description": "Temperature in Celsius" }, "tp_min": { "type": "number", "description": "Minimum temperature in Celsius" }, "pr": { "type": "number", "description": "Atmospheric pressure in hPa" }, "hu": { "type": "number", "description": "Humidity percentage" }, "ws": { "type": "number", "description": "Wind speed in m/s" }, "wd": { "type": "number", "description": "Wind direction as angle" }, "ic": { "type": "string", "description": "Weather icon code" } } }, "CityData": { "type": "object", "properties": { "city": { "type": "string", "description": "City name" }, "state": { "type": "string", "description": "State name" }, "country": { "type": "string", "description": "Country name" }, "location": { "$ref": "#/components/schemas/GeoLocation" }, "current": { "$ref": "#/components/schemas/Current" }, "forecasts": { "type": "array", "items": { "$ref": "#/components/schemas/Forecast" } }, "history": { "type": "object", "properties": { "weather": { "type": "array", "items": { "$ref": "#/components/schemas/Weather" } }, "pollution": { "type": "array", "items": { "$ref": "#/components/schemas/Pollution" } } } } } }, "StationData": { "type": "object", "properties": { "name": { "type": "string", "description": "Station name" }, "city": { "type": "string", "description": "City name" }, "state": { "type": "string", "description": "State name" }, "country": { "type": "string", "description": "Country name" }, "location": { "$ref": "#/components/schemas/GeoLocation" }, "current": { "$ref": "#/components/schemas/Current" }, "forecasts": { "type": "array", "items": { "$ref": "#/components/schemas/Forecast" } }, "history": { "type": "object", "properties": { "weather": { "type": "array", "items": { "$ref": "#/components/schemas/Weather" } }, "pollution": { "type": "array", "items": { "$ref": "#/components/schemas/Pollution" } } } } } }, "CountriesResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string", "description": "Country name" } } } } } }, "StatesResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "state": { "type": "string", "description": "State name" } } } } } }, "CitiesResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "city": { "type": "string", "description": "City name" } } } } } }, "CityDataResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/CityData" } } }, "StationsListResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "station": { "type": "string", "description": "Station name" }, "location": { "$ref": "#/components/schemas/GeoLocation" } } } } } }, "StationDataResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/StationData" } } }, "CityRankingResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "ranking": { "type": "object", "properties": { "current_aqi": { "type": "integer", "description": "Current AQI based on US EPA standard" }, "current_aqi_cn": { "type": "integer", "description": "Current AQI based on China MEP standard" } } } } } } } }, "ErrorResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "fail" }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } } }, "security": [ { "apiKey": [] } ], "tags": [ { "name": "Countries", "description": "List supported countries" }, { "name": "States", "description": "List supported states within a country" }, { "name": "Cities", "description": "List supported cities and retrieve city air quality data" }, { "name": "Stations", "description": "List monitoring stations and retrieve station data" }, { "name": "Rankings", "description": "City air quality rankings" } ] }