# Air Quality API v2

Last updated: Jul 29, 2021

The Air Quality API lets you request air quality information including indexes, pollutants, and health recommendations for a specific location. The API provides endpoints that let you query:

# Current Conditions

Last updated: Jul 29, 2021

Returns current air-quality conditions for a specific location

https://api.breezometer.com/air-quality/v2/current-conditions?lat={latitude}&lon={longitude}&key=YOUR_API_KEY&features={Features_List}

# Request Parameters

While making an API request some parameters are required while some are optional.

lat
float
Latitude (lat) specifies north-south position of a point in a range between -90 and 90
Required
lon
float
Longitude (lon) specifies east-west position of a point in a range between -180 to 180
Required
key
string
Your BreezoMeter API key
Required
features
string
Sets the data fields returned by the response. Possible values:
  • breezometer_aqi (default)
  • local_aqi
  • health_recommendations
  • sources_and_effects
  • dominant_pollutant_concentrations
  • pollutants_concentrations
  • pollutants_aqi_information
For the list of the data fields returned with each feature, see Features List
Example: breezometer_aqi,local_aqi,sources_and_effects
Note: You must separate every two features with a comma, and use the exact naming convention as shown in the possible values.
Optional
default: breezometer_aqi
metadata
boolean
Includes request metadata in the response
Optional
default: false
lang
string
Sets the response language to either:
  • en for English (default)
  • fr for French
  • de for German
  • es for Spanish
  • nl for Dutch
  • it for Italian
  • ko for Korean
  • ru for Russian
  • hi for Hindi
  • ja for Japanese
  • ms-SG for Malay (Singapore)
Optional
default: en
breezometer_aqi_color
String
Set the BreezoMeter AQI color palette for the BreezoMeter AQI color field received:
  • red_green (default)
  • indiper_dark (dark theme)
  • indiper_light (light theme)
Optional
default: red_green

# Examples

Last updated: Nov 1, 2018

# Default Request Settings

This example shows a request to get the current air quality conditions for central Paris (48.857456, 2.354611) using the default request parameters settings.

https://api.breezometer.com/air-quality/v2/current-conditions?lat=48.857456&lon=2.354611&key=YOUR_API_KEY

TIP

Note:

In this example only some of the available data fields returns, as it uses the default settings, which sets only the breezometer_aqi feature.

The request returns this response:

    "loading..."  

# Customized Request

In the example, the request was customized to include additional features:

https://api.breezometer.com/air-quality/v2/current-conditions?lat=48.857456&lon=2.354611&key=YOUR_API_KEY&features=breezometer_aqi,local_aqi,health_recommendations,sources_and_effects,pollutants_concentrations,pollutants_aqi_information

TIP

Note:

Both request made with default and customized settings are counted as a single object, regardless of the number of features included in the original query.

    "loading..."  

# Response Data Fields

Last updated: Nov 1, 2018

The response data field is an object that includes the following fields:

TIP

Note:

  • As in requests to the current conditions endpoint, the most recent data is returned, the data_available field is always returned with true value.
datetime
string
ISO 8601 UTC timestamp indicating the time the data refers to
data_available
boolean
True/false indicating whether the expected data is available
indexes
object
Dictionary of two air quality indexes:
  • BreezoMeter AQI (baqi)
  • Local AQI set to be the default index for requested location (country)
For the list of supported indexes, see Air Quality Indexes
Show child fields
pollutants
object
Dictionary of available pollutants at the requested location.
Note:
  • This dictionary will be returned only for requests specifies the features parameter, and set it up with at least one of these options:
    • sources_and_effects
    • dominant_pollutant_concentrations
    • pollutants_concentrations
    • pollutants_aqi_information and breezometer_aqi
  • The specific pollutants returned under this dictionary, are based on the logic of the features specified in the request.

    For the logic of each of the features, see Features List
Show child fields
health_recommendations
object
Object containing BreezoMeter health advice and recommended actions relates to the reported air quality conditions. Recommendations are tailored for at risk populations and groups with greater sensitivities to pollutants than the general population
Show child fields

# Hourly Forecast

Last updated: Jul 29, 2021

