Introduction

This R package is aimed at accessing the openaq API. OpenAQ is a community of scientists, software developers, and lovers of open environmental data who are building an open, real-time database that provides programmatic and historical access to air quality data. See their website at https://openaq.org/ and see the API documentation at https://docs.openaq.org/. The package contains 5 functions that correspond to the 5 different types of query offered by the openaq API: cities, countries, latest, locations and measurements. The package uses the dplyr package: all output tables are data.frame (dplyr “tbl_df”) objects, that can be further processed and analysed.

What data can you get?

Via the API since November 2017 the API only provides access to the latest 90 days of OpenAQ data. The whole OpenAQ data can be accessed via Amazon S3. See this announcement. You can interact with Amazon S3 using the aws.s3 package and the maintainer of ropenaq plans to write tutorials about how to access OpenAQ data and will also keep the documentation of ropenaq up-to-date regarding data access changes.

Finding measurements availability

Three functions of the package allow to get lists of available information. Measurements are obtained from locations that are in cities that are in countries.

The aq_countries function

The aq_countries function allows to see for which countries information is available within the platform. It is the easiest function because it does not have any argument. The code for each country is its ISO 3166-1 alpha-2 code.

library("ropenaq")
countries_table <- aq_countries()
library("knitr")
kable(countries_table)
code count locations cities name
AD 130644 3 2 Andorra
AE 92206 4 3 United Arab Emirates
AF 12174 2 2 Afghanistan
AG 1 1 1 Antigua and Barbuda
AR 14976 4 1 Argentina
AT 2600089 541 25 Austria
AU 7481982 177 60 Australia
BA 1140165 22 10 Bosnia and Herzegovina
BD 37009 2 1 Bangladesh
BE 1835144 198 14 Belgium
BG 132593 25 17 Bulgaria
BH 50667 1 1 Bahrain
BK 5722 1 1 NA
BM 8379 1 1 Bermuda
BR 304267 61 31 Brazil
CA 6871188 219 12 Canada
CE 7875 1 1 NA
CH 1754919 30 15 Switzerland
CI 3724 1 1 Côte d’Ivoire
CL 8756962 245 166 Chile
CN 122386021 1747 388 China
CO 851410 34 12 Colombia
CR 6263 1 1 Costa Rica
CS 5404 2 1 NA
CW 29402 1 1 Curaçao
CY 19009 3 2 Cyprus
CZ 6702709 200 15 Czech Republic
DE 12291392 1086 36 Germany
DK 629754 25 7 Denmark
DZ 10268 1 1 Algeria
EE 67784 9 6 Estonia
ES 24181846 1238 115 Spain
ET 67746 3 2 Ethiopia
FI 2213353 120 35 Finland
FR 28094458 1504 135 France
GB 11914940 162 112 United Kingdom
GH 4332 12 1 Ghana
GI 40842 6 2 Gibraltar
GN 2691 1 1 Guinea
GR 102395 19 5 Greece
GT 12810 2 2 Guatemala
HK 1727055 16 9 Hong Kong
HR 996026 50 17 Croatia
HU 2401218 50 14 Hungary
ID 90525 5 3 Indonesia
IE 567208 38 16 Ireland
IL 173130367 2041 14 Israel
IN 33351638 456 235 India
IQ 11361 1 1 Iraq
IS 98008 15 8 Iceland
IT 4866560 540 129 Italy
IZ 4301 1 1 NA
JO 11708 2 2 Jordan
KE 2842 2 1 Kenya
KG 17428 2 2 Kyrgyzstan
KU 5565 1 1 NA
KV 5709 1 1 NA
KW 26646 1 1 Kuwait
KZ 16533 2 2 Kazakhstan
LA 14235 2 2 Lao People’s Democratic Republic
LK 21258 1 1 Sri Lanka
LT 459102 17 8 Lithuania
LU 504997 7 3 Luxembourg
LV 218685 4 4 Latvia
MG 5244 1 1 Madagascar
MK 1385346 45 16 Macedonia, the Former Yugoslav Republic of
ML 2309 1 1 Mali
MM 13857 2 2 Myanmar
MN 2972005 44 25 Mongolia
MT 299259 4 4 Malta
MX 3590699 113 6 Mexico
NG 2541 1 1 Nigeria
NL 9533395 111 67 Netherlands
NO 3920652 88 37 Norway
NP 112597 6 2 Nepal
PE 784395 22 2 Peru
PH 958 1 1 Philippines
PK 61009 8 5 Pakistan
PL 9955337 236 173 Poland
PT 4007489 67 16 Portugal
RO 285148 123 42 Romania
RS 287785 6 4 Serbia
RU 186861 48 1 Russian Federation
SA 11289 3 2 Saudi Arabia
SE 375722 51 15 Sweden
SG 1275 1 1 Singapore
SI 166536 13 13 Slovenia
SK 2749306 38 8 Slovakia
SU 1400 1 1 NA
TH 5654593 64 29 Thailand
TI 5986 1 1 NA
TJ 6151 1 1 Tajikistan
TM 6248 1 1 Turkmenistan
TR 5640285 159 43 Turkey
TW 8460945 144 30 Taiwan
TX 5147 1 1 NA
UC 4 1 1 NA
UG 32294 2 2 Uganda
US 73562303 2302 799 United States
UZ 39478 2 2 Uzbekistan
VM 6813 2 1 NA
VN 77590 5 3 Viet Nam
XK 498600 9 8 Kosovo
ZA 239159 3 1 South Africa
attr(countries_table, "meta")
#> # A tibble: 1 x 6
#>   name       license   website                   page limit found
#>   <chr>      <chr>     <chr>                    <int> <int> <int>
#> 1 openaq-api CC BY 4.0 https://docs.openaq.org/     1 10000   104
attr(countries_table, "timestamp")
#> # A tibble: 1 x 1
#>   queriedAt          
#>   <dttm>             
#> 1 2020-08-29 21:22:13

