pyaqsapi user documentation

EPA Disclaimer

Note

This software/application was developed by the U.S. Environmental Protection Agency (USEPA). No warranty expressed or implied is made regarding the accuracy or utility of the system, nor shall the act of distribution constitute any such warranty. The USEPA has relinquished control of the information and no longer has responsibility to protect the integrity, confidentiality or availability of the information. Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply their endorsement, recommendation or favoring by the USEPA. The USEPA seal and logo shall not be used in any manner to imply endorsement of any commercial product or activity by the USEPA or the United States Government.

AQS DataMart Disclaimer

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.

Introduction

The pyaqsapi package for the python 3 programming environment allows a python 3 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) interface directly. This package enables the data user to omit legacy challenges including coercing data from a JSON object to a usable python 3 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 Hypertext Transfer Protocol (HTTP) so there is no need to install external ODBC drivers, configure ODBC connections or deal with the security vulnerabilities associated with them. Most 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 python 3 AQSAPI_V2 object. An AQSAPI_V2 object has instance methods for retrieving the data requested, header information, and other metadata related to the API call. 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.

About the timeliness of AQS Data

EPA’s AQS Datamart API, the service that pyaqsapi retrieves data from, does not host real time (collected now/today) data. If real time data is needed, please use the AirNow API and direct all questions toward real time data there. pyaqsapi does not work with AirNow and cannot retrieve real time data. For more details see section 7.1 of the About AQS Data page .

Install pyaqsapi

To install pyaqsapi first clone the pyaqsapi repository.

git clone https://github.com/USEPA/pyaqsapi.git

Next, in the project’s root directory use pip to install the proper dependencies that are required to build and install pyaqsapi.

pip install -r requirements.txt

While still in the project’s root directory use setuptools to build and pip to install the package.

python -m build .
python -m pip install .

Load pyaqsapi

Like any other python package make sure that you are loading pyaqsapi in the same virtual environment where pyaqsapi was installed. Load pyaqsapi in the same any other python package is loaded.

import pyaqsapi as aqs

Using pyaqsapi

For those who are already familiar with using RAQSAPI then the pyaqsapi API should feel familiar with a few minor differences regarding how the data is returned.

By default data is returned as a pandas Data Frames . Exported functions from pyaqsapi have a parameter RETURN_HEADER, by default this parameter is False. When False functions simply return the requested data as a pandas Data Frame. If RETURN_HEADER is manually set to True a list of AQSAPI_V2 python 3 objects are returned. Use the get_data() class method to retrieve the data and the get_header() class method to retrieve header information.

Sign up and setting up user credentials with the pyaqsapi library

If you have not already done so you will need to sign up with AQS Data Mart using aqs_sign_up function, this function takes one input, “email,” which is a python 3 character object, that represents the email address that you want to use as a user credential to the AQS Data Mart service. After a successful call to aqs_sign_up an email message will be sent to the email address provided with a new Data Mart key which will be used as a credential key to access the Data Mart API. The aqs_sign_up function can also be used to regenerate a new key for an existing user, to generate a new key simply call the aqs_sign_up function with the parameter “email” set to an existing account. A new key will be e-mailed to the account given.

The credentials used to access the Data Mart API service are stored in as a python global variable that needs to be set every time the pyaqsapi module is loaded or the key is changed. Without valid credentials, the Data Mart server will reject any request sent to it. The key used with Data Mart is a key and is not a password, so the pyaqsapi package does not treat the key as a password; this means that the key is stored in plain text and there are no attempts to encrypt Data Mart credentials as would be done for a username and password combination. The key that is supplied to use with Data Mart is not intended for authentication but only account monitoring. Each time pyaqsapi is loaded and before using any of it’s functions use the aqs_credentials function to enter in the user credentials so that pyaqsapi can access the AQS Data Mart server.

Both pyaqsapi and RAQSAPI use the US Environmental Protection Agency’s Air Quality Service DataMart to retrieve data. The same credentials can be used for access to either project. Note however, that AQS and AQS DataMart are similar and related data sources, however the credentials used to access AQS are not the same as those used to access AQS DataMart.

Note

The credentials used to access AQS Data Mart API are not the same as the credentials used to access AQS. AQS users who do not have access to the AQS Data Mart will need to create new credentials. However, you may use the same credentials used in RAQSAPI in pyaqsapi since RAQSAPI ewes the the same AQS Data Mart API as pyaqsapi.

