Air Quality Forecasts

URL Path

https://data.api.xweather.com/airquality/forecasts/

Data Coverage

Global

Update Interval

1 hour

Time Range

+5 days

Access Multiplier

The air quality API forecasts endpoint provides information for locations globally. This endpoint can provide up to 4 days of daily and hourly forecast data. Forecast data will be interpolated for the exact location queried. Available information includes the air quality index (AQI), category, dominant pollutant, Health Index (AQHI), and information for primary pollutants.

Requests

Every request to the endpoint must include one of the supported actions in the url.

https://data.api.xweather.com/airquality/forecasts/{action}?client_id={client_id}&client_secret={client_secret}&{params}

Supported Actions

The following actions are supported with the /airquality/forecasts endpoint:

Action	Description
:id	Type: stringTypically used for passing a geographical location name or identifier such as city name, lat/long, or even US and Canadian postal codes. Learn more.
route	Type: stringAllows you to pass several coordinates along a custom route to return data points at each location. Learn more.

Response

The following is an example of what each object in the response will consist of. Depending on your requested action, the response may contain multiple instances of this object within an array.

Properties

id (string)

The ID of the air quality station. Null if not available.

loc.long (number)

The place or nearest place to the record.

loc.lat (number)

The latitude coordinate of the record.

place.name (string)

The place or nearest place to the record.

place.state (string)

The state abbreviation in which the response is located. This may be null or an empty string depending on the country.

place.country (string)

The 2 letter ISO-3166 country abbreviation in which the response is located.

interval (string)

The forecast interval.

periods.#.dateTimeISO (string)

ISO 8601 date of the period.

periods.#.timestamp (number)

UNIX timestamp of the period.

periods.#.aqi (number)

The standardized Air Quality Index value from 0 - 500.
See AirNow

periods.#.category (string)

The Air Quality category based on the AQI:
See AirNow

- good
- moderate
- usg (Unhealthy for Sensitive Groups)
- unhealthy
- very Unhealthy
- hazardous

If using filter=china, the following categories are utilized:
More info on China AQI / Categories.

- excellent
- good
- slightly polluted
- lightly polluted
- moderately polluted
- severely polluted

If using the filter=india, the following categories are utilizes:
More info on India AQI / Categories.

- good
- satisfactory
- moderately polluted
- poor
- very poor
- severe

periods.#.color (string)

The 6 character hexadecimal color code for the specific category.
See AirNow

periods.#.method (string)

The method used for the AQI calculation:
- airnow = Used the EPA AirNow AQI specification (default)
- china = Used the China AQI specification (filter=china)
- india = Used the India AQI specification (filter=india)

periods.#.dominant (string)

The dominant pollutant. Normally set to one of the following:
- co (Carbon Monoxide)
- no2 (Nitrogen Dioxide)
- o3 (Ozone)
- pm10 (Particle Matter <10µm)
- pm2.5 (Particle Matter <2.5µm)
- so2 (Sulfur Dioxide)

periods.#.health.index (number)

The air quality health index. A simplified global health index using a scale of 0 to 20 to describe the effect of air quality on health

- low: 0 - 3
- moderate: 4-6
- high: 7-10
- very high: > 10

periods.#.health.category (string)

The air quality health index category name:

- low: 0 - 3
- moderate: 4-6
- high: 7-10
- very high: > 10

periods.#.health.color (string)

The air quality health index category color:
The air quality health index. A simplified global health index using a scale of 0 to 20 to describe the effect of air quality on health

- low: #0000FF
- moderate: #00FF00
- high: #FFFF00
- very high: #FF0000

periods.#.pollutants.#.type (string)

The type abbreviation of the pollutant:
co = carbon monoxide
no2 = nitrogen dioxide
o3 = ozone
pm1 = partical matter (<1µm)
pm10 = partical matter (<10µm)
pm2.5 = partical matter (<2.5µm)
so2 = sulfer dioxide

Note that not all air quality stations provide information on all pollutants.

periods.#.pollutants.#.name (string)

Name of the pollutant

periods.#.pollutants.#.valuePPB (number)

The pollutant measurement in parts per billion. Null if this unit is not utilized

pm2.5 & pm10 do not utilize PPB.

periods.#.pollutants.#.valueUGM3 (number)

The pollutant measurement in parts per micrograms per cubic meter. Null if this unit is not utilized

