Air Pollution API

Learn to get the current, forecast, and historical air pollution data for a specific location.

We'll cover the following

This API provides the current air pollution data for any specific location. Moreover, it provides air pollution forecasts and historical air pollution data for a location of our choice.

Note: Historical air pollution data is available from November 27, 2020 onward.

Air quality data

This API provides the air quality index and data comprising concentration levels for a number of pollutant gases. These include:

  • Carbon monoxide (CO)

  • Ammonia (NH3)

  • Nitrogen monoxide (NO)

  • Nitrogen dioxide (NO2)

  • Ozone (O3)

  • Coarse particulate matter (PM10)

  • Fine particulate matter (PM2.5)

  • Sulfur dioxide (SO2)

AQI Levels

Qualitative Name

Index

Pollutant Concentration in μg/m3



NO2

PM10

O3

PM25 (Optional)

Good

1

0-50

0-25

0-60

0-15

Fair

2

50-100

25-50

60-120

15-30

Moderate

3

100-200

50-90

120-180

30-55

Poor

4

200-400

90-180

180-240

30-55

Very Poor

5

>400

>180

>240

>110

Note: Wikipedia has a good section explaining The Common Air Quality Index (CAQI) and how it is calculated.

Current air pollution data

We'll make a GET request to the following URI to get the current air pollution data for a specific location:

http://api.openweathermap.org/data/2.5/air_pollution?lat={lat}&lon={lon}&appid={APP_ID}

Request Parameters

Parameter

Type

Category

Description

APP_ID

string

required

This is our unique API key.

lat

decimal

required

This is the location’s latitude.

lon

decimal

required

This is the location’s longitude.

Lines 16–17: We enter 47.6038321 and -122.3300624, the geographical coordinates for Seattle, United States, for the required parameters lat and lon, respectively.

Click the "Run" button in the widget below to see the output.

Press + to interact
// Importing libraries here
import fetch from "node-fetch";
// Define APP ID here
const APP_ID = '{{APP_ID}}';
// Define endpoint URL here
const url = new URL(`http://api.openweathermap.org/data/2.5/air_pollution`);
// Define header parameters here
const headerParameters = {
  contentType: 'application/json',
};
// Define query parameters here
const lat = 47.6038321;
const lon = -122.3300624;
const queryParameters = new URLSearchParams({
  lat: lat.toString(),
  lon: lon.toString(),
  appid: APP_ID
});
// Setting API call options
const options = {
  method: 'GET',
  headers: headerParameters,
};
// Function to make API call
async function getAirPollution() {
  try {
    url.search = queryParameters;
    const response = await fetch(url, options);
    // Custom function for printing the API response
    printResponse(response);
  } catch (error) {
    // Custom function for printing the error message
    printError(error);
  }
}
 
// Calling function to make API call
getAirPollution();

Line 8: We define the URL for the current air pollution data endpoint.

Lines 19–23: We define the query parameters for the current air pollution data endpoint.

Lines 32–43: We define a custom function getAirPollution() to make an API call using fetch and handle any exception if it occurs. The printResponse() and printError() are custom functions to print the API response and errors, respectively.

Line 46: We invoke the getAirPollution() function.

The output of the above code displays the current air pollution data for the specified location.

Let's dig into the response fields generated by this endpoint.

Response Fields

Parameter

Type

Description

coord.lat

decimal

This is the location’s latitude.

coord.lon

decimal

This is the location’s longitude.

list.components.co

decimal

This is the concentration of carbon monoxide. Its unit is μg/m3.

list.components.nh3

decimal

This is the concentration of ammonia. Its unit is μg/m3.

list.components.no

decimal

This is the concentration of nitrogen monoxide. Its unit is μg/m3.

list.components.no2

decimal

This is the concentration of nitrogen dioxide. Its unit is μg/m3.

list.components.o3

decimal

This is the concentration of ozone. Its unit is μg/m3.

