pyaqsapi package

Subpackages

• pyaqsapi.bybox package
  • annualsummary()
  • dailysummary()
  • monitors()
  • quarterlysummary()
  • sampledata()
  • Submodules
  • pyaqsapi.bybox.bybox module
    • annualsummary()
    • dailysummary()
    • monitors()
    • quarterlysummary()
    • sampledata()
• pyaqsapi.bycbsa package
  • annualsummary()
  • dailysummary()
  • monitors()
  • quarterlysummary()
  • sampledata()
  • Submodules
  • pyaqsapi.bycbsa.bycbsa module
    • annualsummary()
    • dailysummary()
    • monitors()
    • quarterlysummary()
    • sampledata()
• pyaqsapi.bycounty package
  • annualsummary()
  • dailysummary()
  • monitors()
  • qa_annualperformanceeval()
  • qa_annualperformanceevaltransaction()
  • qa_blanks()
  • qa_collocated_assessments()
  • qa_flowrateaudit()
  • qa_flowrateverification()
  • qa_one_point_qc()
  • qa_pep_audit()
  • quarterlysummary()
  • sampledata()
  • transactionsample()
  • Submodules
  • pyaqsapi.bycounty.bycounty module
    • annualsummary()
    • dailysummary()
    • monitors()
    • qa_annualperformanceeval()
    • qa_annualperformanceevaltransaction()
    • qa_blanks()
    • qa_collocated_assessments()
    • qa_flowrateaudit()
    • qa_flowrateverification()
    • qa_one_point_qc()
    • qa_pep_audit()
    • quarterlysummary()
    • sampledata()
    • transactionsample()
• pyaqsapi.byma package
  • qa_annualpeferomanceeval()
  • qa_annualperformanceevaltransaction()
  • qa_blanks()
  • qa_collocated_assessments()
  • qa_flowrateaudit()
  • qa_flowrateverification()
  • qa_one_point_qc()
  • qa_pep_audit()
  • transactionsample()
  • Submodules
  • pyaqsapi.byma.byma module
    • qa_annualpeferomanceeval()
    • qa_annualperformanceevaltransaction()
    • qa_blanks()
    • qa_collocated_assessments()
    • qa_flowrateaudit()
    • qa_flowrateverification()
    • qa_one_point_qc()
    • qa_pep_audit()
    • transactionsample()
• pyaqsapi.bypqao package
  • qa_annualperformanceeval()
  • qa_annualperformanceevaltransaction()
  • qa_blanks()
  • qa_collocated_assessments()
  • qa_flowrateaudit()
  • qa_flowrateverification()
  • qa_one_point_qc()
  • qa_pep_audit()
  • Submodules
  • pyaqsapi.bypqao.bypqao module
    • qa_annualperformanceeval()
    • qa_annualperformanceevaltransaction()
    • qa_blanks()
    • qa_collocated_assessments()
    • qa_flowrateaudit()
    • qa_flowrateverification()
    • qa_one_point_qc()
    • qa_pep_audit()
• pyaqsapi.bysite package
  • annualsummary()
  • dailysummary()
  • monitors()
  • qa_annualpeferomanceeval()
  • qa_annualperformanceevaltransaction()
  • qa_blanks()
  • qa_collocated_assessments()
  • qa_flowrateaudit()
  • qa_flowrateverification()
  • qa_one_point_qc()
  • qa_pep_audit()
  • quarterlysummary()
  • sampledata()
  • transactionsample()
  • Submodules
  • pyaqsapi.bysite.bysite module
    • annualsummary()
    • dailysummary()
    • monitors()
    • qa_annualpeferomanceeval()
    • qa_annualperformanceevaltransaction()
    • qa_blanks()
    • qa_collocated_assessments()
    • qa_flowrateaudit()
    • qa_flowrateverification()
    • qa_one_point_qc()
    • qa_pep_audit()
    • quarterlysummary()
    • sampledata()
    • transactionsample()
