---
title: RAQSAPI - Introduction to RAQSAPI
author: Clinton Mccrowey physical scientist - US EPA
output:
  rmarkdown::html_vignette: default
vignette: >
  %\VignetteIndexEntry{RAQSAPI - Introduction to RAQSAPI}
  %\VignetteEncoding{UTF-8}
  %\VignetteDepends{knitr}
  %\VignetteDepends{rmarkdown}
  %\VignetteEngine{knitr::rmarkdown}
bibliography: AQSAPI.bib
csl: acs-nano.csl
---

| <span style="color:red"> Warning: US EPA's AQS Data Mart API V2 is currently \
in beta phase of development, the API interface has not been finalized. \
This means that certain functionality of the API may change or be removed \
without notice. As a result, this package is also currently marked as beta and \
may also change to reflect any changes made to the Data Mart API or in respect \
to improvements in the design, functionality, quality and documentation of \
this package. The authors assume no liability for any problems that may occur \
as a result of using this package, the Data Mart service, any software, \
service, hardware, or user accounts that may utilize this package. </span> |
| -- |

# Introduction

The `RAQSAPI` package for the R programming environment allows a R programming
  environment to connect to and retrieve data from the United States
  Environmental Protection Agency's (US EPA) Air Quality System (AQS) Data Mart
  API v2 Air Quality System[@AQSDataMartWelcome]
  interface directly. This package enables the data user to omit legacy
  challenges including coercing data from a JSON object to a usable R object,
  retrieving multiple years of data, formatting API requests, retrieving
  results, handling credentials, requesting multiple pollutant data and rate
  limiting data requests. All the basic functionality of the API have been
  implemented that are available from the AQS API Data Mart server. The library
  connects to AQS Data Mart API via Secure Hypertext Transfer Protocol (HTTPS)
  so there is no need to install external ODBC drivers, configure ODBC
  connections or deal with the security vulnerabilities associated with them.
  Most API functions have a parameter, return_header, which by default is set to
  FALSE. If the user decides to set return_header to TRUE, then that function
  will return a R AQS_DATAMART_APIv2 S3 object which is a two item named list.  
  The first item, (\$Header) in the AQS_DATAMART_APIv2 object is a
  tibble[@package:tibble] 
  which contains the header information. The Header contains status
  information regarding the request (success/fail), any applicable error
  messages returned from the API, if any exist, the URL used in the request, a
  date and time stamp noting when request was received and other useful
  information. The second item of the AQS_DATAMART_APIv2 object (\$Data) is a
  tibble which contains the actual data being requested. For functions with the
  return_header option set to FALSE (default) a simple tibble is returned with
  just the $Data portion of the request. After each call to the API a five
  second stall is invoked to help prevent overloading the Data Mart API server
  and to serve as a simple rate limit.  ^[RAQSAPI's rate limit does not
  guarantee that the user will not go over the rate limit and does not guarantee
  that API calls do not overload the AQS Data Mart system, each user should
  monitor their requests independently.]