The aq_cities function

Using the aq_cities functions one can get all cities for which information is available within the platform. For each city, one gets the number of locations and the count of measures for the city, the URL encoded string, and the country it is in.

cities_table <- aq_cities()
kable(head(cities_table))
country name city count locations cityURL
AD Escaldes-Engordany Escaldes-Engordany 120680 2 Escaldes-Engordany
AD unused unused 9964 1 unused
AE Abu Dhabi Abu Dhabi 38938 1 Abu+Dhabi
AE Dubai Dubai 32699 1 Dubai
AE N/A N/A 20569 2 N%2FA
AF Kabul Kabul 7159 1 Kabul

The optional country argument allows to do this for a given country instead of the whole world.

cities_tableIndia <- aq_cities(country="IN", limit = 10, page = 1)
kable(cities_tableIndia)
country name city count locations cityURL
IN 203 203 5841 1 203
IN Administrative Block Administrative Block 5874 1 Administrative+Block
IN Agra Agra 248848 2 Agra
IN Ahmedabad Ahmedabad 187737 1 Ahmedabad
IN Aizawl Aizawl 23004 1 Aizawl
IN Ajmer Ajmer 190596 1 Ajmer
IN Al Afiya General Hospital Al Afiya General Hospital 10363 1 Al+Afiya+General+Hospital
IN Alwar Alwar 479 1 Alwar
IN Alwar Alwar 205768 2 +Alwar
IN Alwar - Jaipur Rd Alwar - Jaipur Rd 11115 1 Alwar+-+Jaipur+Rd

If one inputs a country that is not in the platform (or misspells a code), then an error message is thrown.

#aq_cities(country="PANEM")

The aq_locations function

The aq_locations function has far more arguments than the first two functions. On can filter locations in a given country, city, location, for a given parameter (valid values are “pm25”, “pm10”, “so2”, “no2”, “o3”, “co” and “bc”), from a given date and/or up to a given date, for values between a minimum and a maximum, for a given circle outside a central point by the use of the latitude, longitude and radius arguments. In the output table one also gets URL encoded strings for the city and the location. Below are several examples.

Here we only look for locations with PM2.5 information in Chennai, India.

