# Air Quality API v1
This document is intended for website and mobile developers who want to use air quality data provided by one of the BreezoMeter APIs
A proper BreezoMeter API request must be of the following form:
https://api.breezometer.com/baqi/?parameters
To access the BreezoMeter API over HTTP, use:
http://api.breezometer.com/baqi/?parameters
While making an API request some parameters are required while some are optional. As is standard in URLs, parameters are separated using the ampersand (&) character.
# Real Time
Get BreezoMeter Air Quality Index by Latitude and Longitude (Geocoding)
You can get air quality data by Latitude and Longitude (Geocoding), simply by concatenating the following API request:
https://api.breezometer.com/baqi/?lat={latitude}&lon={longitude}&key=YOUR_API_KEY
# Required parameters
lat– Latitude is a geographic coordinate that specifies the north-south position of a point on the Earth’s surface. Range between -90 to 90 (WGS84 standard (opens new window))lon- Longitude is a geographic coordinate that specifies the east-west position of a point on the Earth’s surface. Range between -180 to 180 (WGS84 standard (opens new window))key– Your BreezoMeter API key. This key identifies your account for purposes of quota management and features access.
# Optional parameters
lang– Response language. We support English -enand Hebrew -he.
# Responses
The responses are returned in JSON format. In this example, the BreezoMeter Air Quality Index by Latitude and Longitude response for the query on Latitude=40.7324296, Longitude=-73.9977264. This request demonstrates:
https://api.breezometer.com/baqi/?lat=40.7324296&lon=-73.9977264&key=YOUR_API_KEY
# Customize Your API Request
You can customize your API request to get only the specific data you want in the response. Concatenate the API request with the fields you wish to get in the response. The responses are returned in JSON format.
In this example, the BreezoMeter Air Quality Index for “5th Avenue, New York, NY, United States” with the coordinates lat=40.7324296 and lon=-73.9977264 query on with customization to get only the BreezoMeter AQI and Recommendations fields.
# Example request
https://api.breezometer.com/baqi/?lat=40.7324296&lon=-73.9977264&fields=breezometer_aqi,random_recommendations&key=YOUR_API_KEY
# Example response
"children" : "Let the children enjoy the fresh outdoor air - You should play with them too!" , "sport" : "This is an excellent opportunity to enjoy your favorite outdoor activity without any worries" , "health" : "This air quality is excellent for people with respiratory sensitivities" , "inside" : "Let the air outside freshen up your home" , "outside" : "Hooray! The air quality outside is awesome!" } , "breezometer_aqi" : 80 }# Possible fields
breezometer_aqi | breezometer_color |
breezometer_description | country_name |
country_aqi_prefix | country_aqi |
country_color | country_description |
random_recommendations | dominant_pollutant_canonical_name |
dominant_pollutant_description | dominant_pollutant_text |
pollutants | datetime |
data_valid |
# History
BreezoMeter history air quality data API requests are just as easy and friendly to use as our real-time requests. History API calls can be made to return both:
- Air Quality data for a specific date/time in a specific location
- Air Quality data for a range of dates in a specific location
We use ISO 8601 (opens new window) standard for our timestamp. The standard is built as such:
YYYY-MM-DDTHH:mm:SS.
# Specific date
History API queries are equivalent and priced as several API calls, depending on the length of the time interval queried which affects the number of data objects returned. Each returned data object (maximum one per 1 hour) is priced as one API call. e.g.
The maximum price for historical api call will be: 14 days * 24 hour * API call price.
You can get history air quality data for a specific date/time in a specific location (Latitude and Longitude) by concatenating the following API request:
https://api.breezometer.com/baqi/?datetime={the_required_date}&lat={latitude}&lon={longitude}&key=YOUR_API_KEY
# Required parameters
datetime– The specific time you wish to get air quality data for.- Location
lat– Latitude is a geographic coordinate that specifies the north-south position of a point on the Earth’s surface. Range between -90 to 90 (WGS84 standard (opens new window))lon– Longitude is a geographic coordinate that specifies the east-west position of a point on the Earth’s surface. Range between -180 to 180 (WGS84 standard (opens new window))
key– Your BreezoMeter API key. This key identifies your account for purposes of quota management and features access.
# Optional parameters
lang– Response language. We support English -enand Hebrew -he.
# Responses
The responses are returned in JSON format.
In this example, the BreezoMeter History Air Quality Data for A Specific Date response for the query on DateTime=2015-10-26T16:18:34 and Latitude=40.7324296, Longitude=-73.9977264.
# Example request
https://api.breezometer.com/baqi/?datetime=2015-10-26T16:18:34&lat=40.7324296&lon=-73.9977264&key=YOUR_API_KEY
# Example response
"datetime" : "2015-10-26T16:00:00" , "country_name" : "United States" , "breezometer_aqi" : 82 , "breezometer_color" : "#4FBB35" , "breezometer_description" : "Excellent Air Quality" , "country_aqi" : 22 , "country_aqi_prefix" : "" , "country_color" : "#00E400" , "country_description" : "Good air quality" , "data_valid" : true , "key_valid" : true , "dominant_pollutant_canonical_name" : "pm2.5" , "dominant_pollutant_description" : "Fine particulate matter (<2.5µm)" , }# Range of dates
You can get history air quality data for a range of dates in a specific location (Latitude and Longitude) with a start and end timestamps that will provide an array of results.
To get air quality data for a range of dates at a given location you need to concatenate the following API request:
https://api.breezometer.com/baqi/?start_datetime={the_required_start_date}&end_datetime={the_required_end_date}&lat={latitude}&lon={longitude}&key=YOUR_API_KEY
# Required parameters
start_datetime– The specific start time you wish to get air quality data for.end_datetime– The specific end time you wish to get air quality data for.- Location
lat– Latitude is a geographic coordinate that specifies the north-south position of a point on the Earth’s surface. Range between -90 to 90 (WGS84 standard (opens new window))lon– Longitude is a geographic coordinate that specifies the east-west position of a point on the Earth’s surface. Range between -180 to 180 (WGS84 standard (opens new window))
key– Your BreezoMeter API key. This key identifies your account for purposes of quota management and features access.
# Optional parameters
interval– A time interval represents a period of time (hours) between two BAQI objects. You can choose an interval value (Integer) between 1-24 hours.lang– Response language. We support English -enand Hebrew -he.
# Responses
The responses are returned in JSON format.
# Example request
https://api.breezometer.com/baqi/?lat=40.7324296&lon=-73.9977264&interval=1&start_datetime=2018-08-26T15:00:00&end_datetime=2018-08-27T15:00:00&key=YOUR_API_KEY
# Forecast
BreezoMeter Air Quality Forecast API requests are very similar to our historical API requests and are straightforward and simple to use.
Forecast API calls can provide:
- Air quality data forecasts for a specific location for the next 24 hours
- Air quality forecast data for a range of dates at a specific location for up to four days
We use the date and time format ISO 8601 (opens new window) standard for our timestamp. The standard is represented as:
YYYY-MM-DDTHH:mm:SS
Forecast API queries are priced as API calls, returning 24 objects per request and priced individually per object depending on the length of the time interval queried, which affects the number of data objects returned. Each returned data object (maximum one per hour) is priced as one API call.
e.g. The maximum price for each forecast API query equivalent Forecast API call will be: 4 days * 24 hour * API call price.
# 24 Hours
You can get forecast air quality data for the next 24 hours in a specific location (latitude and longitude) by concatenating the following API request:
https://api.breezometer.com/forecast/?lat={latitude}&lon={longitude}&key=YOUR_API_KEY
# Required parameters
- Location
lat– Latitude is a geographic coordinate that specifies the north-south position of a point on the Earth’s surface. Range between -90 to 90 (WGS84 standard (opens new window))lon– Longitude is a geographic coordinate that specifies the east-west position of a point on the Earth’s surface. Range between -180 to 180 (WGS84 standard (opens new window))
key– Your BreezoMeter API key. This key identifies your account for purposes of quota management and features access.
# Optional parameters
hours– hours represents the period of time for the Forecast data you’ll receive. You can choose any value (integer) up to 96 hours. 24 hours is the default period of time if you don’t use thehoursparameter.lang– Response language. We support English -enand Hebrew -he.
# Responses
The responses are returned in JSON format.
For example, the BreezoMeter Forecast Air Quality Data for the next 48 Hours response for the query on Latitude=40.7324296, Longitude=-73.9977264 and hours=48.
# Example request
https://api.breezometer.com/forecast/?lat=40.7324296&lon=-73.9977264&hours=48&key=YOUR_API_KEY
# Range of dates
You can acquire Air Quality Forecast Data for a range of dates (up to 4 days) at a specific location (latitude and longitude) with start and end timestamps that will provide an array of results. The end date should be up to four days from the time the API request is made.
To get air quality data for a range of dates at a given location you need to concatenate the following API request:
https://api.breezometer.com/forecast/?start_datetime={the_required_start_date}&end_datetime={the_required_end_date}&lat={latitude}&lon={longitude}&key=YOUR_API_KEY
# Required parameters
start_datetime– The specific start time you wish to get air quality data for.end_datetime– The specific end time you wish to get air quality data for.- Location
lat– Latitude is a geographic coordinate that specifies the north-south position of a point on the Earth’s surface. Range between -90 to 90 (WGS84 standard (opens new window))lon– Longitude is a geographic coordinate that specifies the east-west position of a point on the Earth’s surface. Range between -180 to 180 (WGS84 standard (opens new window))
key– Your BreezoMeter API key. This key identifies your account for purposes of quota management and features access.
# Optional parameters
lang– Response language. We support English -enand Hebrew -he.
# Responses
The responses are returned in JSON format.
For example, the BreezoMeter Forecast Air Quality Data for a range of dates in response to the query on start_datetime=2018-08-28T08:00:00, end_datetime=2018-08-29T08:00:00 and Latitude=40.7324296, Longitude=-73.9977264.
# Example request
https://api.breezometer.com/forecast/?lat=40.7324296&lon=-73.9977264&start_datetime=2018-08-28T08:00:00&end_datetime=2018-08-29T08:00:00&key=YOUR_API_KEY
# Response Data Fields
This page explains in detail the response data fields for BreezoMeter’s global air quality data API.
breezometer_aqi -
BreezoMeter Air Quality Index (BAQI); Integer between 0-100 as seen here (opens new window).
breezometer_color -
BreezoMeter Air Quality Index Color. The color is between two hexadecimal numbers.
breezometer_description -
A string of BreezoMeter Air Quality Index interpretation.
| BreezoMeter AQI Values | Air Quality Interpretation |
|---|---|
| 100 – 80 | Excellent Air Quality |
| 79 – 60 | Good Air Quality |
| 59 – 40 | Moderate Air Quality |
| 39 – 20 | Low Air Quality |
| 19 – 0 | Poor Air Quality |
country_name -
The country name
country_aqi_prefix -
Some maximum AQIs have added signs, such as “X+” or “>X”. In this cases, you will get in the JSON response a prefix field with the sign to add. The field value will be “” (Empty String) when there is no sign to add.
country_aqi -
Local Air Quality Index Integer as defined by the country where the requested location is. In case the county do not have a numeric AQI will return null.
country_color -
Local Air Quality Index Color in hexadecimal number. (As detailed in the AQI scales sources).
country_description -
A string of Local Air Quality Index interpretation.
random_recommendations -
BreezoMeter Health Recommendations strings based on BreezoMeter AQI. There are different recommendations for 5 different segments:
- children
- sport – outdoor athletes
- health – health sensitives
- inside
- outside
dominant_pollutant_canonical_name -
A string of pollutant name as an acronym. For chemical compounds, this is the chemical formula (opens new window) (i.e. SO2).
dominant_pollutant_description -
A string of full pollutant name. For chemical compounds, this is the IUPAC name (opens new window) (i.e. sulfur dioxide).
dominant_pollutant_text -
Sequence of information about the pollutant that has the greatest effect on the AQI right now.
- main – General indication of the current dominant pollutant.
- effects – Main health effects of the dominant pollutant.
- causes – Main causes and emission sources of the dominant pollutant.
datetime -
The timestamp represents the BreezoMeter calculation time. In our API the timestamp is of ISO 8601 (opens new window) standard (UTC time zone).
data_valid -
Boolean value.
pollutants -
Object of all the available* pollutants information at a specific location. For each pollutant you will find:
pollutant_description– A string of full pollutant name. For chemical compounds, this is the IUPAC name (i.e. sulfur dioxide).units– In which units the pollutant concentration is measured.concentration– Value of the pollutant concentration. (in case there is no reported value, will returnnull).
* Available pollutants include those that are part of the BAQI, and any additional pollutant that is part of the returned local AQI.
# Response Codes & Errors
# HTTP Status Codes
The BreezoMeter API will return the appropriate HTTP status codes (opens new window) for every request.
| Error Code | Header | Message | Description |
|---|---|---|---|
| 1 | 200 | Success! | Success! |
| 80 | 400 | User not found | User not found |
| 10 | 403 | Invalid API key | Provided API key is invalid. Check for accidental whitespace characters and note that the key is case sensitive |
| 11 | 403 | API key not provided | User did not provide API key |
| 12 | 403 | User has been disabled | User permissions have been revoked, contact Breezometer's admin at developers@breezometer.com to enable |
| 13 | 403 | Permission denied for Heat maps API | User do not have permissions to use Air Quality Heat Maps |
| 14 | 403 | Permission denied for Dominant Pollutant | User do not have permissions to get the Dominant Pollutant data |
| 15 | 403 | Permission denied for Recommendations | User do not have permissions to get the Recommendations data |
| 16 | 403 | Permission denied for Pollutant Concentrations | User do not have permissions to get the Dominant Pollutant data |
| 17 | 403 | Permission denied for Base API | User do not have permissions for Base API |
| 18 | 403 | Permission denied | User do not have permissions |
| 19 | 403 | Permission denied for Forecast API | User do not have permissions for Forecast API |
| 20 | 200 | Provided location is unsupported. | Provided location is not supported. This could mean a country we do not cover yet, the middle of the ocean, etc If you or your clients are interested in specific locations, contact us and let us know! |
| 21 | 200 | No data available for provided location | No data available for provided location This could be temporary (i.e. when monitoring sites are down for maintenance) or permanent (i.e. remote regions where no monitoring sites are present) |
| 22 | 400 | Unable to find location | Failed to parse provided location string (geocode). Please verify spelling |
| 23 | 400 | Location not permitted | User does not have permission to get information in this location |
| 24 | 403 | Permission denied for Pollen API | User do not have permissions to use Pollen API |
| 25 | 400 | Daily query limit exceeded | Daily query limit exceeded |
| 26 | 403 | Permission denied for Weather API | User do not have permissions for Weather API |
| 30 | 400 | Invalid coordinates | Provided coordinates (lat and/or lon) are invalid. Note that coordinates are in WGS 84 standard |
| 31 | 400 | Invalid datetime | Provided datetime parameter is invalid. As a reminder, datetime must be provided according to ISO 8601 |
| 32 | 400 | Invalid start_datetime | Provided start_datetime parameter is invalid. As a reminder, datetime must be provided according to ISO 8601 |
| 33 | 400 | Invalid end_datetime | Provided end_datetime parameter is invalid. As a reminder, datetime must be provided according to ISO 8601 |
| 34 | 400 | Datetime range should be 2 weeks or less | Provided datetime range cannot exceed a maximum of two weeks |
| 35 | 400 | Invalid datetime range - start_datetime must precede end_datetime chronologically | Provided datetime range is invalid. Parameter start_date time must precede end_datetime chronologically |
| 36 | 400 | Interval must be integer in range 1-24 | Provided interval must be a positive integer in the range 1 to 24 |
| 37 | 400 | No data after start_datetime | There is no available data after the specified start datetime parameter. |
| 38 | 400 | Invalid start_date | Provided start_date parameter is invalid. |
| 39 | 400 | Invalid end_date | Provided end_date parameter is invalid. |
| 40 | 400 | Forecast datetime range should be 96 hours or less from now in UTC time | Provided datetime range cannot exceed a maximum of 96 hours from now in UTC time |
| 41 | 400 | No data before end_datetime | There is no available data before the specific end_datetime parameter, as forecast data is available only for future time. |
| 42 | 400 | No data available for this datetime | There is no data available for this datetime |
| 43 | 400 | No data available for this datetime range | There is no data available for this datetime range |
| 44 | 400 | Weather hours must be between 1 to 120 hours | Provided hours value cannot exceed a maximum of 120 hours |
| 45 | 400 | Weather days must be between 1 to 5 days | Provided days value cannot exceed a maximum of 5 days |
| 46 | 200 | No data available for provided location | No data available for provided location |
Get API Key
Talk to an expert