Returns hourly air-quality forecasts for the specified location. Each forecast includes hourly air quality indexes, pollutant data, and health recommendations for a maximum of 96 hours (4 days).

# Requesting Hourly Forecasts

You can request forecasts for:

  1. A specific date and time
  2. The next number of hours
  3. Over a time period

TIP

Apart from the parameters that indicate the required time period, requests to the Hourly Forecast API endpoint use the same parameters

# 1. Specific date and time

To request hourly forecasts from the specified date and time, use this URL and set the datetime parameter to the required date and time:

https://api.breezometer.com/air-quality/v2/forecast/hourly?lat={latitude}&lon={longitude}&key=YOUR_API_KEY&datetime={the_required_date_and_time}&features={Features_List}

# 2. Next number of hours

To request hourly forecasts for the next number of hours, use this URL and set the hours parameter for the required number of hours:

https://api.breezometer.com/air-quality/v2/forecast/hourly?lat={latitude}&lon={longitude}&key=YOUR_API_KEY&hours={number_of_forecast_hours}&features={Features_List}

# 3. Time period/date range

To request hourly forecasts over a defined time period, use this URL and set the start_datetime and end_datetime to indicate the time and dates the period starts and ends:

https://api.breezometer.com/air-quality/v2/forecast/hourly?lat={latitude}&lon={longitude}&key=YOUR_API_KEY&start_datetime={the_required_start_date_and_time}&end_datetime={the_required_end_date_and_time}&features={Features_List}

# Request Parameters

While making an API request some parameters are required while some are optional.

lat
float
Latitude (lat) specifies north-south position of a point in a range between -90 and 90
Required
lon
float
Longitude (lon) specifies east-west position of a point in a range between -180 to 180
Required
key
string
Your BreezoMeter API key
Required
datetime
string
OR
ISO 8601 UTC datetime (including timezone) from which to return hourly forecasts
OR
hours
integer
OR
Number from 1 to 96 that indicates how many hourly forecast to request
OR
start_datetime
end_datetime
string
ISO 8601 UTC datetime (including timezone) that indicates from when, and until when to request forecasts
Required
Notice: Only one of these options can be included in each hourly forecast API endpoint request.
features
string
Sets the data fields returned by the response. Possible values:
  • breezometer_aqi (default)
  • local_aqi
  • health_recommendations
  • sources_and_effects
  • dominant_pollutant_concentrations
  • pollutants_concentrations
  • pollutants_aqi_information
For the list of the data fields returned with each feature, see Features List
Example: breezometer_aqi,local_aqi,sources_and_effects
Note: You must separate every two features with a comma, and use the exact naming convention as shown in the possible values.
Optional
default: breezometer_aqi
metadata
boolean
Includes request metadata in the response
Optional
default: false
lang
string
Sets the response language to either:
  • en for English (default)
  • fr for French
  • de for German
  • es for Spanish
  • nl for Dutch
  • it for Italian
  • ko for Korean
  • ru for Russian
  • hi for Hindi
  • ja for Japanese
  • ms-SG for Malay (Singapore)
Optional
default: en
breezometer_aqi_color
String
Set the BreezoMeter AQI color palette for the received BreezoMeter AQI color field:
  • red_green (default)
  • indiper_dark (dark theme)
  • indiper_light (light theme)
Optional
default: red_green

# Examples

Last updated: Nov 1, 2018

The URLs in the following examples do not include the feature parameter, therefore the default dataset is returned in the API response.

TIP

Notes:

  • Each example request is being sent now, on UTC, they request data for central Paris (Latitude:48.857456, Longitude: 2.354611).
  • The resolution of requests to these endpoint is hourly. This means that received requests round the specified datetime to the previous exact hour. For example a request sent where the datetime parameter is set to will be rounded down to

# 1. Specific Date and Time

This request returns hourly forecasts for UTC.

https://api.breezometer.com/air-quality/v2/forecast/hourly?lat=48.857456&lon=2.354611&key=YOUR_API_KEY&datetime=

TIP

Notes:

In hourly forecast requests, the datetime parameter, must be:

  • Later than the exact UTC time for the next hour.
  • Up to 96 hours from the current time
  • Within the period permitted for your account for hourly forecast endpoint request
    "loading..."  