locations_chennai <- aq_locations(country = "IN", city = "Chennai", parameter = "pm25")
kable(locations_chennai)
id country city cities location locations sourceName sourceNames sourceType sourceTypes firstUpdated lastUpdated countsByMeasurement count longitude latitude pm25 pm10 no2 so2 o3 co bc cityURL locationURL
IN-44 IN Chennai Chennai Alandur Bus Depot Alandur Bus Depot CPCB CPCB government government 2016-03-22 00:45:00 2018-02-22 03:45:00 co , no2 , o3 , pm25 , so2 , 104 , 25860, 26208, 13224, 7301 72697 80.19151 12.99711 TRUE FALSE TRUE TRUE TRUE TRUE FALSE Chennai Alandur+Bus+Depot
IN-135 IN Chennai Chennai, MKN Rd Alandur Bus Depot, Chennai - CPCB Alandur Bus Depot, Chennai - CPCB caaqm data.gov.in, caaqm government government 2018-03-09 05:30:00 2020-07-22 12:45:00 co , no2 , o3 , pm25 , so2 , 34519, 34471, 34160, 34328, 34235 171713 80.10765 12.90992 TRUE FALSE TRUE TRUE TRUE TRUE FALSE Chennai Alandur+Bus+Depot%2C+Chennai+-+CPCB
IN-42 IN Chennai Chennai IIT IIT CPCB CPCB government government 2016-03-22 00:45:00 2018-02-22 03:45:00 co , no2 , o3 , pm25 , so2 , 31550, 31419, 29069, 16204, 9656 117898 80.23745 12.99251 TRUE FALSE TRUE TRUE TRUE TRUE FALSE Chennai IIT
IN-20 IN Chennai Chennai Manali, Chennai - CPCB Manali , Manali, Chennai - CPCB caaqm CPCB , data.gov.in, caaqm government government 2016-03-21 10:00:00 2020-07-22 12:30:00 co , no2 , pm25 , so2 , 62956, 63518, 51033, 42437 219944 80.26285 13.16454 TRUE FALSE TRUE TRUE FALSE TRUE FALSE Chennai Manali%2C+Chennai+-+CPCB
IN-258 IN Chennai Chennai Manali Village, Chennai - TNPCB Manali Village, Chennai - TNPCB caaqm caaqm government government 2019-07-19 06:00:00 2020-07-22 12:45:00 co , no2 , o3 , pm10 , pm25 , so2 , 15799, 15798, 15798, 15791, 15784, 15798 94768 80.25840 13.16620 TRUE TRUE TRUE TRUE TRUE TRUE FALSE Chennai Manali+Village%2C+Chennai+-+TNPCB
IN-239 IN Chennai Government School, Chennai Manali Village, Chennai - TNPCB Manali Village, Chennai - TNPCB caaqm caaqm government government 2019-06-18 23:00:00 2019-07-19 05:15:00 co , no2 , o3 , pm10, pm25, so2 , 184 , 184 , 158 , 164 , 165 , 184 1039 77.55243 11.25824 TRUE TRUE TRUE TRUE TRUE TRUE FALSE Chennai Manali+Village%2C+Chennai+-+TNPCB
IN-54 IN Chennai Chennai, India US Diplomatic Post: Chennai US Diplomatic Post: Chennai, Chennai StateAir_Chennai StateAir_Chennai, AirNow government government 2016-11-09 17:30:00 2020-07-22 12:30:00 pm25 , 35422 35422 80.27847 13.08784 TRUE FALSE FALSE FALSE FALSE FALSE FALSE Chennai US+Diplomatic+Post%3A+Chennai
IN-12 IN Chennai Chennai US Diplomatic Post: Chennai US Diplomatic Post: Chennai StateAir_Chennai StateAir_Chennai government government 2015-12-11 21:30:00 2016-11-09 16:30:00 pm25, 7835 7835 80.25193 13.05237 TRUE FALSE FALSE FALSE FALSE FALSE FALSE Chennai US+Diplomatic+Post%3A+Chennai
IN-90 IN Chennai Chennai , Sardar Patel Road Velachery Res. Area, Chennai - CPCB IIT, Chennai - CPCB , Velachery Res. Area, Chennai - CPCB caaqm data.gov.in, caaqm government government 2018-03-09 05:30:00 2020-07-22 12:45:00 co , no2 , o3 , pm25 , so2 , 29564, 29524, 29439, 29047, 29571 147145 80.23981 13.00522 TRUE FALSE TRUE TRUE TRUE TRUE FALSE Chennai Velachery+Res.+Area%2C+Chennai+-+CPCB

Getting measurements

Two functions allow to get data: aq_measurement and aq_latest. In both of them the arguments city and location needs to be given as URL encoded strings.

The aq_measurements function

The aq_measurements function has many arguments for getting a query specific to, say, a given parameter in a given location or for a given circle outside a central point by the use of the latitude, longitude and radius arguments. Below we get the PM2.5 measures for Delhi in India.