Usage tips and precautions

This section contains suggestions for completing certain data related tasks.

  • Determine if or how much data exists for a time-parameter-geography combination:

    • 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 the temporal 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 data without loss of fidelity.

  • Determine a single value for a site with collocated monitors:

    • Many sites will have collocated monitors - monitors collecting the same parameter at the same time.

    • The API currently provides only monitor level values. (site-level values will be added in the future.)

    • For some criteria pollutants (PM2.5, ozone, lead, and NO2), the regulations define procedures for defining a single site-level value.

    • For other pollutants, determining a single site-level value is left to the investigator.

  • Please adhere to the following when using the AQS Data Mart API:

    • Limit the size of queries. The AQS Data Mart contains billions of

      values and you may request more than you intend. If you 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 how much data exists for a time-parameter-geography combination.

    • Limit the frequency of queries. The AQS Data Mart can process a limited

      load. Please wait for one request to complete before submitting another and do not make more than 10 requests per minute.

    • Be advised that RAQSAPI is capable of retrieving results for multiple pollutants, this can result in the amount of data being returned being multiplied by the number of pollutants being requested.

    • Be advised that the AQS Data Mart API limits certain data requests to 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 the RAQSAPI library conveniently sends multiple API requests to the Data Mart API server, one request for each year, this can result in the amount of data being returned being multiplied by the number of years of data being requested.

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

Functions Exported by pyaqsapi

The pyaqsapi package includes the following submodules which are not loaded by default:

* pyaqsapi.bysite
* pyaqsapi.bycounty
* pyaqsapi.bycounty
* pyaqsapi.bycbsa
* pyaqsapi.bybox
* pyaqsapi.byma
* pyaqsapi.ma

With these submodules loaded the entire list of functions exported by the pyaqsapi package includes:

* pyaqsapi.aqs_cbsas,
* pyaqsapi.aqs_classes,
* pyaqsapi.aqs_counties_by_state,
* pyaqsapi.aqs_credentials,
* pyaqsapi.aqs_credentials,
* pyaqsapi.aqs_fields_by_service,
* pyaqsapi.aqs_fields_by_service,
* pyaqsapi.aqs_isavailable,
* pyaqsapi.aqs_isavailable,
* pyaqsapi.aqs_knownissues,
* pyaqsapi.aqs_knownissues,
* pyaqsapi.aqs_mas,
* pyaqsapi.aqs_parameters_by_class,
* pyaqsapi.aqs_pqaos,
* pyaqsapi.aqs_removeheader,
* pyaqsapi.aqs_revisionhistory,
* pyaqsapi.aqs_revisionhistory,
* pyaqsapi.aqs_sampledurations,
* pyaqsapi.aqs_sign_up,
* pyaqsapi.aqs_sign_up,
* pyaqsapi.aqs_sites_by_county,
* pyaqsapi.aqs_states,
* pyaqsapi.bybox.annualsummary,
* pyaqsapi.bybox.dailysummary,
* pyaqsapi.bybox.helperfunctions,
* pyaqsapi.bybox.monitors,
* pyaqsapi.bybox.quarterlysummary,
* pyaqsapi.bybox.sampledata,
* pyaqsapi.bycbsa.annualsummary,
* pyaqsapi.bycbsa.dailysummary,
* pyaqsapi.bycbsa.helperfunctions,
* pyaqsapi.bycbsa.monitors,
* pyaqsapi.bycbsa.quarterlysummary,
* pyaqsapi.bycbsa.sampledata,
* pyaqsapi.bycounty.annualsummary,
* pyaqsapi.bycounty.dailysummary,
* pyaqsapi.bycounty.helperfunctions,
* pyaqsapi.bycounty.monitors,
* pyaqsapi.bycounty.qa_annualperformanceeval,
* pyaqsapi.bycounty.qa_annualperformanceevaltransaction,
* pyaqsapi.bycounty.qa_blanks,
* pyaqsapi.bycounty.qa_collocated_assessments,
* pyaqsapi.bycounty.qa_flowrateaudit,
* pyaqsapi.bycounty.qa_flowrateverification,
* pyaqsapi.bycounty.qa_one_point_qc,
* pyaqsapi.bycounty.qa_pep_audit,
* pyaqsapi.bycounty.quarterlysummary,
* pyaqsapi.bycounty.sampledata,
* pyaqsapi.bycounty.transactionsample,
* pyaqsapi.byma.qa_annualpeferomanceeval,
* pyaqsapi.byma.qa_annualperformanceevaltransaction,
* pyaqsapi.byma.qa_blanks,
* pyaqsapi.byma.qa_collocated_assessments,
* pyaqsapi.byma.qa_flowrateaudit,
* pyaqsapi.byma.qa_flowrateverification,
* pyaqsapi.byma.qa_one_point_qc,
* pyaqsapi.byma.qa_pep_audit,
* pyaqsapi.byma.transactionsample,
* pyaqsapi.bypqao.qa_annualperformanceeval,
* pyaqsapi.bypqao.qa_annualperformanceevaltransaction,
* pyaqsapi.bypqao.qa_blanks,
* pyaqsapi.bypqao.qa_collocated_assessments,
* pyaqsapi.bypqao.qa_flowrateaudit,
* pyaqsapi.bypqao.qa_flowrateverification,
* pyaqsapi.bypqao.qa_one_point_qc,
* pyaqsapi.bypqao.qa_pep_audit,
* pyaqsapi.bysite.annualsummary,
* pyaqsapi.bysite.dailysummary,
* pyaqsapi.bysite.helperfunctions,
* pyaqsapi.bysite.monitors,
* pyaqsapi.bysite.qa_annualpeferomanceeval,
* pyaqsapi.bysite.qa_annualperformanceevaltransaction,
* pyaqsapi.bysite.qa_blanks,
* pyaqsapi.bysite.qa_collocated_assessments,
* pyaqsapi.bysite.qa_flowrateaudit,
* pyaqsapi.bysite.qa_flowrateverification,
* pyaqsapi.bysite.qa_one_point_qc,
* pyaqsapi.bysite.qa_pep_audit,
* pyaqsapi.bysite.quarterlysummary,
* pyaqsapi.bysite.sampledata,
* pyaqsapi.bysite.transactionsample,
* pyaqsapi.bystate.annualsummary,
* pyaqsapi.bystate.dailysummary,
* pyaqsapi.bystate.helperfunctions,
* pyaqsapi.bystate.monitors,
* pyaqsapi.bystate.qa_annualperformanceeval,
* pyaqsapi.bystate.qa_annualperformanceevaltransaction,
* pyaqsapi.bystate.qa_blanks,
* pyaqsapi.bystate.qa_collocated_assessments,
* pyaqsapi.bystate.qa_flowrateaudit,
* pyaqsapi.bystate.qa_flowrateverification,
* pyaqsapi.bystate.qa_one_point_qc,
* pyaqsapi.bystate.qa_pep_audit,
* pyaqsapi.bystate.quarterlysummary,
* pyaqsapi.bystate.sampledata,
* pyaqsapi.bystate.transactionsample

pyaqsapi functions are named according to the service and filter variables that are available by the AQS Data Mart API. Refer to Air Quality System (AQS) API for full details of the AQS DataMart API.

Variable descriptions and usage