# 2. Next number of hours

This request returns three hourly forecasts from UTC

https://api.breezometer.com/air-quality/v2/forecast/hourly?lat=48.857456&lon=2.354611&key=YOUR_API_KEY&hours=3

TIP

Notes:

In hourly forecast requests, the hours parameter, must be:

  • Up to 96 hours from the current time
  • Within the period permitted for your account for hourly forecast endpoint request

The request returns this response:

    "loading..."  

# 3. Time period/date range

This request returns hourly forecasts starting from UTC and ending on UTC.

https://api.breezometer.com/air-quality/v2/forecast/hourly?lat=48.857456&lon=2.354611&key=YOUR_API_KEY&start_datetime=&end_datetime=

TIP

Notes:

In hourly forecast requests, the start_datetime and end_datetime parameters, must:

  • Include `start_datetime` and `end_datetime` parameters
  • Set the `start_datetime` parameter to a time that is:
    • Later than the exact UTC time for the next hour
    • To precedes `end_datetime`
  • Set the `end_datetime` parameter to a time that is upto 96 hours from the current time
  • Within the period permitted for your account for hourly forecast endpoint request

The request returns this response:

    "loading..."  

# Response Data Fields

Last updated: Nov 1, 2018

The response data field is an object or an array of objects, where each of them include the following fields:

TIP

Note:

  • As in requests to the hourly forecasts endpoint, there is no concern for a missing forecast data, the data_available field is always returned with true value for any of the objects in the response.
datetime
string
ISO 8601 UTC timestamp indicating the time the data refers to
data_available
boolean
True/false indicating whether the expected data is available
indexes
object
Dictionary of two air quality indexes:
  • BreezoMeter AQI (baqi)
  • Local AQI set to be the default index for requested location (country)
For the list of supported indexes, see Air Quality Indexes
Show child fields
pollutants
object
Dictionary of available pollutants at the requested location.
Note:
  • This dictionary will be returned only for requests specifies the features parameter, and set it up with at least one of these options:
    • sources_and_effects
    • dominant_pollutant_concentrations
    • pollutants_concentrations
    • pollutants_aqi_information and breezometer_aqi
  • The specific pollutants returned under this dictionary, are based on the logic of the features specified in the request.

    For the logic of each of the features, see Features List
Show child fields
health_recommendations
object
Object containing BreezoMeter health advice and recommended actions relates to the reported air quality conditions. Recommendations are tailored for at risk populations and groups with greater sensitivities to pollutants than the general population
Show child fields

# Hourly History

Last updated: Jul 29, 2021

Returns historical hourly air-quality information for the specified location. Each request includes hourly air quality indexes, pollutant data, and health recommendations for a maximum of 720 hours (30 days).

# Requesting Hourly History

You can request history for:

  1. A specific date and time
  2. The previous number of past hours
  3. A time period

TIP

Note:

Apart from the parameters that indicate the required time period, requests to the Hourly History API endpoint use the same parameters

# 1. Specific date and time

To request hourly history from the specified date and time, use this URL and set the datetime parameter to the required date and time:

https://api.breezometer.com/air-quality/v2/historical/hourly?lat={latitude}&lon={longitude}&key=YOUR_API_KEY&datetime={the_required_date_and_time}&features={Features_List}

# 2. Previous number of past hours

To request hourly history for the previous number of hours, use this URL and set the hours parameter for the required number of hours:

https://api.breezometer.com/air-quality/v2/historical/hourly?lat={latitude}&lon={longitude}&key=YOUR_API_KEY&hours={number_of_history_hours}&features={Features_List}

# 3. Time period/date range

To request hourly historical data over a defined time period, use this URL and set the start_datetime and end_datetime to indicate the time and dates the period starts and ends:

https://api.breezometer.com/air-quality/v2/historical/hourly?lat={latitude}&lon={longitude}&key=YOUR_API_KEY&start_datetime={the_required_start_date_and_time}&end_datetime={the_required_end_date_and_time}&features={Features_List}

# Request Parameters

While making an API request some parameters are required while some are optional.