periods.#.pollutants.#.aqi (number)

The pollutant measurement converted to the common AQI value, from 0 to 500 if using AirNow AQI.

periods.#.pollutants.#.category (string)

periods.#.pollutants.#.color (string)

The 6 character hexadecimal color code for the specific category.
See AirNow

periods.#.pollutants.#.method (string)

profile.tz (string)

Timezone name of the location.

profile.sources.#.name (string)

The name of the source

profile.stations.# (array)

Array of the observation station IDs used in the interpolated data

[
  {
    "id": null,
    "loc": {
      "long": -122.459,
      "lat": 47.389
    },
    "place": {
      "name": "burton",
      "state": "wa",
      "country": "us"
    },
    "interval": "day",
    "periods": [
      {
        "dateTimeISO": "2023-12-13T00:00:00-08:00",
        "timestamp": 1702454400,
        "aqi": 127,
        "category": "usg",
        "color": "FF7E00",
        "method": "airnow",
        "dominant": "pm2.5",
        "health": {
          "index": 2,
          "category": "low",
          "color": "0000FF"
        },
        "pollutants": [
          {
            "type": "o3",
            "name": "ozone",
            "valuePPB": 10,
            "valueUGM3": 20,
            "aqi": 9,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          },
          {
            "type": "pm2.5",
            "name": "particle matter (<2.5µm)",
            "valuePPB": null,
            "valueUGM3": 46,
            "aqi": 127,
            "category": "usg",
            "color": "FF7E00",
            "method": "airnow"
          },
          {
            "type": "pm10",
            "name": "particle matter (<10µm)",
            "valuePPB": null,
            "valueUGM3": 51,
            "aqi": 46,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          },
          {
            "type": "co",
            "name": "carbon monoxide",
            "valuePPB": 1787,
            "valueUGM3": 2046,
            "aqi": 20,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          },
          {
            "type": "no2",
            "name": "nitrogen dioxide",
            "valuePPB": 28,
            "valueUGM3": 52,
            "aqi": 25,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          },
          {
            "type": "so2",
            "name": "sulfur dioxide",
            "valuePPB": 1,
            "valueUGM3": 3.5,
            "aqi": 2,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          }
        ],
        "date": "2023-12-13T00:00:00-08:00"
      },
      {
        "dateTimeISO": "2023-12-14T00:00:00-08:00",
        "timestamp": 1702540800,
        "aqi": 130,
        "category": "usg",
        "color": "FF7E00",
        "method": "airnow",
        "dominant": "pm2.5",
        "health": {
          "index": 2,
          "category": "low",
          "color": "0000FF"
        },
        "pollutants": [
          {
            "type": "o3",
            "name": "ozone",
            "valuePPB": 30,
            "valueUGM3": 61,
            "aqi": 28,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          },
          {
            "type": "pm2.5",
            "name": "particle matter (<2.5µm)",
            "valuePPB": null,
            "valueUGM3": 47,
            "aqi": 130,
            "category": "usg",
            "color": "FF7E00",
            "method": "airnow"
          },
          {
            "type": "pm10",
            "name": "particle matter (<10µm)",
            "valuePPB": null,
            "valueUGM3": 51,
            "aqi": 46,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          },
          {
            "type": "co",
            "name": "carbon monoxide",
            "valuePPB": 1897,
            "valueUGM3": 2172,
            "aqi": 21,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          },
          {
            "type": "no2",
            "name": "nitrogen dioxide",
            "valuePPB": 24,
            "valueUGM3": 45,
            "aqi": 22,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          },
          {
            "type": "so2",
            "name": "sulfur dioxide",
            "valuePPB": 1,
            "valueUGM3": 2.2,
            "aqi": 1,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          }
        ],
        "date": "2023-12-14T00:00:00-08:00"
      },
      {
        "dateTimeISO": "2023-12-15T00:00:00-08:00",
        "timestamp": 1702627200,
        "aqi": 126,
        "category": "usg",
        "color": "FF7E00",
        "method": "airnow",
        "dominant": "pm2.5",
        "health": {
          "index": 3,
          "category": "low",
          "color": "0000FF"
        },
        "pollutants": [
          {
            "type": "o3",
            "name": "ozone",
            "valuePPB": 11,
            "valueUGM3": 23,
            "aqi": 10,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          },
          {
            "type": "pm2.5",
            "name": "particle matter (<2.5µm)",
            "valuePPB": null,
            "valueUGM3": 46,
            "aqi": 126,
            "category": "usg",
            "color": "FF7E00",
            "method": "airnow"
          },
          {
            "type": "pm10",
            "name": "particle matter (<10µm)",
            "valuePPB": null,
            "valueUGM3": 52,
            "aqi": 47,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          },
          {
            "type": "co",
            "name": "carbon monoxide",
            "valuePPB": 2811,
            "valueUGM3": 3219,
            "aqi": 31,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          },
          {
            "type": "no2",
            "name": "nitrogen dioxide",
            "valuePPB": 25,
            "valueUGM3": 47,
            "aqi": 23,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          },
          {
            "type": "so2",
            "name": "sulfur dioxide",
            "valuePPB": 1,
            "valueUGM3": 2.7,
            "aqi": 1,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          }
        ],
        "date": "2023-12-15T00:00:00-08:00"
      },
      {
        "dateTimeISO": "2023-12-16T00:00:00-08:00",
        "timestamp": 1702713600,
        "aqi": 55,
        "category": "moderate",
        "color": "FFFF00",
        "method": "airnow",
        "dominant": "pm2.5",
        "health": {
          "index": 5,
          "category": "moderate",
          "color": "00FF00"
        },
        "pollutants": [
          {
            "type": "o3",
            "name": "ozone",
            "valuePPB": 24,
            "valueUGM3": 48,
            "aqi": 22,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          },
          {
            "type": "pm2.5",
            "name": "particle matter (<2.5µm)",
            "valuePPB": null,
            "valueUGM3": 14,
            "aqi": 55,
            "category": "moderate",
            "color": "FFFF00",
            "method": "airnow"
          },
          {
            "type": "pm10",
            "name": "particle matter (<10µm)",
            "valuePPB": null,
            "valueUGM3": 25,
            "aqi": 23,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          },
          {
            "type": "co",
            "name": "carbon monoxide",
            "valuePPB": 599,
            "valueUGM3": 686,
            "aqi": 7,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          },
          {
            "type": "no2",
            "name": "nitrogen dioxide",
            "valuePPB": 25,
            "valueUGM3": 46,
            "aqi": 23,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          },
          {
            "type": "so2",
            "name": "sulfur dioxide",
            "valuePPB": 2,
            "valueUGM3": 4.1,
            "aqi": 2,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          }
        ],
        "date": "2023-12-16T00:00:00-08:00"
      },
      {
        "dateTimeISO": "2023-12-17T00:00:00-08:00",
        "timestamp": 1702800000,
        "aqi": 51,
        "category": "moderate",
        "color": "FFFF00",
        "method": "airnow",
        "dominant": "pm2.5",
        "health": {
          "index": 5,
          "category": "moderate",
          "color": "00FF00"
        },
        "pollutants": [
          {
            "type": "o3",
            "name": "ozone",
            "valuePPB": 26,
            "valueUGM3": 52,
            "aqi": 23,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          },
          {
            "type": "pm2.5",
            "name": "particle matter (<2.5µm)",
            "valuePPB": null,
            "valueUGM3": 12,
            "aqi": 51,
            "category": "moderate",
            "color": "FFFF00",
            "method": "airnow"
          },
          {
            "type": "pm10",
            "name": "particle matter (<10µm)",
            "valuePPB": null,
            "valueUGM3": 18,
            "aqi": 16,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          },
          {
            "type": "co",
            "name": "carbon monoxide",
            "valuePPB": 284,
            "valueUGM3": 325,
            "aqi": 3,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          },
          {
            "type": "no2",
            "name": "nitrogen dioxide",
            "valuePPB": 16,
            "valueUGM3": 31,
            "aqi": 15,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          },
          {
            "type": "so2",
            "name": "sulfur dioxide",
            "valuePPB": 1,
            "valueUGM3": 2.9,
            "aqi": 2,
            "category": "good",
            "color": "00E400",
            "method": "airnow"
          }
        ],
        "date": "2023-12-17T00:00:00-08:00"
      }
    ],
    "profile": {
      "tz": "America/Los_Angeles",
      "elev": null,
      "sources": [
        {
          "name": "CAMS"
        },
        {
          "name": "Vaisala Xweather"
        }
      ],
      "stations": null
    }
  }
]

Endpoints