These are all the available variables that can be used with various functions exported from the pyaqsapi library listed alphabetically. Not all of these variables are used with every function, and not all of these parameters are required. See the :ref: pyaqsapi functional families section to see which parameters are used with each function.

  • AQSobject:

    an object of type AQSAPI_V2 that is returned from pyaqsapi aggregate functions wheen return_header is True.

  • bdate:

    a date object which represents the begin date of the data selection. Only data on or after this date will be returned.

  • cbdate (optional):

    a date object which represents the “beginning date of last change” that indicates when the data was last updated. cbdate is used to filter data based on the change date. Only data that changed on or after this date will be returned. This is an optional variable which defaults to None.

  • cedate (optional):

    a date object which represents the “end date of last change” that indicates when the data was last updated. cedate is used to filter data based on the change date. Only data that changed on or before this date will be returned. This is an optional variable which defaults to None.

  • countycode:

    a character object which represents the 3 digit state FIPS code for the county being requested (with leading zero(s)). Refer to aqs_counties_by_state() for a table of available county codes for each state.

  • duration (optional):

    a character string that represents the parameter duration code that limits returned data to a specific sample duration. The default value of None will result in no filtering based on duration code. Valid durations include actual sample durations and not calculated durations such as 8 hour CO or O3rolling averages, 3/6 day PM averages or Pb 3 month rolling averages. Refer to aqs_sampledurations() for a table of all available duration codes.

  • edate:

    a date object which represents the end date of the data selection. Only data on or before this date will be returned.

  • email:

    a character object which represents the email account that will be used to register with the AQS API or change an existing user’s key. A verification email will be sent to the account specified.

  • key:

    a character object which represents the key used in conjunction with the username given to connect to AQS Data Mart.

  • MA_code:

    a character object which represents the 4 digit AQS Monitoring Agency code (with leading zeroes).

  • maxlat:

    a character object which represents the maximum latitude of a geographic box. Decimal latitude with north begin positive. Only data south of this latitude will be returned.

  • maxlon:

    a character object which represents the maximum longitude of a geographic box. Decimal longitude with east being positive. Only data west of this longitude will be returned. Note that -80 is less than -70.

  • minlat:

    a character object which represents the minimum latitude of a geographic box. Decimal latitude with north being positive. Only data north of this latitude will be returned.

  • minlon:

    a character object which represents the minimum longitude of a geographic box. Decimal longitude with east begin positive. Only data east of this longitude will be returned.

  • parameter:

    a character list or single character object which represents the parameter code of the air pollutant related to the data being requested.

  • return_Header:

    If False (default) only returns data requested as a pandas DataFrame. If True returns a AQSAPI_V2 object.

  • service:

    a string which represents the services provided by the AQS API. For a list of available services refer to <https://aqs.epa.gov/aqsweb/documents/data_api.html#services>_ for the complete listing of services available through the EPA AQS Datamart API

  • sitenum:

    a character object which represents the 4 digit site number (with leading zeros) within the county and state being requested.

  • stateFIPS:

    a character object which represents the 2 digit state FIPS code (with leading zero) for the state being requested.

  • pqao_code:

    a character object which represents the 4 digit AQS Primary Quality Assurance Organization code (with leading zeroes).

  • username:

    a character object which represents the email account that will be used to connect to the AQS API.

pyaqsapi functional families

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 store credential

information to use with pyaqsapi. The aqs_sign_up function takes one parameter:

  • email:

The aqs_credentials function takes two parameters:

  • username:

  • key:

Data Mart API metadata functions

The functions included in this family of functions are:

* aqs_isavailable
* aqs_knownissues
* aqs_fields_by_service
* aqs_revisionhistory

These functions return Data Mart meta data

The aqs_isavailable function takes no parameters and returns a table which details the status of the AQS API.

The aqs_fields_by_service function takes one parameter, service, which is a character object which represents the services provided by the AQS API. For a list of available services see Air Quality System (AQS) API - Services Overview

The aqs_knownissues function takes no parameters and Returns a table of any known issues with system functionality or the data. These are usually issues that have been identified internally and will require some time to correct in Data Mart or the API. This function implements a direct API call to Data Mart and returns data directly from the API. Issues returned via this function do not include any issues from the pyaqsapi package.

The aqs_revisionhistory function is used to query Data Mart for the change history to the API.

Data Mart API list functions

The functions included in this family of functions are:

* aqs_cbsas,
* aqs_classes,
* aqs_counties_by_state,
* aqs_fields_by_service,
* aqs_isavailable,
* aqs_knownissues,
* aqs_mas,
* aqs_parameters_by_class,
* aqs_pqaos,
* aqs_revisionhistory,
* aqs_sampledurations,
* aqs_sites_by_county,
* aqs_states

List functions return the API status, API options or groupings that can be used in conjunction with other API calls. By default each function in this category returns results as a DataTable. If return_header parameter is set to True a AQSAPI_v2 object is returned instead.

aqs_cbsas returns a table of all available Core Based Statistical Areas (cbsas) and their respective cbsa codes.

aqs_states takes no arguments and returns a table of the available states and their respective state FIPS codes.

aqs_sampledurations() aqs_sampledurations takes no arguments and returns a table of the available sample duration code used to construct other requests.

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

aqs_counties_by_state() aqs_counties_by_state takes one parameter, stateFIPS, which is a two digit state FIPS code for the state being requested represented as a character object and returns a table of counties and their respective FIPS code for the state requested. Use aqs_states to receive a table of valid state FIPS codes.