list.components.pm10

decimal

This is the concentration of coarse particulate matter. Its unit is μg/m3.

list.components.pm2_5

decimal

This is the concentration of fine particles matter. Its unit is μg/m3.

list.components.so2

decimal

This is the concentration of sulfur dioxide. Its unit is μg/m3.

list.dt

datetime

This is the date and time. Its units are Unix and UTC.

list.main.aqi

integer

This is the air quality index. Its possible values are 1 for Good, 2 for Fair, 3 for Moderate, 4 for Poor, and 5 for Very Poor.

Air pollution forecasts

We'll make a GET request to the following URI to get the air pollution forecasts for a specific location:

http://api.openweathermap.org/data/2.5/air_pollution/forecast?lat={lat}&lon={lon}&appid={APP_ID}

Request Parameters

Parameter

Type

Category

Description

APP_ID

string

required

This is our unique API key.

lat

decimal

required

This is the location’s latitude.

lon

decimal

required

This is the location’s longitude.

Lines 16–17: We enter 47.6038321 and -122.3300624, the geographical coordinates for Seattle, United States, for the required parameters lat and lon, respectively.

Click the "Run" button in the widget below to see the output.

Press + to interact
// Importing libraries here
import fetch from "node-fetch";
// Define APP ID here
const APP_ID = '{{APP_ID}}';
// Define endpoint URL here
const url = new URL(`http://api.openweathermap.org/data/2.5/air_pollution/forecast`);
// Define header parameters here
const headerParameters = {
  contentType: 'application/json',
};
// Define query parameters here
const lat = 47.6038321;
const lon = -122.3300624;
const queryParameters = new URLSearchParams({
  lat: lat.toString(),
  lon: lon.toString(),
  appid: APP_ID
});
// Setting API call options
const options = {
  method: 'GET',
  headers: headerParameters,
};
// Function to make API call
async function getAirPollution() {
  try {
    url.search = queryParameters;
    const response = await fetch(url, options);
    // Custom function for printing the API response
    printResponse(response);
  } catch (error) {
    // Custom function for printing the error message
    printError(error);
  }
}
 
// Calling function to make API call
getAirPollution();

Let's take a quick look at the code given in the widget above:

Line 8: We define the URL for the air pollution forecasts endpoint.

Lines 19–23: We define the query parameters for the air pollution forecasts endpoint.

Lines 32–43: We define a custom function getAirPollution() to make an API call using fetch and handle any exception if it occurs. The printResponse() and printError() are custom functions to print the API response and errors, respectively.

Line 46: We invoke the getAirPollution() function.

The output of the above code displays the air pollution forecasts for the specified location for a period of 5 days with hourly granularity.

Let's take a look at the response fields generated by this endpoint.

Response Fields

Parameter

Type

Description

coord.lat

decimal

This is the location’s latitude.

coord.lon

decimal

This is the location’s longitude.

list.components.co

decimal

This is the concentration of carbon monoxide. Its unit is μg/m3.

list.components.nh3

decimal

This is the concentration of ammonia. Its unit is μg/m3.

list.components.no

decimal

This is the concentration of nitrogen monoxide. Its unit is μg/m3.

list.components.no2

decimal

This is the concentration of nitrogen dioxide. Its unit is μg/m3.

list.components.o3

decimal

This is the concentration of ozone. Its unit is μg/m3.

list.components.pm10

decimal

This is the concentration of coarse particulate matter. Its unit is μg/m3.

list.components.pm2_5

decimal

This is the concentration of fine particles matter. Its unit is μg/m3.

list.components.so2

decimal

This is the concentration of sulfur dioxide. Its unit is μg/m3.

list.dt

datetime

This is the date and time. Its units are Unix and UTC.

list.main.aqi

integer

This is the air quality index. Its possible values are 1 for Good, 2 for Fair, 3 for Moderate, 4 for Poor, and 5 for Very Poor.