• pyaqsapi.bystate package
  • annualsummary()
  • dailysummary()
  • monitors()
  • qa_annualperformanceeval()
  • qa_annualperformanceevaltransaction()
  • qa_blanks()
  • qa_collocated_assessments()
  • qa_flowrateaudit()
  • qa_flowrateverification()
  • qa_one_point_qc()
  • qa_pep_audit()
  • quarterlysummary()
  • sampledata()
  • transactionsample()
  • Submodules
  • pyaqsapi.bystate.bystate module
    • annualsummary()
    • dailysummary()
    • monitors()
    • qa_annualperformanceeval()
    • qa_annualperformanceevaltransaction()
    • qa_blanks()
    • qa_collocated_assessments()
    • qa_flowrateaudit()
    • qa_flowrateverification()
    • qa_one_point_qc()
    • qa_pep_audit()
    • quarterlysummary()
    • sampledata()
    • transactionsample()

Submodules

pyaqsapi.helperfunctions module

helperfunctions.

class pyaqsapi.helperfunctions.AQSAPI_V2

Bases: object

AQSAPI_V2 class used to store and retrieve data from the EPA AQS Datamart API.

# for some reason Sphinx does not like this Attributes section so it is # commented out, for now.

# Attributes # ———- # _header (pandas DataFrame): header information returned from the # AQS Datamart API. # _request_time (str): the time stamp that the call to the AQS Datamart # API was received. # _status (str): the status (associated with the _status_code) returned # from a call to the AQS Datamart API. # _status_code (str): the numeric status_code (represented as a string) # that is returned from a call to the AQS Datamart API. # _rows (str): the number of rows contained in the _data. # _url (str): a string representing the URL used to make the AQS Datamart # API call. # _data (pandas DataFrame): the data returned from a call to the # AQS Datamart API.

Methods

set_data():
set_header():
get_data():
get_header():
get_status_code():
get_header():
get_url():
get_header():
get_request_time():

get_data() → DataFrame

Return the Data portion of the AQSAPI_V2 instance.

Returns:

(pandas DataFrame) a DataFrame containing the Data portion of the

AQSAPI_V2 instance.

Return type:

DataFrame

get_header() → DataFrame

Return the Header portion of the AQSAPI_V2 instance.

Returns:

(pandas DataFrame) a DataFrame containing the Header portion of the

AQSAPI_V2 instance.

Return type:

DataFrame

get_request_time() → str

Retrieve the time that the request to the AQS DataMart API was made.

Returns:

(str) A string representing the time that that request to the AQS

DataMart API was made.

Return type:

str

get_status_code() → str

Retrieve the status code from the API call.

Returns:

(str) A string representing the status code returned from the EPA

DataMart API.

Return type:

str

get_url() → str

Retrieve the URL of the AQS DataMart API request.

Returns:

(str) A string representing the status code returned from the EPA

DataMart API.

Return type:

str

set_data(Data: DataFrame) → None

Set the Data of a single AQSAPI_V2 object.

Data must be a pandas DataFrame.

Returns:

None

Warns:

A warning is thrown if Data is not a pandas DataFrame

Parameters:

Data (DataFrame)

Return type:

None

set_header(Header: DataFrame) → None

Set the header of a single AQSAPI_V2 object. Header must be a pandas DataFrame.

Parameters:

HeaderPandas DataFrame

A pandas.DataFrame instance with the header information.

Returns:

None.

Warns:

A warning is thrown if Header is not a pandas DataFrame

Parameters:

Header (DataFrame)

Return type:

None

pyaqsapi.helperfunctions.aqs_credentials(username: str | None = None, key: str | None = None) → None

Set the user credentials for the AQS API. This function needs to be called once and only once every time this library is re-loaded. Users must have a valid username and key which can be obtained through the use of the aqs_sign_up function, use pyaqsapi.aqs_sign_up() to sign up for AQS data mart credentials.

Parameters:

usernamea python character object which represents the email account

that will be used to connect to the AQS API.

keythe key used in conjunction with the username given to connect to

AQS Data Mart.

Returns:

None

Parameters:

• username (str | None)

• key (str | None)

Return type:

None

pyaqsapi.helperfunctions.aqs_removeheader(aqsobject: list[AQSAPI_V2]) → DataFrame | AQSAPI_V2