aqs_sites_by_county takes two parameters, stateFIPS, which is a two digit state FIPS code for the state being requested and county_code which is a three digit county FIPS code for the county being requested, both stateFIPS and county_code should be encoded as a character object. This function returns a table of all air monitoring sites with the requested state and county FIPS code combination.

aqs_pqaos takes no parameters and returns an AQSAPI_V2 object containing a table of primary quality assurance organizations (pqaos).

aqs_mas takes no parameters and returns an AQSAPI_V2 object containing a table of monitoring agencies (MA).

Data Mart aggregate functions

Note

AQS Data Mart API restricts the maximum amount of monitoring data to one full year of data per API call. These functions are able to return multiple years of data by making repeated calls to the API. Each call to the Data Mart API will take time to complete. The more years of data being requested the longer pyaqsapi will take to return the results.

These functions retrieve aggregated data from the Data Mart API and are grouped by how each function aggregates the data. There are 5 different families of related aggregate functions. These families are arranged by how the Data Mart API groups the returned data, bysite, bycounty, bystate, by<latitude/longitude bounding box> (bybox) and by<core based statistical area> (bycbsa). Within each family of aggregated data functions there are functions that call on the 10 different services that the Data Mart API provides. All Aggregate functions return a pandas DataFrame by default. If the return_Header parameter is set to True an AQSAPI_V2 object is returned instead.

