A simple PHP Wrapper for the World Air Quality Index API
The World Air Quality Index project is an initiative to map the current and real-time air quality around the globe. The Air Quality indexes are based on PM2.5, PM10, Ozone, NO2, SO2 and CO hourly measurements provided by various monitoring stations in the world.
This packages makes it easy to retrieve the Air Quality Index for your area and is based on the a real-time Air Quality data feed (API) of the WAQI project.
Note: To make use of this package (and the underlying AQI API) an access token is required. You can acquire your token here: https://aqicn.org/data-platform/token.
You need PHP >= 7.2.0 to use 'azuyalabs/waqi'.
You can pull in this package via composer:
$ composer require azuyalabs/waqi
Start with including the Composer autoload file in your project:
<?php require 'vendor/autoload.php';
Using your AQI access token, create an instance of the WAQI object:
use Azuyalabs\WAQI\WAQI; $waqi = new WAQI(<your access token>);
Next, use the
getObservationByStation method with the desired city or monitoring station name (e.g.
'new york'). This will obtain the latest air quality observations:
If all goes well, use the various API methods to get details about the retrieved Air Quality Index of the chosen city or monitoring station.
To get the AQI (Air Quality Index), use the method
This returns an array structure containing the Air Quality Index measured at this monitoring station at the time of measurement. It contains 4 elements:
- 'aqi': the AQI level (which is defined by the monitoring stations' dominant pollution type)
- 'pollution_level': a narrative describing the air pollution level
- 'health_implications': a narrative describing the health implications associated with the measured pollution level
- 'cautionary_statement': a cautionary statement associated with the measured pollution level (only for PM2.5)
Example output (for 'New York'):
- 'aqi': 15 - 'pollution_level': Good - 'health_implications': Air quality is considered satisfactory, and air pollution poses little or no risk. - 'cautionary_statement': None
In addition to the general Air Quality Information, specific pollutant level information is available as well. Be aware that not every monitoring station captures all pollutant types, so some of these API functions may return 'null'.
The following API functions are available to get specific pollutant level information:
getCO(): returns the carbon monoxide (CO) level measured at the monitoring station at the time of measurement.
getNO2(): returns the nitrogen dioxide (NO2) level measured at the monitoring station at the time of measurement.
getO3(): returns the ozone (O3) level measured at the monitoring station at the time of measurement.
getSO2(): returns the sulfur dioxide (SO2) level measured at the monitoring station at the time of measurement.
getPM10(): returns the level of particulate matter 10 micrometers or less (PM10), measured at this monitoring station at the time of measurement.
getPM25(): returns the level of particulate matter 2.5 micrometers or less (PM2.5), measured at this monitoring station at the time of measurement.
Information about the monitoring station can be obtained through two API methods.
First, using the API method
getMonitoringStation(), will return information about the given monitoring station:
- 'id': the unique ID for this monitoring station
- 'name': the name (or description) of this monitoring station
- 'coordinates': the geographical coordinates of this monitoring station (array of 'longitude' and 'latitude')
- 'url': the URL of this monitoring station
Secondly, the API method
getAttributions() will return a list of EPA attributions for this monitoring station.
Other API methods that provide additional information, are:
getMeasurementTime(): returns the date/time the last measurement was taken. (as a DateTime object).
getHumidity(): returns the humidity (in %) measured at this monitoring station at the time of measurement.
getTemperature(): returns the temperature (in degrees Celsius) measured at this monitoring station at the time of measurement.
getPressure(): returns the barometric pressure (in millibars) measured at this monitoring station at the time of measurement.
getPrimaryPollutant(): returns the name of the primary pollutant at this monitoring station at the time of measurement (e.g. 'pm25').
Please see CHANGELOG for more information what has changed.
This package comes with a PHPUnit test suite. To run the tests, run the following command from the project directory:
$ composer test
or alternatively run with:
Contributions are encouraged and welcome; I am always happy to get feedback or pull requests on Github :) Create Github Issues for bugs and new features and comment on the ones you are interested in.
If you enjoy what I am making, an extra cup of coffee is very much appreciated :). Your support helps me to put more time into Open-Source Software projects like this.
This package is open-sourced software licensed under the MIT License. Please see LICENSE for more information.