Coerces a single AQS_Data_Mart_APIv2 instance or a list of AQS_Data_Mart_APIv2 instance into a single DataFrame object. This function decouples the Data from the AQSAPI_v2 object and returns only the Data portion as a DataFrame. If the input is a list of AQSAPI_v2 objects combines the Data portion of each AQS_Data_Mart_APIv2 object into a DataFrame with Header information discarded. Else returns the input with no changes.

Parameters:

aqsobjectAn object of AQSAPI_v2 or a list of AQSAPI_v2 objects.

Returns:

(DataFrame) A DataFrame containing the data portion of the AQSAPI_V2

object.

Parameters:

aqsobject (list[AQSAPI_V2])

Return type:

DataFrame | AQSAPI_V2

pyaqsapi.listfunctions module

listfunctions.

pyaqsapi.listfunctions.aqs_cbsas(return_header: bool | None = False) → AQSAPI_V2 | DataFrame

Return a table of all Core Based Statistical Areas (cbsa) and their associated cbsa_codes.

Parameters:

return_headerIf FALSE (default) only returns data requested. If TRUE

returns a AQSAPI_v2 object.

Returns:

(pandas DataFrame or an AQSAPI_V2 object): all cbsas and their associated

cbsa_codes.

Parameters:

return_header (bool | None)

Return type:

AQSAPI_V2 | DataFrame

Examples

Return a DataFrame of Core Based Statistical Areas (cbsas) and their respective cbsa codes:

aqs_cbsas()

pyaqsapi.listfunctions.aqs_classes(return_header: bool | None = False) → AQSAPI_V2 | DataFrame

Return a table of Parameter classes (groups of parameters, i.e. “criteria” or “all”). The information from this function can be used as input to other API calls.

Parameters:

return_headerIf FALSE (default) only returns data requested. If TRUE

returns a AQSAPI_v2 object.

Returns:

(pandas DataFrame or an AQSAPI_V2 object): Parameter classes (groups of

parameters, i.e. “criteria” or “all”).

Parameters:

return_header (bool | None)

Return type:

AQSAPI_V2 | DataFrame

Examples

Return a DataFrame of parameter classes (groups of parameters, i.e. “criteria” or all”):

aqs_classes()

pyaqsapi.listfunctions.aqs_counties_by_state(stateFIPS: str, return_header: bool | None = False) → AQSAPI_V2 | DataFrame

Return a table of all counties in within the stateFIPS provided.

Parameters:

stateFIPSa python character object which represents the 2 digit

state FIPS code (with leading zero) for the state being requested. Use aqs_states() for the list of available FIPS codes.

return_headerIf FALSE (default) only returns data requested. If TRUE

returns a AQSAPI_v2 object.

Returns:

(pandas DataFrame or an AQSAPI_V2 object): all counties in the requested

state.

Parameters:

• stateFIPS (str)

• return_header (bool | None)

Return type:

AQSAPI_V2 | DataFrame

Examples

Returns a DataFrame of all the counties in North Carolina the county FIPS codes (county codes) for each.:

aqs_counties_by_state(stateFIPS = "37")

pyaqsapi.listfunctions.aqs_fields_by_service(service: str, return_header: bool | None = False) → AQSAPI_V2 | DataFrame

Return a table containing the list and definitions of fields in the

service requested.

Parameters:

servicea 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

return_headerIf FALSE (default) only returns data requested. If TRUE

returns a AQSAPI_v2 object.

Returns:

(pandas DataFrame or an AQSAPI_V2 object): details the status of the AQS

API.

Parameters:

• service (str)

• return_header (bool | None)

Return type:

AQSAPI_V2 | DataFrame

Examples

Return a DataFrame containing a list and definitions of fields in the Sample Data service.:

aqs_fieldsbyservice(service = "sampleData")

pyaqsapi.listfunctions.aqs_isavailable(return_header: bool | None = False) → AQSAPI_V2 | DataFrame

Return a table explaining the status of the AQS API.

Parameters:

return_headerIf FALSE (default) only returns data requested. If TRUE

returns a AQSAPI_v2 object.

Returns:

(pandas DataFrame or an AQSAPI_V2 object): details the status of the AQS

API.

Parameters:

return_header (bool | None)

Return type:

AQSAPI_V2 | DataFrame

Examples

Check if the AQS API is up, running and accepting requests.:

aqs_isAvailable()

pyaqsapi.listfunctions.aqs_knownissues(return_header: bool | None = False) → AQSAPI_V2 | DataFrame

Return 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 python package.

Parameters:

return_headerIf FALSE (default) only returns data requested. If TRUE

returns a AQSAPI_v2 object.

Returns:

(pandas DataFrame or an AQSAPI_V2 object): information involving known

issues with the Data Mart API.

Parameters:

return_header (bool | None)

Return type:

AQSAPI_V2 | DataFrame

Examples

Retrieve a DataFrame of known issues directly from the AQS data mart API:

aqs_knownissues()

pyaqsapi.listfunctions.aqs_mas(return_header: bool | None = False) → AQSAPI_V2 | DataFrame

Return a DataFrame of monitoring agencies (MA).

Parameters:

return_headerIf FALSE (default) only returns data requested. If TRUE

returns a AQSAPI_v2 object.

Returns:

(pandas DataFrame or an AQSAPI_V2 object): monitoring agencies and their

associated agency code.

Parameters:

return_header (bool | None)

Return type:

AQSAPI_V2 | DataFrame

Examples

Returns a DataFrame of monitoring agencies and their respective monitoring agency codes.:

aqs_mas()

pyaqsapi.listfunctions.aqs_parameters_by_class(parameterclass: str, return_header: bool | None = False) → AQSAPI_V2 | DataFrame

Return a table of Parameter classes (groups of parameters, i.e. “criteria” or “all”). The information from this function can be used as input to other API calls.

Parameters:

parameterclass: a python character object that represents the class

requested, use aqs_classes() for retrieving available classes. The parameterclass python character object must be a valid parameterclass as returned from aqs_classes(). The class must be an exact match to what is returned from aqs_classes().

return_headerIf FALSE (default) only returns data requested. If TRUE

returns a AQSAPI_v2 object.

Returns:

(pandas DataFrame or an AQSAPI_V2 object): parameters associated with the

parameterclass requested. None is returned for parameterclasses not found.

Parameters:

• parameterclass (str)

• return_header (bool | None)

Return type:

AQSAPI_V2 | DataFrame

Examples

Return a DataFrame of parameter classes (groups of parameters, i.e. “criteria” or all”):

aqs_classes()

pyaqsapi.listfunctions.aqs_pqaos(return_header: bool | None = False) → AQSAPI_V2 | DataFrame

Return a table of primary quality assurance organizations (pqaos).

Parameters:

return_headerIf FALSE (default) only returns data requested. If TRUE

returns a AQSAPI_v2 object.

Returns:

(pandas DataFrame or an AQSAPI_V2 object): pqaos and their associated

pqao_codes.

Parameters:

return_header (bool | None)

Return type:

AQSAPI_V2 | DataFrame

Examples

Return a DataFrame of primary quality assurance organizations (pqaos):

aqs_pqaos()

pyaqsapi.listfunctions.aqs_revisionhistory(return_header: bool | None = False) → AQSAPI_V2 | DataFrame

Return a table Returns that contains change history to the AQS Data Mart API.

Parameters:

return_headerIf FALSE (default) only returns data requested. If TRUE

returns a AQSAPI_v2 object.

Returns:

(pandas DataFrame or an AQSAPI_V2 object): details change history to the

AQS Data Mart API.

Parameters:

return_header (bool | None)

Return type:

AQSAPI_V2 | DataFrame

Examples

Return a DataFrame of the EPA AQS Data Mart API revision history:

aqs_revisionHistory()

pyaqsapi.listfunctions.aqs_sampledurations(return_header: bool | None = False) → AQSAPI_V2 | DataFrame

Return a table of sample durations and their associated duration codes. Returned values are not calculated durations such as 8 hour carbon monoxide or ozone rolling averages, 3/6 day PM averages or Pb 3 month rolling averages.

Parameters:

return_headerIf FALSE (default) only returns data requested. If TRUE

returns a AQSAPI_v2 object.

Returns:

(pandas DataFrame or an AQSAPI_V2 object): sample durations and