results_table <- aq_measurements(country = "IN", city = "Delhi", parameter = "pm25", limit = 10, page = 1)
kable(results_table)
location parameter value unit country city latitude longitude date.utc cityURL locationURL dateUTC dateLocal
CRRI Mathura Road, Delhi - IMD pm25 17.91 µg/m³ IN Delhi 28.55120 77.27357 2020-08-29T19:45:00Z Delhi CRRI+Mathura+Road%2C+Delhi+-+IMD 2020-08-29 19:45:00 2020-08-30
Aya Nagar, Delhi - IMD pm25 32.67 µg/m³ IN Delhi 28.47069 77.10994 2020-08-29T19:45:00Z Delhi Aya+Nagar%2C+Delhi+-+IMD 2020-08-29 19:45:00 2020-08-30
Lodhi Road, Delhi - IMD pm25 60.54 µg/m³ IN Delhi 28.59182 77.22731 2020-08-29T19:45:00Z Delhi Lodhi+Road%2C+Delhi+-+IMD 2020-08-29 19:45:00 2020-08-30
IGI Airport (T3), Delhi - IMD pm25 51.38 µg/m³ IN Delhi 28.56278 77.11801 2020-08-29T19:30:00Z Delhi IGI+Airport+%28T3%29%2C+Delhi+-+IMD 2020-08-29 19:30:00 2020-08-30
Shadipur, Delhi - CPCB pm25 36.15 µg/m³ IN Delhi 28.65148 77.14731 2020-08-29T19:30:00Z Delhi Shadipur%2C+Delhi+-+CPCB 2020-08-29 19:30:00 2020-08-30
IHBAS, Dilshad Garden, Delhi - CPCB pm25 19.30 µg/m³ IN Delhi 28.68117 77.30252 2020-08-29T19:30:00Z Delhi IHBAS%2C+Dilshad+Garden%2C+Delhi+-+CPCB 2020-08-29 19:30:00 2020-08-30
ITO, Delhi - CPCB pm25 38.00 µg/m³ IN Delhi 28.62862 77.24106 2020-08-29T19:30:00Z Delhi ITO%2C+Delhi+-+CPCB 2020-08-29 19:30:00 2020-08-30
Pusa, Delhi - IMD pm25 29.28 µg/m³ IN Delhi 28.63965 77.14626 2020-08-29T19:30:00Z Delhi Pusa%2C+Delhi+-+IMD 2020-08-29 19:30:00 2020-08-30
NSIT Dwarka, Delhi - CPCB pm25 20.86 µg/m³ IN Delhi 28.60909 77.03254 2020-08-29T19:30:00Z Delhi NSIT+Dwarka%2C+Delhi+-+CPCB 2020-08-29 19:30:00 2020-08-30
Punjabi Bagh, Delhi - DPCC pm25 44.00 µg/m³ IN Delhi 28.67404 77.13102 2020-08-29T19:15:00Z Delhi Punjabi+Bagh%2C+Delhi+-+DPCC 2020-08-29 19:15:00 2020-08-30

One could also get all possible parameters in the same table.

The aq_latest function

This function gives a table with all newest measures for the locations that are chosen by the arguments. If all arguments are NULL, it gives all the newest measures for all locations. Below are the latest values for Hyderabad at the time this vignette was compiled.

tableLatest <- aq_latest(country="IN", city="Hyderabad")
kable(head(tableLatest))
location city country parameter value lastUpdated unit sourceName averagingPeriod_value averagingPeriod_unit distance latitude longitude cityURL locationURL
Bollaram Industrial Area Hyderabad IN pm25 55.0 2017-02-17 05:15:00 µg/m³ CPCB 0.25 hours NA NA NA Hyderabad Bollaram+Industrial+Area
Bollaram Industrial Area Hyderabad IN pm10 137.0 2017-02-17 05:15:00 µg/m³ CPCB 0.25 hours NA NA NA Hyderabad Bollaram+Industrial+Area
Bollaram Industrial Area Hyderabad IN so2 16.8 2017-02-17 05:15:00 µg/m³ CPCB 0.25 hours NA NA NA Hyderabad Bollaram+Industrial+Area
Bollaram Industrial Area Hyderabad IN no2 16.2 2017-02-17 05:15:00 µg/m³ CPCB 0.25 hours NA NA NA Hyderabad Bollaram+Industrial+Area
Bollaram Industrial Area Hyderabad IN co 420.0 2017-02-17 05:15:00 µg/m³ CPCB 0.25 hours NA NA NA Hyderabad Bollaram+Industrial+Area
Bollaram Industrial Area, Hyderabad - TSPCB Hyderabad IN co 100.0 2020-08-29 07:45:00 µg/m³ caaqm 0.25 hours 6488054 17.54089 78.35853 Hyderabad Bollaram+Industrial+Area%2C+Hyderabad+-+TSPCB

Paging and limit

For all endpoints/functions, there a a limit and a page arguments, which indicate, respectively, how many results per page should be shown and which page should be queried. If you don’t enter the parameters by default all results for the query, or results for 100 pages which is the maximum, will be retrieved with async requests, but it might take a while nonetheless depending on the total number of results.

aq_measurements(city = "Delhi", parameter = "pm25")

Rate limiting

In October 2017 the API introduced a rate limit of 2,000 requests every 5 minutes. Please keep this in mind. In the case when the request receives a response status of 429 (too many requests), the package will wait 5 minutes.

Other packages of interest for getting air quality data

  • The rdefra package, also part of the rOpenSci project, allows to to interact with the UK AIR pollution database from DEFRA, including historical measures.

  • The openair package gives access to the same data as rdefra but relies on a local and compressed copy of the data on servers at King’s College (UK), periodically updated.

  • The usaqmindia package provides data from the US air quality monitoring program in India for Delhi, Mumbai, Chennai, Hyderabad and Kolkata from 2013. ## Meta

  • Please report any issues or bugs.
  • License: GPL
  • Get citation information for ropenaq in R doing citation(package = 'ropenaq')
  • Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.