These fourteen services are:

  1. Monitors:

    Returns operational information about the samplers (monitors) used to collect the data. Includes identifying information, operational dates, operating organizations, etc. Functions using this service contain monitors in the function name.

  2. Sample Data:

    Returns sample data - the most fine grain data reported to EPA. Usually hourly, sometimes 5-minute, 12-hour, etc. This service is available in several geographic selections based on geography: site, county, state, cbsa (core based statistical area, a grouping of counties), or by latitude/longitude bounding box. Functions using this service contain sampledata in the function name. All Sample Data functions accept two additional, optional parameters; cbdate and cedate.

    • cbdate:

      a date object which represents a “beginning date of last change” that indicates when the data was last updated. cbdate is used to filter data based on the change date. Only data that changed on or after this date will be returned. This is an optional variable which defaults to None.

    • cedate:

      a date object which represents an “end date of last change” that indicates when the data was last updated. cedate is used to filter data based on the change date. Only data that changed on or before this date will be returned. This is an optional variable which defaults to None.

    • duration:

      an optional character string that represents the parameter duration code that limits returned data to a specific sample duration. The default value of None results in no filtering based on duration code. Valid durations include actual sample durations and not calculated durations such as 8 hour CO or $O_3$ rolling averages, 3/6 day PM averages or Pb 3 month rolling averages. Refer to aqs_sampledurations() for a list of all available duration codes.

  3. Daily Summary Data:

    Returns data summarized at the daily level. All daily summaries are calculated on midnight to midnight basis in local time. Variables returned include date, mean value, maximum value, etc. Functions using this service contain Dailysummary in the function name. All Daily Summary Data functions accept two additional parameters; cbdate and cedate.

    • cbdate:

      a date object which represents a “beginning date of last change” that indicates when the data was last updated. cbdate is used to filter data based on the change date. Only data that changed on or after this date will be returned. This is an optional variable which defaults to None.

    • cedate:

      a date object which represents an “end date of last change” that indicates when the data was last updated. cedate is used to filter data based on the change date. Only data that changed on or before this date will be returned. This is an optional variable which defaults to None.

  4. Annual Summary Data:

    Returns data summarized at the yearly level. Variables include mean value, maxima, percentiles, etc. Functions using this service contain annualdata in the function name. All Annual Summary Data functions accept two additional parameters; cbdate and cedate.

    • cbdate:

      a date object which represents a “beginning date of last change” that indicates when the data was last updated. cbdate is used to filter data based on the change date. Only data that changed on or after this date will be returned. This is an optional variable which defaults to None.

    • cedate:

      a date object which represents an “end date of last change” that indicates when the data was last updated. cedate is used to filter data based on the change date. Only data that changed on or before this date will be returned. This is an optional variable which defaults to None.

  5. Quarterly Summary Data:

    Returns data summarized at the quarterly level. Variables include mean value, maxima, percentiles, etc. Functions using this service contain quarterlydata in the function name. All Annual Summary Data functions accept two additional parameters; cbdate and cedate.

    • cbdate:

      a date object which represents a “beginning date of last change” that indicates when the data was last updated. cbdate is used to filter data based on the change date. Only data that changed on or after this date will be returned. This is an optional variable which defaults to None.

    • cedate:

      a date object which represents an “end date of last change” that indicates when the data was last updated. cedate is used to filter data based on the change date. Only data that changed on or before this date will be returned. This is an optional variable which defaults to None.

  6. Quality Assurance - Blanks Data:

    Quality assurance data - blanks samples. Blanks are unexposed sample collection devices (e.g., filters) that are transported with the exposed sample devices to assess if contamination is occurring during the transport or handling of the samples. Functions using this service contain qa_blanks in the function name.

  7. Quality Assurance - Collocated Assessments:

    Quality assurance data - collocated assessments. Collocated assessments are pairs of samples collected by different samplers at the same time and place. (These are “operational” samplers, assessments with independently calibrated samplers are called “audits”.). Functions using this service contain qa_collocated_assessments in the function name.

  8. Quality Assurance - Flow Rate Verifications:

    Quality assurance data - flow rate verifications. Several times per year, each PM monitor must have it’s (fixed) flow rate verified by an operator taking a measurement of the flow rate. Functions using this service contain qa_flowrateverification in the function name.

  9. Quality Assurance - Flow Rate Audits:

    Quality assurance data - flow rate audits. At least twice year, each PM monitor must have it’s flow rate measurement audited by an expert using a different method than is used for flow rate verifications. Functions using this service contain qa_flowrateaudit in the function name.

  10. Quality Assurance - One Point Quality Control Raw Data:

    Quality assurance data - one point quality control check raw data. At least every two weeks, certain gaseous monitors must be challenged with a known concentration to determine monitor performance. Functions using this service contain qa_one_point_qc in the function name.

  11. Quality Assurance - pep Audits:

    Quality assurance data - performance evaluation program (pep) audits. Pep audits are independent assessments used to estimate total measurement system bias with a primary quality assurance organization. Functions using this service contain qa_pep_audit in the function name.

  12. Transaction Sample - AQS Submission data in transaction format (RD):

    Transaction sample data - The raw transaction sample data uploaded to AQS by the agency responsible for data submissions in RD format. Functions using this service contain transactionsample in the function name. Transaction sample data is only available aggregated by site, county, state or monitoring agency.

  13. Quality Assurance - Annual Performance Evaluations:

    Quality assurance data - Annual performance evaluations. A performance evaluation must be conducted on each primary monitor once per year. The percent differences between known and measured concentrations at several levels are used to assess the quality of the monitoring data. Functions using this service contain aqs_qa_annualperformanceeval in the function name. Annual performance in transaction format are only available aggregated by site, county, state, monitoring agency, and primary quality assurance organization. Annual performance evaluations are only available aggregated by site, county, state, monitoring agency, and primary quality assurance organization.

  14. Quality Assurance - Annual performance Evaluations in transaction

    format (RD): Quality assurance data - The raw transaction annual performance evaluations data in RD format. Functions using this service contain aqs_qa_annualperformanceevaltransaction in the function name. Annual performance evaluations in transaction format are only available aggregated by site, county, state, monitoring agency, and primary quality assurance organization.

Data Mart aggregate functions bysite

The bysite submodule exports the following functions:

* bysite.annualsummary,
* bysite.dailysummary,
* bysite.helperfunctions,
* bysite.monitors,
* bysite.qa_annualpeferomanceeval,
* bysite.qa_annualperformanceevaltransaction,
* bysite.qa_blanks,
* bysite.qa_collocated_assessments,
* bysite.qa_flowrateaudit,
* bysite.qa_flowrateverification,
* bysite.qa_one_point_qc,
* bysite.qa_pep_audit,
* bysite.quarterlysummary,
* bysite.sampledata,
* bysite.transactionsample
Functions exported by the bysite submodule aggregate data at the site level.

