# 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

# Request Parameters

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

# 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.

The request returns this response:

# Customized Request

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

# Response Data Fields

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

# 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:

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

# 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:

# 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:

# 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:

# Request Parameters

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

# Examples

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

# 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=

# 2. Next number of hours

This request returns three hourly forecasts from UTC

The request returns this response:

# 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=

The request returns this response:

# Response Data Fields

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

# 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:

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

# 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:

# 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:

# 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:

# Request Parameters

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

# Examples

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

# 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=

The request returns this response:

# 2. Previous number of past hours

This request returns three hourly history from UTC

The request returns this response:

# 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=

The request returns this response:

# Response Data Fields

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

# 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:

# Features

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

# Pollutants Features

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

# 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:

# 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:

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

# Metadata Fields

Metadata objects can include these fields.

# 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:

# 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:

# 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.