As spring turns to summer and everyone begins spending more time outdoors, the air we breathe is a concern for many. With most of the world’s population affected, this is not only a local concern but a global one–one that our clients care about. So we are proud to announce the addition of the Air Quality API to the AerisWeather weather API.
The air quality API endpoints within AerisWeather’s API offers the ability to obtain global air quality observations and forecasts via two new endpoints: airquality and airquality/forecasts. The new endpoints are available today as part of our AerisWeather Premium API subscription and can be tested with our free developer trial.
The air quality API endpoints provide information on the current and forecast Air Quality Index (AQI). As defined by the EPA, the Air Quality Index is a common index for reporting air quality, indicating how clean or polluted the air is that often associated with potential health effects.
The AQI covers a scale from 0 to 500 and is most commonly based on a weighted calculation of six (6) primary pollutants, including: ozone (O3), particulate matter of less than 2.5 micrometers (pm2.5), particulate matter of less than 10 micrometers (pm10), Carbon Monoxide (CO), Nitrogen Dioxide (NO2) and Sulphur Dioxide (SO2). The pollutants ozone, PM 2.5 and PM 10 are the most common.
The air quality observation endpoint provides information on the latest observed air quality data, including the AQI value, AQI category, dominate pollutant and, when available, information on the 6 common pollutants.
The endpoint can provide data via two core methods: derived air quality and raw observations. When calling the endpoint with a location, such as a city, US/Canadian postal code, or a latitude/longitude, the API will return estimated air quality information based on a combination of nearby observation stations and models. This method can assist in providing the most detailed information for a location, especially if nearby stations only provide limited pollutant data.
For example, to obtain information for Beijing, China:
1 |
https://api.aerisapi.com/airquality/beijing,china |
The location can also be passed as a parameter:
1 |
https://api.aerisapi.com/airquality/?p=beijing,china |
Or, to obtain information for Minneapolis, MN via zip code:
1 |
https://api.aerisapi.com/airquality/55403 |
In some instances, you may prefer to obtain the actual observations from one or more observation stations. With the following methods, the API will not provide estimated observations but rather the actual raw observation data received from the station.
To obtain the latest observation for the observation station East Forth in Beijing, China, you can use its station ID of AQCN_1004a:
1 |
https://api.aerisapi.com/airquality/AQCN_1004a |
Likewise, to obtain the latest observation from the US Embassy in Beijing, use station ID AQO_cn85f6cf3:
1 |
https://api.aerisapi.com/airquality/AQO_cn85f6cf3 |
Note that not all observation stations measure all pollutant types. For instance, while most of observations stations in China measure all 6 primary pollutants, the US Embassy only measures PM2.5.
A second common method to obtain observations is to query nearby stations via the closest action of the weather API. For example, to obtain the 10 closest observations within 50km of downtown Beijing, China:
1 |
https://api.aerisapi.com/airquality/closest?p=beijing,china&limit=10&radius=50km |
The API also offers the within action. This action allows querying data that is contained within a circle, bounding box or a polygon. A perfect use for this type of query is to obtain the stations within a map bounding box. This method is used for the map within the WeatherBlox air quality layout.
For example, fetching up to 250 observation stations within a bounding box surrounding Beijing, China:
1 |
https://api.aerisapi.com/airquality/within?p=40.535,114.884,39.271,117.933&limit=250 |
The weather API allows for some unique advanced queries when using a combination of the search action and the query and sort parameters. For example, to obtain the latest observation reporting the highest PM2.5 value around the globe:
1 |
https://api.aerisapi.com/airquality/search?query=pm2p5&sort=pm2p5:-1 |
To find the location within the United States reporting the highest ozone observation:
1 |
https://api.aerisapi.com/airquality/search?query=country:us&sort=o3:-1&limit=1 |
By default, the API will return an AQI calculated based on the EPA AirNow specification. The AirNOW specification is one of the most commonly utilized but not the only calculation method as some governments may define their own specifications. The Air Quality API Endpoints supports two additional AQI standards published by China and India. Review the Air Quality Wikipedia article for more information.
To obtain air quality data utilizing the China standard, pass filter=china in the API query:
1 |
https://api.aerisapi.com/airquality/beijing,china?filter=china |
Alternatively, to obtain air quality information using the India standard, pass filter=india in the query.
The air quality forecast endpoint, currently in public beta, provides forecast information for up to the next 4 days. Forecasts are available globally and in daily timeframes or custom intervals, such as hourly or three (3) hour intervals.
To obtain the hourly forecast for the next 24 hours for Minneapolis, MN:
1 |
https://api.aerisapi.com/airquality/forecasts/minneapolis,mn?filter=1hr&limit=24 |
To obtain the 48-hour forecast for London in 3-hour intervals:
1 |
https://api.aerisapi.com/airquality/forecasts/london,gb?filter=3hr&limit=16 |
The air quality forecast endpoint can provide a lot of data, though the output can be limited using the fields parameter. For example, to limit the result to the date and the AQI value:
1 |
https://api.aerisapi.com/airquality/forecasts/minneapolis,mn?&filter=1hr&limit=24&fields=periods.dateTimeISO,periods.aqi,periods.category |
Note that the Air Quality Forecasts endpoint is currently in public beta. While not recommended for production use, we are continuously improving the forecasts so that we can move forecasts out of beta in the coming weeks.
Along with offering the air quality API endpoints within the weather API, developers can quickly integrate air quality information into their websites and web applications using WeatherBlox. We have added the new Air Quality Layout and Air Quality View to the WeatherBlox library. The new air quality layout provides a full suite of information in a responsive design for use on desktop and mobile integrations. View the new layout within our WeatherBlox demo site.
The new Air Quality endpoints are available for use today with your API Premium subscriptions. Not currently an API Premium user? Check out our Free Developer Trial or contact our accounts team for assistance.
2 Comments
[…] documentation or integrate using our WeatherBlox layouts and views. For developers, check out our Developer AQI Blog. If you have questions contact our Sales or Technical Support […]
[…] but also for everyone when air quality drops considerably. In May, we announced the addition of the Air Quality endpoints to the Aeris Weather API. Today, as we continue to expand our Air Quality API and datasets, we […]