#AirVisual API

Number of APIs: 8

Interested in using AirVisual's most comprehensive global air quality data for your own application? You are at the right place! Let's get you started.

First of all, please refer to the air quality API page on our website , in order to get familiar with our plans and features.

At any moment, feel free to contact us if you have any questions, would like to trial a particular plan, or any other inquiries. We are always happy to hear from you!

Get started

The only thing you need to start using our service is an API key, to obtain one for free please go to this page .

Once you have it, you need to put it everywhere you see the {{YOUR_API_KEY}} string, either directly throught Qodex (recommended) using global variables, in your browser or any other system/language you may use.

HTTPS support

AirVisual API now supports HTTPS! In order to enable this feature, just prefix your request with https://... instead of http://...

Important notes

Stations around the world have update cycles that are all different from each other.
Stations are updated only once per hour.
The API returns calculated AQI for each pollutant and for the station (main pollutant).
The API returns 2 types of AQI: US AQI (EPA) and Chinese AQI.
Stations may occasionally have updated information. For example, their GPS coordinates may be adjusted or their name changed. Make sure your system or apps support the station info updates.
If a station doesn’t return pollution values, it means the data wasn’t published for that particular hour.
Pollutants do not always have the same concentration units. Sometimes CO is reported in µg/m3 and sometimes in ppm. However, PM2.5 and PM10 are always reported in µg/m3.

Return codes

Below are a few example of return codes you may get. This list is not exhaustive.

success : returned when JSON file was generated successfully.
call_limit_reached : returned when minute/monthly limit is reached.
api_key_expired : returned when API key is expired.
incorrect_api_key : returned when using wrong API key.
ip_location_failed : returned when service is unable to locate IP address of request.
no_nearest_station : returned when there is no nearest station within specified radius.
feature_not_available : returned when call requests a feature that is not available in chosen subscription plan.
too_many_requests : returned when more than 10 calls per second are made.

Detailed response example


{
  "status": "success",
  "data": {
    "name": "Eilat Harbor",
    "city": "Eilat",
    "state": "South District",
    "country": "Israel",
    "location": {
      "type": "Point",
      "coordinates": [
        34.939443,
        29.531814
      ]
    },
    "forecasts": [ //object containing forecast information
      {
        "ts": "2017-02-01T03:00:00.000Z",  //timestamp
        "aqius": 21, //AQI value based on US EPA standard
        "aqicn": 7, //AQI value based on China MEP standard
        "tp": 8, //temperature in Celsius
        "tp_min": 6, //minimum temperature in Celsius
        "pr": 976,  //atmospheric pressure in hPa
        "hu": 100, //humidity %
        "ws": 3, //wind speed (m/s)
        "wd": 313, //wind direction, as an angle of 360° (N=0, E=90, S=180, W=270)
        "ic": "10n" //weather icon code, see below for icon index
      }, 
    …  // contains more forecast data for upcoming 76 hours
    ]
    "current": {
      "weather": {
        "ts": "2017-02-01T01:00:00.000Z",
        "tp": 12,
        "pr": 1020,
        "hu": 62,
        "ws": 2,
        "wd": 320,
        "ic": "01n"
      },
      "pollution": {
        "ts": "2017-02-01T01:15:00.000Z",
        "aqius": 18,
        "mainus": "p1", //main pollutant for US AQI
        "aqicn": 20,
        "maincn": "p1",  //main pollutant for Chinese AQI
        "p1": {   //pollutant details, concentration and appropriate AQIs
          "conc": 20,
          "aqius": 18,
          "aqicn": 20
        }
      }
    },
    "history": { //object containing weather and pollution history information
      "weather": [
        {
          "ts": "2017-02-01T01:00:00.000Z",
          "tp": 12,
          "pr": 1020,
          "hu": 62,
          "ws": 2,
          "wd": 320,
          "ic": "01n"
        },
        … // contains more weather historical data for past 48 hours
      ]
      "pollution": [
        {
          "ts": "2017-02-01T01:15:00.000Z",
          "aqius": 18,
          "mainus": "p1",
          "aqicn": 20,
          "maincn": "p1",
          "p1": {
            "conc": 20,
            "aqius": 18,
            "aqicn": 20
          }
        },
      …  // contains more pollution historical data for past 48 hours
      ]
    },
    "units": { //object containing units information
      "p2": "ugm3", //pm2.5
      "p1": "ugm3", //pm10
      "o3": "ppb", //Ozone O3
      "n2": "ppb", //Nitrogen dioxide NO2 
      "s2": "ppb", //Sulfur dioxide SO2 
      "co": "ppm" //Carbon monoxide CO 
    }
  }
}

Weather icon index

Description	Name	Icon
clear sky (day)	01d.png
clear sky (night)	01n.png
few clouds (day)	02d.png
few clouds (night)	02n.png
scattered clouds	03d.png
broken clouds	04d.png
shower rain	09d.png
rain (day time)	10d.png
rain (night time)	10n.png
thunderstorm	11d.png
snow	13d.png
mist	50d.png