Option 1: Installing the stable version from CRAN

install.packages(pkgs="RAQSAPI",dependencies =TRUE )

Option 2: Installing the development version of RAQSAPI

To install the development version ofRAQSAPI, first ifnot already installed, install theremotes package and itsdependencies. Then run the following in a R environment.

remotes::install_github(repo ="USEPA/raqsapi",dependencies =TRUE,upgrade ="always",build =TRUE,#optional, set TRUE if the manual is desired,#requires pandocbuild_manual =FALSE,build_vignettes =TRUE                        )

Load RAQSAPI

after successfully installing theRAQSAPI package, loadtheRAQSAPI library:

library(RAQSAPI)

Sign up and setting up user credentials with the RAQSAPIlibrary

If you have not already done so you will need to sign up with AQSData Mart using aqs_sign_up function,² this function takesone input, “email”, which is a R character object, that represents theemail address that you want to use as a user credential to the AQS DataMart service. After a successful call to aqs_sign_up an email messagewill be sent to the email address provided with a new Data Mart keywhich will be used as a credential key to access the Data Mart API. Theaqs_sign_up function can also be used to regenerate a new key for anexisting user, to generate a new key simply call the aqs_sign_upfunction with the parameter “email” set to an existing account. A newkey will be e-mailed to the account given.

The credentials used to access the Data Mart API service are storedin a R environment variable that needs to be set every time theRAQSAPI library is attached or the key is changed. Withoutvalid credentials, the Data Mart server will reject any request sent toit. The key used with Data Mart is a key and is not a password, so theRAQSAPI library does not treat the key as a password; this means thatthe key is stored in plain text and there are no attempts to encryptData Mart credentials as would be done for a username and passwordcombination. The key that is supplied to use with Data Mart is notintended for authentication but only account monitoring. Each timeRAQSAPI is loaded and before using any of it’s functions use theaqs_credentials³ function to enter in the user credentialsso that RAQSAPI can access the AQS Data Mart server.

(suggested) Use thekeyring package to managecredentials

It is highly suggested that users use a keyring manager to store andretrieve their credentials while using RAQSAPI. One such credentialmanager is provided by thekeyring package⁴. TheKeyring package uses the credential manager available formost popular operating systems to store and manage user credentials.This will help avoid hard coding credential information into Rscripts.

To use thekeyring package withRAQSAPIfirst installkeyring:

install.package("keyring")

Ensure that your system is supported by thekeyringpackage before proceeding.

  keyring::has_keyring_support()

then set the keyring used to access AQS Data Mart (make sure toreplace the text in the angled brackets with your specific userinformation):

library("keyring")  keyring::key_set(service ="AQSDatamart",username ="\<user email account\>")

a popup window will appear for the user to input their keyringinformation. Enter the AQS Data mart credential key associated with theAQS user name provided, then hit enter. Now the AQS Data Mart usercredential is set usingkeyring.

To retrieve the keyring to use withRAQSAPI load thekeyring package and use the function key_get to return theuser credential to RAQSAPI:

library(RAQSAPI)library(keyring)  datamartAPI_user<- \<user email account\>  server<-"AQSDatamart"

then pass these variables to the aqs_credentials function when usingRAQSAPI:

aqs_credentials(username = datamartAPI_user,key =key_get(service = server,username = datamartAPI_user                                )                  )

To change the keyring stored with thekeyring packagerepeat the steps above to call the keyring::key_set function again withthe new credential information.

To retrieve a list of all keyrings managed with thekeyring package use the function: >keyring::key_list()

Refer the thekeyringpackage documentation for an in depth explanation on using thekeyring package.

Usage tips and precautions

This section contains suggestions for completing certain data relatedtasks.

• Determine if or how much data exists for a time-parameter-geographycombination:
  • Retrieve data using the annualdata service.
  • If no records are returned, we do not have the data.
  • If records are returned, use the observation count to determine thetemporal and geographic distribution of the data.
• Monthly averages:
  • AQS does not routinely calculate monthly aggregate statistics.
  • If you need these, you must calculate them yourself.
  • These can be calculated from the sample data or the daily datawithout loss of fidelity.
• Determine a single value for a site with collocated monitors:
  • Many sites will have collocated monitors - monitors collecting thesame parameter at the same time.
  • The API currently provides only monitor level values. (site-levelvalues will be added in the future.)
  • For some criteria pollutants (PM2.5, ozone, lead, and NO2), theregulations define procedures for defining a single site-levelvalue.
  • For other pollutants, determining a single site-level value is leftto the investigator.
• Please adhere to the following when using the AQS Data MartAPI:
  • Limit the size of queries. The AQS Data Martcontains billions of values and you may request more than you intend. Ifyou are unsure of the amount of data, start small and work your way up.Please limit queries to 1,000,000 rows of data each. You can use the“observation count” field on the annualdata service to determine howmuch data exists for a time-parameter-geography combination.
    
  • Limit the frequency of queries. The AQS Data Martcan process a limited load. Please wait for one request to completebefore submitting another and do not make more than 10 requests perminute.
  • Be advised that RAQSAPI is capable of retrieving results formultiple pollutants, this can result in the amount of data beingreturned being multiplied by the number of pollutants beingrequested.
  • Be advised that the AQS Data Mart API limits certain data requeststo one year of data at a time with the exception of the Monitor service.In order to retrieve multiple years of data for these functions theRAQSAPI library conveniently sends multiple API requests to the DataMart API server, one request for each year, this can result in theamount of data being returned being multiplied by the number of years ofdata being requested.

The AQS Data Mart administrators may disable accounts withoutnotice for failure to adhere to these terms (Though they will contactthe offending user via the email address provided)

Sign up and credentials

The functions included in this family of functions are:

aqs_credentials  aqs_sign_up

These functions are used to sign up with Data Mart and to storecredential information to use with RAQSAPI. The RAQSAPI::aqs_signupfunction takes one parameter:

• email:

The RAQSAPI::aqs_credentials function takes two parameters:

• username:
• key:

Data Mart API metadata functions

aqs_fields_by_service  aqs_isavailable  aqs_knownissues

These functions return the status of Data Mart API or metadataassociated with it.

The RAQSAPI::aqs_isavailable function takes no parameters and returnsa table which details the status of the AQS API.

The RAQSAPI::aqs_fields_by_service function takes one parameter,service, which is a R character object which represents the servicesprovided by the AQS API. For a list of available services seeAirQuality System (AQS) API - Services Overview

The RAQSAPI::aqs_knownissues function takes no parameters and Returnsa table of any known issues with system functionality or the data. Theseare usually issues that have been identified internally and will requiresome time to correct in Data Mart or the API. This function implements adirect API call to Data Mart and returns data directly from the API.Issues returned via this function do not include any issues from theRAQSAPI R package.

The RAQSAPI::aqs_revisionhistory function is used to query Data Martfor the change history to the API.

Data Mart API list functions

aqs_cbsas  aqs_classes  aqs_counties_by_state  aqs_mas  aqs_pqaos  aqs_sites_by_county  aqs_states

List functions return the API options or groupings that can be usedin conjunction with other API calls. By default each function in thiscategory returns results as a tibble. If return_header parameter is setto TRUE a AQSAPI_v2 object is returned instead.

RAQSAPI::aqs_cbsas returns a table of all available Core BasedStatistical Areas (cbsas) and their respective cbsa codes.

RAQSAPI::aqs_states takes no arguments and returns a table of theavailable states and their respective state FIPS codes.

RAQSAPI::aqs_sampledurations takes no arguments and returns a tableof the available sample duration code used to construct otherrequests.

RAQSAPI::aqs_classes takes no arguments and returns a table ofparameter classes (groups of parameters, i.e. “criteria” or “all”).

RAQSAPI::aqs_counties_by_state takes one parameter, stateFIPS, whichis a two digit state FIPS code for the state being requested representedas a R character object and returns a table of counties and theirrespective FIPS code for the state requested. Use RAQSAPI::aqs_states toreceive a table of valid state FIPS codes.

RAQSAPI::aqs_sites_by_county takes two parameters, stateFIPS, whichis a two digit state FIPS code for the state being requested andcounty_code which is a three digit county FIPS code for the county beingrequested, both stateFIPS and county_code should be encoded as a Rcharacter object This function returns a table of all air monitoringsites with the requested state and county FIPS code combination.

RAQSAPI::aqs_pqaos takes no parameters and returns anAQS_DATAMART_APIv2 S3 object containing a table of primary qualityassurance organizations (pqaos).

RAQSAPI::aqs_mas takes no parameters and returns anAQS_DATAMART_APIv2 S3 object containing a table of monitoring agencies(MA).

Data Mart aggregate functions

These functions retrieve aggregated data from the Data Mart API andare grouped by how each function aggregates the data. There are 5different families of related aggregate functions. These families arearranged by how the Data Mart API groups the returned data, _by_site,_by_county, _by_state,by(_by_box) andby (_by_cbsa).Within each family of aggregated data functions there are functions thatcall on the 10 different services that the Data Mart API provides. AllAggregate functions return a tibble by default. If the return_Headerparameter is set to TRUE an AQS_DATAMART_APIv2 S3 object is returnedinstead.

• These fourteen services are:

1. Monitors: Returns operational information aboutthe samplers (monitors) used to collect the data. Includes identifyinginformation, operational dates, operating organizations, etc. Functionsusing this service contain*monitors_by_* in the functionname.

2. Sample Data: Returns sample data - the most finegrain data reported to EPA. Usually hourly, sometimes 5-minute, 12-hour,etc. This service is available in several geographic selections based ongeography: site, county, state, cbsa (core based statistical area, agrouping of counties), or by latitude/longitude bounding box. Functionsusing this service contain*sampledata_by_* in the functionname. All Sample Data functions accept two additional, optionalparameters; cbdate and cedate:

   • cbdate: a R date object which represents a “beginning date of lastchange” that indicates when the data was last updated. cbdate is used tofilter data based on the change date. Only data that changed on or afterthis date will be returned. This is an optional variable which defaultsto NA_Date_.
   • cedate: a R date object which represents an “end date of lastchange” that indicates when the data was last updated. cedate is used tofilter data based on the change date. Only data that changed on orbefore this date will be returned. This is an optional variable whichdefaults to NA_Date_.
   • duration: an optional R character string that represents theparameter duration code that limits returned data to a specific sampleduration. The default value of NA_character_ results in no filteringbased on duration code. Valid durations include actual sample durationsand not calculated durations such as 8 hour CO or\(O_3\) rolling averages, 3/6 day PM averagesor Pb 3 month rolling averages. Refer to [aqs_sampledurations()] for alist of all available duration codes.

3. Daily Summary Data: Returns data summarized atthe daily level. All daily summaries are calculated on midnight tomidnight basis in local time. Variables returned include date, meanvalue, maximum value, etc. Functions using this service contain*dailysummary_by_* in the function name. All Daily Summary Datafunctions accept two additional parameters; cbdate and cedate:

   • cbdate: a R date object which represents a “beginning date of lastchange” that indicates when the data was last updated. cbdate is used tofilter data based on the change date. Only data that changed on or afterthis date will be returned. This is an optional variable which defaultsto NA_Date_.
   • cedate: a R date object which represents an “end date of lastchange” that indicates when the data was last updated. cedate is used tofilter data based on the change date. Only data that changed on orbefore this date will be returned. This is an optional variable whichdefaults to NA_Date_.

4. Annual Summary Data: Returns data summarized atthe yearly level. Variables include mean value, maxima, percentiles,etc. Functions using this service contain*annualdata_by_* inthe function name. All Annual Summary Data functions accept twoadditional parameters; cbdate and cedate:

   • cbdate: a R date object which represents a “beginning date of lastchange” that indicates when the data was last updated. cbdate is used tofilter data based on the change date. Only data that changed on or afterthis date will be returned. This is an optional variable which defaultsto NA_Date_.
   • cedate: a R date object which represents an “end date of lastchange” that indicates when the data was last updated. cedate is used tofilter data based on the change date. Only data that changed on orbefore this date will be returned. This is an optional variable whichdefaults to NA_Date_.

5. Quarterly Summary Data: Returns data summarizedat the quarterly level. Variables include mean value, maxima,percentiles, etc. Functions using this service contain*quarterlydata_by_* in the function name. All Annual SummaryData functions accept two additional parameters; cbdate and cedate:

   • cbdate: a R date object which represents a “beginning date of lastchange” that indicates when the data was last updated. cbdate is used tofilter data based on the change date. Only data that changed on or afterthis date will be returned. This is an optional variable which defaultsto NA_Date_.
   • cedate: a R date object which represents an “end date of lastchange” that indicates when the data was last updated. cedate is used tofilter data based on the change date. Only data that changed on orbefore this date will be returned. This is an optional variable whichdefaults to NA_Date_.

6. Quality Assurance - Blanks Data: Qualityassurance data - blanks samples. Blanks are unexposed sample collectiondevices (e.g., filters) that are transported with the exposed sampledevices to assess if contamination is occurring during the transport orhandling of the samples. Functions using this service contain*qa_blanks_by_* in the function name.
   

7. Quality Assurance - Collocated Assessments:Quality assurance data - collocated assessments. Collocated assessmentsare pairs of samples collected by different samplers at the same timeand place. (These are “operational” samplers, assessments withindependently calibrated samplers are called “audits”.). Functions usingthis service contain*qa_collocated_assessments_by_* in thefunction name.

8. Quality Assurance - Flow Rate Verifications:Quality assurance data - flow rate verifications. Several times peryear, each PM monitor must have it’s (fixed) flow rate verified by anoperator taking a measurement of the flow rate. Functions using thisservice contain*qa_flowrateverification_by_* in the functionname.

9. Quality Assurance - Flow Rate Audits: Qualityassurance data - flow rate audits. At least twice year, each PM monitormust have it’s flow rate measurement audited by an expert using adifferent method than is used for flow rate verifications. Functionsusing this service contain*qa_flowrateaudit_by_* in thefunction name.

10. Quality Assurance - One Point Quality Control RawData: Quality assurance data - one point quality control checkraw data. At least every two weeks, certain gaseous monitors must bechallenged with a known concentration to determine monitor performance.Functions using this service contain*qa_one_point_qc_by_* inthe function name.
    

11. Quality Assurance - pep Audits: Qualityassurance data - performance evaluation program (pep) audits. pep auditsare independent assessments used to estimate total measurement systembias with a primary quality assurance organization. Functions using thisservice contain*qa_pep_audit_by_* in the functionname.

12. Transaction Sample - AQS Submission data in transactionformat (RD): Transaction sample data - The raw transactionsample data uploaded to AQS by the agency responsible for datasubmissions in RD format. Functions using this service contain*transactionsample_by_* in the function name. Transactionsample data is only available aggregated by site, county, state ormonitoring agency.

13. Quality Assurance - Annual PerformanceEvaluations: Quality assurance data - Annual performanceevaluations. A performance evaluation must be conducted on each primarymonitor once per year. The percent differences between known andmeasured concentrations at several levels are used to assess the qualityof the monitoring data. Functions using this service contain*aqs_qa_annualperformanceeval_by_* in the function name. Annualperformance in transaction format are only available aggregated by site,county, state, monitoring agency, and primary quality assuranceorganization. Annual performance evaluations are only availableaggregated by site, county, state, monitoring agency, and primaryquality assurance organization.

14. Quality Assurance - Annual performance Evaluations intransaction
    format (RD): Quality assurance data - The rawtransaction annual performance evaluations data in RD format. Functionsusing this service contain*aqs_qa_annualperformanceevaltransaction_by_* in the functionname. Annual performance evaluations in transaction format are onlyavailable aggregated by site, county, state, monitoring agency, andprimary quality assurance organization.

aqs_annualsummary_by_site  aqs_dailysummary_by_site  aqs_monitors_by_site  aqs_qa_annualperformanceeval_by_site  aqs_qa_annualperformanceevaltransaction_by_site  aqs_qa_blanks_by_site  aqs_qa_collocated_assessments_by_site  aqs_qa_flowrateaudit_by_site  aqs_qa_flowrateverification_by_site  aqs_qa_one_point_qc_by_site  aqs_qa_pep_audit_by_site  aqs_quarterlysummary_by_site  aqs_sampledata_by_site  aqs_transactionsample_by_site

aqs_annualsummary_by_county  aqs_dailysummary_by_county  aqs_monitors_by_county  aqs_qa_annualperformanceeeval_by_county  aqs_qa_annualperformanceevaltransaction_by_county  aqs_qa_blanks_by_county  aqs_qa_collocated_assessments_by_county  aqs_qa_flowrateaudit_by_county  aqs_qa_flowrateverification_by_county  aqs_qa_one_point_qc_by_county  aqs_qa_pep_audit_by_county  aqs_quarterlysummary_by_county  aqs_sampledata_by_county  aqs_sites_by_county  aqs_transactionsample_by_county

aqs_annualsummary_by_state  aqs_counties_by_state  aqs_dailysummary_by_state  aqs_monitors_by_state  aqs_qa_annualperformanceeval_by_state  aqs_qa_annualperformanceevaltransaction_by_state  aqs_qa_blanks_by_state  aqs_qa_collocated_assessments_by_state  aqs_qa_flowrateaudit_by_state  aqs_qa_flowrateverification_by_state  aqs_qa_one_point_qc_by_state  aqs_qa_pep_audit_by_state  aqs_quarterlysummary_by_state  aqs_sampledata_by_state  aqs_transactionsample_by_state

aqs_qa_annualperformanceeval_by_MA  aqs_qa_annualperformanceevaltransaction_by_MA  aqs_qa_blanks_by_MA  aqs_qa_collocated_assessments_by_MA  aqs_qa_flowrateaudit_by_MA  aqs_qa_flowrateverification_by_MA  aqs_qa_one_point_qc_by_MA  aqs_qa_pep_audit_by_MA  aqs_transactionsample_by_MA

aqs_annualsummary_by_cbsa  aqs_dailysummary_by_cbsa  aqs_monitors_by_cbsa  aqs_sampledata_by_cbsa

aqs_qa_annualperformanceeval_by_pqao  aqs_qa_annualperformanceevaltransaction_by_pqao  aqs_qa_blanks_by_pqao  aqs_qa_collocated_assessments_by_pqao  aqs_qa_flowrateaudit_by_pqao  aqs_qa_flowrateverification_by_pqao  aqs_qa_one_point_qc_by_pqao  aqs_qa_pep_audit_by_pqao  aqs_quarterlysummary_by_pqao

aqs_annualsummary_by_box  aqs_dailysummary_by_box  aqs_monitors_by_box  aqs_quarterlysummary_by_box  aqs_sampledata_by_box

aqs_removeheader

pyaqsapi - a port of RAQSAPI to the python 3 programmingenvironment

For users that feel more comfortable working within a python 3environment,pyaqsapi⁴, a port of RAQSAPI to the python 3language has been released. Both projects aim to maintain feature paritywith the other and there are no inherent advantages to using eitherproject over the other, except for the ability of working within theprogramming language environment of choice. The API of both packages arevery structured similarly, both packages export the same data, use thesame credentials and data source to retrieve data.