bysite functions accept the following variables:

  • parameter:

  • bdate:

  • edate:

  • stateFIPS:

  • countycode:

  • sitenum:

  • cbdate (optional):

    (This parameter is only used in conjunction with sampledata, dailysummary, annualdata functions and quarterlysummary functions).

  • cedate (optional):

    (This parameter is only used in conjunction with sampledata, dailysummary, annualdata functions and quarterlysummary functions).

  • return_header (optional):

    set to False by default.

  • duration (optional):

    (This parameter is only used in conjunction with sampledata functions).

Data Mart aggregate functions bycounty

The bycounty submodule exports the following functions:

* bycounty.annualsummary,
* bycounty.dailysummary,
* bycounty.helperfunctions,
* bycounty.monitors,
* bycounty.qa_annualperformanceeval,
* bycounty.qa_annualperformanceevaltransaction,
* bycounty.qa_blanks,
* bycounty.qa_collocated_assessments,
* bycounty.qa_flowrateaudit,
* bycounty.qa_flowrateverification,
* bycounty.qa_one_point_qc,
* bycounty.qa_pep_audit,
* bycounty.quarterlysummary,
* bycounty.sampledata,
* bycounty.transactionsample
Functions exported by the bycounty submodule aggregate data at the county

level. All functions accept the following variables:

  • parameter:

  • bdate:

  • edate:

  • stateFIPS:

  • countycode:

  • cbdate (optional):

    (This parameter is only used in conjunction with sampledata, dailysummary, annualdata and quarterlysummary functions).

  • cedate (optional):

    (This parameter is only used in conjunction with sampledata, dailysummary, annualdata and quarterlysummary functions).

  • return_header (optional):

    set to False by default.

  • duration (optional):

    (This parameter is only used in conjunction with sampledata functions).

Data Mart aggregate functions bystate

The bystate submodule exports the following functions:

* bystate.annualsummary,
* bystate.dailysummary,
* bystate.helperfunctions,
* bystate.monitors,
* bystate.qa_annualperformanceeval,
* bystate.qa_annualperformanceevaltransaction,
* bystate.qa_blanks,
* bystate.qa_collocated_assessments,
* bystate.qa_flowrateaudit,
* bystate.qa_flowrateverification,
* bystate.qa_one_point_qc,
* bystate.qa_pep_audit,
* bystate.quarterlysummary,
* bystate.sampledata,
* bystate.transactionsample
Functions exported by the bystate submodule aggregate data at the state level.

All functions accept the following variables:

  • parameter:

  • bdate:

  • edate:

  • stateFIPS:

  • countycode:

  • cbdate (optional):

    (This parameter is only used in conjunction with sampledata, dailysummary, annualdata and quarterlysummary functions).

  • cedate (optional):

    (This parameter is only used in conjunction with sampledata, dailysummary, annualdata and quarterlysummary functions).

  • return_header (optional):

    set to False by default.

  • duration (optional):

    (This parameter is only used in conjunction with sampledata functions).

Data Mart aggregate functions by Monitoring agency (MA)

The byma submodule exports the following functions:

* byma.qa_annualpeferomanceeval,
* byma.qa_annualperformanceevaltransaction,
* byma.qa_blanks,
* byma.qa_collocated_assessments,
* byma.qa_flowrateaudit,
* byma.qa_flowrateverification,
* byma.qa_one_point_qc,
* byma.qa_pep_audit,
* byma.transactionsample
Functions in this family of functions aggregate data at the state level.

All functions accept the following variables:

  • parameter:

  • bdate:

  • edate:

  • stateFIPS:

  • cbdate (optional):

    (This parameter is only used in conjunction with sampledata, dailysummary, annualdata functions and quarterlysummary functions).

  • cedate (optional):

    (This parameter is only used in conjunction with sampledata, dailysummary, annualdata and quarterlysummary functions).

  • return_header (optional):

    set to False by default.

  • duration (optional):

    (This parameter is only used in conjunction with sampledata functions).

Functions exported by the byma submodule aggregate data at the

Monitoring Agency (MA) level. All functions accept the following variables:

  • parameter:

  • bdate:

  • edate:

  • MA_code:

  • cbdate (optional):

    (This parameter is only used in conjunction with sampledata, dailysummary, annualdata and quarterlysummary functions).

  • cedate (optional):

    (This parameter is only used in conjunction with sampledata, dailysummary, annualdata and quarterlysummary functions).

  • return_header (optional):

    set to False by default.

  • duration (optional):

    (This parameter is only used in conjunction with sampledata functions).