Historical air pollution data

We'll make a GET request to the following URI to get the historical air pollution data for a specific location:

http://api.openweathermap.org/data/2.5/air_pollution/history?lat={lat}&lon={lon}&start={start}&end={end}&appid={APP_ID}

Request Parameters

Parameter

Type

Category

Description

APP_ID

string

required

This is our unique API key.

lat

decimal

required

This is the location’s latitude.

lon

decimal

required

This is the location’s longitude.

start

datetime

required

This is the start time. Its units are Unix and UTC.

end

datetime

required

This is the end time. Its units are Unix and UTC.

Lines 16–17: We enter 47.6038321 and -122.3300624, the geographical coordinates for Seattle, United States, for the required parameters lat and lon, respectively.

Lines 20–21: We retrieve the historical air pollution data for the last 5 days. Therefore, the values for the start and the end parameters are automatically set to 5 days ago and the current timestamp, respectively.

Click the "Run" button in the widget below to see the output.

Press + to interact
// Importing libraries here
import fetch from "node-fetch";
// Define APP ID here
const APP_ID = '{{APP_ID}}';
// Define endpoint URL here
const url = new URL(`http://api.openweathermap.org/data/2.5/air_pollution/history`);
// Define header parameters here
const headerParameters = {
  contentType: 'application/json',
};
// Define query parameters here
const lat = 47.6038321;
const lon = -122.3300624;
const currentTimeInMs = Date.now();
const secs1Day = 24 * 60 * 60;
const start = parseInt((currentTimeInMs/1000) - (5 * secs1Day));
const end = parseInt(currentTimeInMs/1000);
const queryParameters = new URLSearchParams({
  lat: lat.toString(),
  lon: lon.toString(),
  start: start.toString(),
  end: end.toString(),
  appid: APP_ID
});
// Setting API call options
const options = {
  method: 'GET',
  headers: headerParameters,
};
// Function to make API call
async function getAirPollution() {
  try {
    url.search = queryParameters;
    const response = await fetch(url, options);
    // Custom function for printing the API response
    printResponse(response);
  } catch (error) {
    // Custom function for printing the error message
    printError(error);
  }
}
 
// Calling function to make API call
getAirPollution();

Line 8: We define the URL for the historical air pollution data endpoint.

Lines 23–29: We define the query parameters for the historical air pollution data endpoint.

Lines 38–49: We define a custom function getAirPollution() to make an API call using fetch and handle any exception if it occurs. The printResponse() and printError() are custom functions to print the API response and errors, respectively.

Line 52: We invoke the getAirPollution() function.

The output of the above code displays the historical air pollution data for the specified location over the given duration with hourly granularity.

Let's dig into the response fields generated by this endpoint.

Response Fields

Parameter

Type

Description

coord.lat

decimal

This is the location’s latitude.

coord.lon

decimal

This is the location’s longitude.

list.components.co

decimal

This is the concentration of carbon monoxide. Its unit is μg/m3.

list.components.nh3

decimal

This is the concentration of ammonia. Its unit is μg/m3.

list.components.no

decimal

This is the concentration of nitrogen monoxide. Its unit is μg/m3.

list.components.no2

decimal

This is the concentration of nitrogen dioxide. Its unit is μg/m3.

list.components.o3

decimal

This is the concentration of ozone. Its unit is μg/m3.

list.components.pm10

decimal

This is the concentration of coarse particulate matter. Its unit is μg/m3.

list.components.pm2_5

decimal

This is the concentration of fine particles matter. Its unit is μg/m3.

list.components.so2

decimal

This is the concentration of sulfur dioxide. Its unit is μg/m3.

list.dt

datetime

This is the date and time. Its units are Unix and UTC.

list.main.aqi

integer

This is the air quality index. Its possible values are 1 for Good, 2 for Fair, 3 for Moderate, 4 for Poor, and 5 for Very Poor.