lat
float
Latitude (lat) specifies north-south position of a point in a range between -90 and 90
Required
lon
float
Longitude (lon) specifies east-west position of a point in a range between -180 to 180
Required
key
string
Your BreezoMeter API key
Required
datetime
string
OR
ISO 8601 UTC datetime (including timezone) from which to return hourly historical data
OR
hours
integer
OR
Number from 1 to 168 that indicates how many hourly historical hours data to request
OR
start_datetime
end_datetime
string
ISO 8601 UTC datetime (including timezone) that indicates from when, and until when to request historical hours data
Required
Notice: Only one of these options can be included in each hourly history API endpoint request.
features
string
Sets the data fields returned by the response. Possible values:
  • breezometer_aqi (default)
  • local_aqi
  • health_recommendations
  • sources_and_effects
  • dominant_pollutant_concentrations
  • pollutants_concentrations
  • pollutants_aqi_information
For the list of the data fields returned with each feature, see Features List
Example: breezometer_aqi,local_aqi,sources_and_effects
Note: You must separate every two features with a comma, and use the exact naming convention as shown in the possible values.
Optional
default: breezometer_aqi
metadata
boolean
Includes request metadata in the response
Optional
default: false
lang
string
Sets the response language to either:
  • en for English (default)
  • fr for French
  • de for German
  • es for Spanish
  • nl for Dutch
  • it for Italian
  • ko for Korean
  • ru for Russian
  • hi for Hindi
  • ja for Japanese
  • ms-SG for Malay (Singapore)
Optional
default: en
breezometer_aqi_color
String
Set the BreezoMeter AQI color palette for the received BreezoMeter AQI color field:
  • red_green (default)
  • indiper_dark (dark theme)
  • indiper_light (light theme)
Optional
default: red_green

# Examples

Last updated: Nov 1, 2018

The URLs in the following examples do not include the feature parameter, therefore the default dataset is returned in the API response.

TIP

Notes:

  • Each example request is being sent now, on UTC, they request data for central Paris (Latitude:48.857456, Longitude: 2.354611).
  • The resolution of requests to these endpoint is hourly. This means that received requests round the specified datetime to the previous exact hour. For example a request sent where the datetime parameter is set to will be rounded down to

# 1. Specific Date and Time

This request returns hourly history from UTC.

https://api.breezometer.com/air-quality/v2/historical/hourly?lat=48.857456&lon=2.354611&key=YOUR_API_KEY&datetime=

TIP

Notes:

In hourly history requests, the datetime parameter, must be:

  • Precede the exact UTC time
  • Within 720 hours from the current time
  • Within the period permitted for your account for hourly history endpoint request

The request returns this response:

    "loading..."  

# 2. Previous number of past hours

This request returns three hourly history from UTC

https://api.breezometer.com/air-quality/v2/historical/hourly?lat=48.857456&lon=2.354611&key=YOUR_API_KEY&hours=3

TIP

Notes:

In hourly history requests, the hours parameter, must be:

  • A number between 1 and 168 hours
  • Within the period permitted for your account for hourly historical endpoint request

The request returns this response:

    "loading..."  

# 3. Time period/date range

This request returns hourly historical starting from UTC and ending on UTC.

https://api.breezometer.com/air-quality/v2/historical/hourly?lat=48.857456&lon=2.354611&key=YOUR_API_KEY&start_datetime=&end_datetime=

TIP

Notes:

In hourly history requests, the start_datetime and end_datetime parameters, must:

  • Include `start_datetime` and `end_datetime` parameters
  • Set the `start_datetime` parameter to a time that is:
    • Up to 720 hours from the current time
    • To precedes `end_datetime`
  • Set the `end_datetime` parameter to a time that precedes the exact UTC time
  • Within the period permitted for your account for hourly history endpoint request

The request returns this response:

    "loading..."  

# Response Data Fields

Last updated: Nov 1, 2018

The response data field is an object or an array of objects, where each of them include the following fields:

TIP

Note:

  • In case there is a missing data for a specific object (which represents a specific hour), the data_available field in that specific object returns with false, and the rest of the expected root level elements (Indexes, pollutants, and Health_recommendations) returns null
