# Air Quality API v2
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
- Hourly Forecast for up to four days
- Hourly History for a maximum of 30 days
# Current Conditions
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.
- breezometer_aqi (default)
- local_aqi
- health_recommendations
- sources_and_effects
- dominant_pollutant_concentrations
- pollutants_concentrations
- pollutants_aqi_information
- 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)
- red_green (default)
- indiper_dark (dark theme)
- indiper_light (light theme)
# Examples
# 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.
# Response Data Fields
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.
- BreezoMeter AQI (baqi)
- Local AQI set to be the default index for requested location (country)
- 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
# Hourly Forecast
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:
- A specific date and time
- The next number of hours
- 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.
- breezometer_aqi (default)
- local_aqi
- health_recommendations
- sources_and_effects
- dominant_pollutant_concentrations
- pollutants_concentrations
- pollutants_aqi_information
- 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)
- red_green (default)
- indiper_dark (dark theme)
- indiper_light (light theme)
# Examples
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
# 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
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.
- BreezoMeter AQI (baqi)
- Local AQI set to be the default index for requested location (country)
- 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
# Hourly History
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:
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.
- breezometer_aqi (default)
- local_aqi
- health_recommendations
- sources_and_effects
- dominant_pollutant_concentrations
- pollutants_concentrations
- pollutants_aqi_information
- 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)
- red_green (default)
- indiper_dark (dark theme)
- indiper_light (light theme)
# Examples
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
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
- BreezoMeter AQI (baqi)
- Local AQI set to be the default index for requested location (country)
- 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
# Customizing API Requests
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
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 (opens new window) |
| 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_pollutantNote: 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
# Request Metadata
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.
- BreezoMeter AQI (baqi)
- Local AQI set to be the default index for requested location (country)
# Supported Pollutants
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
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
The Breezometer AQI color value supports multiple palettes, while the returned value will be set according to one of the following:
red_green (default)
indiper_dark - Our new indiper color palette, adapted for dark color backgrounds.
indiper_light - Our new indiper color palette, adapted for light color backgrounds.
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.
Get API Key