In jpkeller/aqsr: Interface to EPA AQS

knitr::opts_chunk$set(echo = TRUE, message = FALSE, warning = FALSE)

library(aqsr)

aqsr

R Package for Accessing EPA AQS data

This package provides an R interface for the EPA Air Quality System (AQS) API. Information about the API, including Terms of Service, is available at https://aqs.epa.gov/aqsweb/documents/data_api.html.

Installation

The aqsr package can be installed by running

devtools::install_github("jpkeller/aqsr")

Creating a User Key

The AQS API requires an email address and key for all queries. The key is not used for authentication (as in a password), but it is used for identification. Sign-up using the aqs_signup() function, and your key phrase will be emailed.

Once an email address and key are registered, assign them to a list in the working environment using create_user(). For example:

myuser <- create_user(email="myemail@mydomain",
                    key="mykeyhere")

Alternatively, the email address and key can be stored as the environment variables AQS_EMAIL and AQS_KEY, respectively, to avoid directly storing the values in code that might be part of a public repository. To do this, add the lines

AQS_EMAIL="myemail@mydomain"
AQS_KEY="mykeyhere"

to the .Renviron file in your home directory. Calling create_user() without any argument will then read from these values:

myuser <- create_user() # Use stored credentials for user

Care should still be taken to avoid storing the resulting object in a public repository.

All functions for requesting data from the API require that the list generated by create_user() be provided in the aqs_user argument.

Available Services

A full list of services provided by the AQS API can be accessed by calling list_services(). These services include sampleData, signup, list, and metaData, among others. The endpoints for each service are listed in list_endpoints(), and the variables required for each endpoint are listed in list_required_vars(). For example:

# List all services
list_services()
# List endpoints for "dailyData" service
list_endpoints(service="dailyData") 
# List variables needed for obtaining data using the "byCounty" endpoint
list_required_vars(endpoint="byCounty")

Available Data

Information on parameter codes and required input for defining data requests can be obtained from the API using aqs_list(), aqs_list_parameters(), and the related functions.

For example, to list the available parameter classes (groups of parameters), use the function

> aqs_list_classes(aqs_user=myuser)
                      code                                                     value_represented
2              AIRNOW MAPS   The parameters represented on AirNow maps (88101, 88502, and 44201)
27                     ALL                                       Select all Parameters Available
3           AQI POLLUTANTS                                   Pollutants that have an AQI Defined
4                CORE_HAPS                                            Urban Air Toxic Pollutants
5                 CRITERIA                                                   Criteria Pollutants
6                 CSN DART       List of CSN speciation parameters to populate the STI DART tool
7                 FORECAST                        Parameters routinely extracted by AirNow (STI)
8                     HAPS                                              Hazardous Air Pollutants
9           IMPROVE CARBON                                             IMPROVE Carbon Parameters
10      IMPROVE_SPECIATION                  PM2.5 Speciated Parameters Measured at IMPROVE sites
11                     MET                                             Meteorological Parameters
12         NATTS CORE HAPS             The core list of toxics of interest to the NATTS program.
13          NATTS REQUIRED Required compounds to be collected in the National Air Toxics Network
14                    PAMS                            Photochemical Assessment Monitoring System
15                PAMS_VOC               Volatile Organic Compound subset of the PAMS Parameters
16               PM COARSE                                     PM between 2.5 and 10 micrometers
17         PM10 SPECIATION                                             PM10 Speciated Parameters
18       PM2.5 CONT NONREF                                PM2.5 Continuous, Nonreference Methods
19           PM2.5 MASS/QA                                          PM2.5 Mass and QA Parameters
20       SCHOOL AIR TOXICS                                  School Air Toxics Program Parameters
21              SPECIATION                                            PM2.5 Speciated Parameters
22       SPECIATION CARBON                                    PM2.5 Speciation Carbon Parameters
23 SPECIATION CATION/ANION                              PM2.5 Speciation Cation/Anion Parameters
24       SPECIATION METALS                                     PM2.5 Speciation Metal Parameters
25          UATMP CARBONYL                         Urban Air Toxics Monitoring Program Carbonyls
26               UATMP VOC                              Urban Air Toxics Monitoring Program VOCs

To list the codes for the criteria air pollutants, use:

aqs_list_parameters(myuser, pc="CRITERIA")

Requesting Data

The primary functions for requesting measurements stored in the AQS database are aqs_annualData(), aqs_dailyData(), and aqs_sampleData(). Variations of each function exist for queries targeting a specific criteria, e.g. aqs_annualData_byState(). The underlying function that queries the API is aqs_get(), which can be called directly if desired.

Example Data Requests

Example 1

Requesting all PM2.5 measurements (parameter code 88101) for California (state code 06) from January 1, 2017 through January 4, 2017:

# Sample Data -- By State
s1 <- aqs_sampleData(aqs_user=myuser,
                     endpoint="byState",
                     state="06",
                     bdate="20170101",
                     edate="20170104",
                     param="88101")
dim(s1)
s1[1:2,]

Example 2

Requesting all NO2 measurements (parameter code 42602) for King County, WA from January 1, 2017 through January 4, 2017. First, we find out the state code for Washington:

state_fips <- aqs_list_states(myuser)
tail(state_fips, 10)

From this list, we get that the state code for Washington is "53". Now we find the code for King County:

wa_counties <- aqs_list_counties(myuser, state="53")
head(wa_counties)

From these results we see the King County code is "033".We now request the sample:

s2 <- aqs_sampleData(aqs_user=myuser,
                     endpoint="byCounty",
                     state="53",
                     county="033",
                     bdate="20170101",
                     edate="20170110",
                     param="42602")
s2[1:2,]

Example 3

We could also request data for site 530330030 in King County:

s3 <- aqs_sampleData(aqs_user=myuser,
                     endpoint="bySite",
                     state="53",
                     county="033",
                     site="0030",
                     bdate="20170201",
                     edate="20170210",
                     param="42602")
s3[1:2,]

Example 4

Data can be requested by metropolitan area, specifically Core-based Statistical Area (CBSA).

aqs_list(myuser, endpoint="cbsas")

From this output (hidden here for brevity), we see that the CBSA code for the greater Atlanta, GA region is 12060. We can now request all PM2.5 observations from March 1, 2017 in the Atlanta-Sandy Springs-Roswell CBSA:

s4 <- aqs_sampleData(aqs_user=myuser,
                     endpoint="byCBSA",
                     cbsa="12060",
                     bdate="20170301",
                     edate="20170301",
                     param="88101")
s4[1:2,]