their associated duration codes

Parameters:

return_header (bool | None)

Return type:

AQSAPI_V2 | DataFrame

Examples

Return a DataFrame of:

aqs_sampledurations()

pyaqsapi.listfunctions.aqs_sites_by_county(stateFIPS: str, countycode: str, return_header: bool | None = False) → AQSAPI_V2 | DataFrame

Return data containing a table of all air monitoring sites with the input state and county FIPS code combination.

Parameters:

stateFIPSa python character object which represents the 2 digit

state FIPS code (with leading zero) for the state being requested. Use aqs_states() for the list of available FIPS codes.

countycodea python character object which represents the 3 digit

state FIPS code for the county being requested (with leading zero(s)). Use aqs_counties_by_state() for the list of available county codes for each state.

return_headerIf FALSE (default) only returns data requested. If TRUE

returns a AQSAPI_v2 object.

Returns:

(pandas DataFrame or an AQSAPI_V2 object): all air monitoring sites with

the requested state and county FIPS codes.

Parameters:

• stateFIPS (str)

• countycode (str)

• return_header (bool | None)

Return type:

AQSAPI_V2 | DataFrame

Examples

Return a DataFrame of all the counties in North Carolina the county FIPS codes (county codes) for each.:

aqs_counties_by_state(stateFIPS = "37")

pyaqsapi.listfunctions.aqs_states(return_header: bool | None = False) → AQSAPI_V2 | DataFrame

Return a table of US states, US territories, and the district or Columbia with their respective FIPS codes.

Parameters:

return_headerIf FALSE (default) only returns data requested. If TRUE

returns a AQSAPI_v2 object.

Returns:

(pandas DataFrame or an AQSAPI_V2 object): states and their associated FIPS

code.

Parameters:

return_header (bool | None)

Return type:

AQSAPI_V2 | DataFrame

Examples

Return a DataFrame of states and their FIPS codes:

aqs_states()}

pyaqsapi.metadatafunctions module

metadatafunctions.

pyaqsapi.metadatafunctions.aqs_is_available(return_header: bool | None = False) → AQSAPI_V2 | DataFrame

Return the status of the AQS API.

Parameters:

return_headerIf FALSE (default) only returns data requested. If TRUE

returns a AQSAPI_v2 object.

Returns:

(pandas DataFrame or an AQSAPI_V2 object): Details the status of the

AQS API (The status information is located in the header).

Parameters:

return_header (bool | None)

Return type:

AQSAPI_V2 | DataFrame

pyaqsapi.metadatafunctions.aqs_knownissues(return_header: bool | None = False) → AQSAPI_V2 | DataFrame

Return 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 python package.

Parameters:

return_headerIf FALSE (default) only returns data requested. If TRUE

returns a AQSAPI_v2 object.

Returns:

(pandas DataFrame or an AQSAPI_V2 object): Information involving known

issues with the Data Mart API.

Parameters:

return_header (bool | None)

Return type:

AQSAPI_V2 | DataFrame

pyaqsapi.metadatafunctions.aqs_revisionhistory(return_header: bool | None = False) → AQSAPI_V2 | DataFrame

Return the change history to the AQS Data Mart API.

Parameters:

return_headerIf FALSE (default) only returns data requested. If TRUE

returns a AQSAPI_v2 object.

Returns:

(pandas DataFrame or an AQSAPI_V2 object): Information on the revision

history to the AQS Datamart API.

Parameters:

return_header (bool | None)

Return type:

AQSAPI_V2 | DataFrame

pyaqsapi.setupfunctions module

setupfunctions.

pyaqsapi.setupfunctions.aqs_sign_up(email: str) → None

Use this service to register as a new user or to reset an existing user’s key. A verification email will be sent to the email account specified. To reset a password: If the request is made with an email that is already registered, a new key will be issued for that account and emailed to the listed address. Usage is the same in either case. Refer to the email message for further instructions before continuing.

Parameters:

emailA python 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. Follow the instructions in the verification e-mail before proceeding to use any other functionality of the AQS API. Register your credential with the aqs_credentials() before using the other functions in this library.

Returns:

None.

Parameters:

email (str)

Return type:

None