Data Mart aggregate functions by Core Based Statistical Area (cbsa)

The bycbsa submodule exports the following functions:

* bycbsa.annualsummary,
* bycbsa.dailysummary,
* bycbsa.helperfunctions,
* bycbsa.monitors,
* bycbsa.quarterlysummary,
* bycbsa.sampledata
Functions exported by the bycbsa submodule aggregate data at the Core Based

Statistical Area (cbsa, as defined by the US Census Bureau) level. All functions accept the following variables:

  • parameter:

  • bdate:

  • edate:

  • cbsa_code:

  • cbdate (optional):

    (This parameter is only used in conjunction with sampledata, dailysummary, annualdata and quarterlysummary functions).

  • cedate (optional):

    (This parameter is only used in conjunction with sampledata, dailysummary, annualdata and quarterlysummary functions).

  • return_header (optional):

    set to False by default.

  • duration (optional):

    (This parameter is only used in conjunction with sampledata functions).

Data Mart aggregate functions by Primary Quality Assurance Organization (pqao)

The bypqao submodule exports the following functions:

* bypqao.qa_annualperformanceeval,
* bypqao.qa_annualperformanceevaltransaction,
* bypqao.qa_blanks,
* bypqao.qa_collocated_assessments,
* bypqao.qa_flowrateaudit,
* bypqao.qa_flowrateverification,
* bypqao.qa_one_point_qc,
* bypqao.qa_pep_audit
Functions exported by the bypqao submodule aggregate data at the

Primary Quality Assurance Organization (pqao) level. All functions accept the following variables:

  • parameter:

  • bdate:

  • edate:

  • pqao_code:

  • return_header (optional): set to False by default.

Data Mart aggregate functions by latitude/longitude bounding box (bybox)

The bybox submodule exports the following functions:

* bybox.annualsummary,
* bybox.dailysummary,
* bybox.helperfunctions,
* bybox.monitors,
* bybox.quarterlysummary,
* bybox.sampledata
Functions exported by the bybox submodule aggregate data by a

latitude/longitude bounding box (bybox) level. All functions accept the following variables:

  • parameter:

  • bdate:

  • edate:

  • minlat:

  • minlon:

  • maxlon:

  • maxlat:

  • cbdate (optional):

    (This parameter is only used in conjunction with sampledata, dailysummary, annualdata and quarterlysummary functions).

  • cedate (optional):

    (This parameter is only used in conjunction with sampledata, dailysummary, annualdata and quarterlysummary functions).

  • return_header (optional):

    set to False by default.

  • duration (optional):

    (This parameter is only used in conjunction with sampledata functions).

pyaqsapi Miscellaneous functions

These are miscellaneous functions exported by pyaqsapi.

aqs_removeheader is the function that the pyaqsapi library uses internally to coerce an AQSAPI_V2 object into a pandas DataFrame. This is useful if the user saves the output from another pyaqsapi function with return_header = True set but later decides that they want just a simple pandas DataFrame object. This function takes only one variable:

  • AQSobject:

Troubleshooting

Parameters must be supplied exactly as they are specified, for example the stateFIPS for Alabama is “01”, entering a value of “1” for the stateFIPS may lead to unexpected results. Do not omit leading zeros in parameters that expect them.

About RAQSAPI

pyaqsapi is a port of to the python 3 programming environment. For anyone that is familiar with RAQSAPI, the pyaqsapi API will feel familiar to you, most of the functions are similar and the parameters sent to each functions are the same. pyaqsapi aims to have feature parity with RAQSAPI and neither project will have features that the other project does not - other than programming language environment or language preference there is no benefit to using one package over the other.

pyaqsapi API reference documentation

pyaqsapi index

  • genindex

References

  1. AQS DataMart welcome. August 2018. URL: https://aqs.epa.gov/aqsweb/documents/data_mart_welcome.html.

  2. About AQS data. May 2019. Version 1.1. URL: https://aqs.epa.gov/aqsweb/documents/about_aqs_data.html.

  3. Pandas DataFrame. January 2024. URL: https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html.

  4. Clinton Mccrowey. A R extension to retrieve ambient air monitoring data from the United States Environmental Protection Agency's (US EPA) Air Quality System (AQS) DataMart API V2 interface. 2022. URL: https://github.com/USEPA/RAQSAPI.