datetime
string
ISO 8601 UTC timestamp indicating the time the data refers to
data_available
boolean
True/false indicating whether the expected data is available
indexes
object
Dictionary of two air quality indexes:
  • BreezoMeter AQI (baqi)
  • Local AQI set to be the default index for requested location (country)
For the list of supported indexes, see Air Quality Indexes
Show child fields
pollutants
object
Dictionary of available pollutants at the requested location.
Note:
  • This dictionary will be returned only for requests specifies the features parameter, and set it up with at least one of these options:
    • sources_and_effects
    • dominant_pollutant_concentrations
    • pollutants_concentrations
    • pollutants_aqi_information and breezometer_aqi
  • The specific pollutants returned under this dictionary, are based on the logic of the features specified in the request.

    For the logic of each of the features, see Features List
Show child fields
health_recommendations
object
Object containing BreezoMeter health advice and recommended actions relates to the reported air quality conditions. Recommendations are tailored for at risk populations and groups with greater sensitivities to pollutants than the general population
Show child fields

# Customizing API Requests

Last updated: Nov 1, 2018

You can customize any API request to only include the data you need for your software. This allows you to save bandwidth and decrease response time by requesting less information. You customize request data returned using the features parameter to define the feature or list of features to include in the response.

# Example

The following returns current air quality conditions including the breezometer_aqi, local_aqi, and sources_and_effects features:

https://api.breezometer.com/air-quality/v2/current-conditions?lat=48.857456&lon=2.354611&key=YOUR_API_KEY&features=breezometer_aqi,local_aqi,sources_and_effects

TIP

Note:

Unless you have specified the features parameter in the request, the response returns only the BreezoMeter AQI information.

# Features

Last updated: Nov 1, 2018

Here are the various supported features and details on each of them.

Feature Description
breezometer_aqi BreezoMeter air quality index, including its value, color, category, and the dominant pollutant according to that index.

This data is located in the data > indexes > baqi object

The response includes these fields: display_name, aqi, aqi_display, color, category, and dominant_pollutant

Note:
BreezoMeter Air Quality Index (BAQI), is a globally unified index that uses a scale of 0 (Poor) to 100 (Excellent). BAQI simplifies comparing air quality between countries. For more information, see BreezoMeter AQI
local_aqi Local (national) air quality index for the requested location (country), including its value, color, category, and the dominant pollutant according to that index.This data is located in the data > indexes > {index code} object

For the list of supported indexes codes, see Air Quality Indexes

The response includes these fields: display_name, aqi, aqi_display, color, category, and dominant_pollutant

Note:
BreezoMeter supports more than 55 official local indexes.
health_recommendations BreezoMeter health advice and recommended actions for current AQI conditions. Recommendations are tailored for the general population, and six at risk populations and groups with greater sensitivities to pollutants than the general population

This data is located in the data > indexes > health_recommendations object

The response includes these recommendations: general_population, elderly, lung_diseases, heart_diseases, active, pregnant_women, and children

# Pollutants Features

Here are the rest of the features, all of which return information on pollutants

TIP

Note:

If you include in your request any of the following features, the display_name and full_name data fields will also be returned under each of the relevant pollutants as part of the response

Feature Description
sources_and_effects Sources and effects for each of the pollutants returned in the response

This data is located in the data > pollutants > {pollutant code} > sources_and_effects object

The response includes these fields: sources, effects
dominant_pollutant_concentrations Concentrations of the dominant pollutants measured according to BreezoMeter and/or local indexes

This data is located in the data > pollutants > {pollutant code} > concentration object

The response includes these fields: value, units

Note:
If the request specified both the breezometer_aqi and the local_aqi features, there may be upto two {pollutant code} returned with concentration object
pollutants_concentrations Concentrations of all pollutants with available measurements according to BreezoMeter and/or local indexes

This data is located in the data > pollutants > {pollutant code} > concentration object

The response includes these fields: value, units
pollutants_aqi_information Detailed BreezoMeter index information for each of the six common pollutants the index is based on. It describes the severity of each pollutants with the relevant value, color, and category.

This data is located in the data > pollutants > {pollutant code} > aqi_information > baqi object

The response includes these fields: display_name, aqi, aqi_display, color, and category

Note:
This feature can only be used for requests that specified the breezometer_aqi feature as well

# Metadata

Last updated: Jul 29, 2021

# Request Metadata

Last updated: Nov 1, 2018

Any request to an API endpoint can return metadata that describes the original request. You request metadata by including the metadata parameter in your request with the value true. When excluding the metadata parameter, or setting it to false, the metadata field returns null.

When requested, it has slightly different structure, depending on the request type.

# Single Object

Requests for a specific date and time return a single object, and a metadata object with a single timestamp. This example shows a request to the hourly forecast endpoint for a specific date and time that returns metadata:

https://api.breezometer.com/air-quality/v2/forecast/hourly?lat=48.857456&lon=2.354611&key=YOUR_API_KEY&datetime=&metadata=true

The request returns this metadata object as part of the response:

    "loading..."  

# Array of Objects

Requests for the next number of hours or time period return an array of objects, and a metadata object with a range of timestamps. This example shows a request to the hourly forecast API endpoint for the next three hours that returns metadata:

https://api.breezometer.com/air-quality/v2/forecast/hourly?lat=48.857456&lon=2.354611&key=YOUR_API_KEY&hours=3&metadata=true

The request’s JSON response includes the following metadata object:

    "loading..."  

# Metadata Fields

Metadata objects can include these fields.

timestamp
string
OR
In Request for a Single Object - ISO 8601 UTC timestamp indicating the time the request was made
OR
start_timestamp
end_timestamp
string
In Request for an Array of Objects - Two ISO 8601 UTC timestamps:
  • start_timestamp - indicates from when the hourly data was requested
  • end_timestamp - indicates until when the hourly data was requested
location
object
Object containing information describing the requested location
Show child fields
indexes
object
Dictionary of upto two air quality indexes: (as included in the response data)
  • BreezoMeter AQI (baqi)
  • Local AQI set to be the default index for requested location (country)
Show child fields

# Supported Pollutants

Last updated: Nov 1, 2018

The BreezoMeter API supports various pollutants, which it make accessible through the different air quality endpoints. Pollutants availability is subject to actual measurements and reports available for BreezoMeter to use, and is changing between different locations.

Here are the various pollutants codes and their metadata we might return:

Code Display Name Full Name Units Measured
co CO Carbon monoxide ppb
c6h6 C6H6 Benzene ug/m3
ox Ox Photochemical oxidants ppb
o3 O3 Ozone ppb
nh3 NH3 Ammonia ppb
nmhc NMHC Non-methane hydrocarbons ppb
no NO Nitrogen monoxide ppb
nox NOx Nitrogen oxides ppb
no2 NO2 Nitrogen dioxide ppb
pm25 PM25 Fine particulate matter (<2.5µm) ug/m3
pm10 PM10 Inhalable particulate matter (<10µm) ug/m3
so2 SO2 Sulfur dioxide ppb
trs TRS Total reduced sulfur ug/m3

# Supported Air Quality Indexes

Last updated: Jul 29, 2021

The BreezoMeter API supports over 50 different air quality indexes, including its own BreezoMeter Air Quality Index.

Here are the various indexes codes and their metadata we might return:

Code Display Name Best Value Worst Value Categories Pollutants

For your convenience, you can download a JSON file with the above indexes metadata. The metadata available in any of the languages supported by the BreezoMeter API.

# BAQI color palette

Last updated: Aug 1, 2020

The Breezometer AQI color value supports multiple palettes, while the returned value will be set according to one of the following:

  • red_green (default) red green

  • indiper_dark - Our new indiper color palette, adapted for dark color backgrounds. indiper dark

  • indiper_light - Our new indiper color palette, adapted for light color backgrounds. indiper light

The required palette can be set as an additional parameter within the different air quality endpoints.

For example, to get the Current Conditions air quality with the “indiper_dark” color palette, concatenate the following API request: https://api.breezometer.com/air-quality/v2/current-conditions?lat={latitude}&lon={longitude}&key=YOUR_API_KEY&features={Features_List}&breezometer_aqi_color=indiper_dark

In cases where the new indiper palettes do not fit your background correctly, please use the Custom BAQI color palette description as a reference.

Integrate BreezoMeter's data in your products today

Get API Key
Talk to an expert