sensortoolkit.reference._ref_api_query.ref_api_query

ref_api_query(query_type=None, param=None, bdate='', edate='', aqs_id=None, airnow_bbox=None, username=None, key=None, path=None)[source]

Wrapper function for sending an API data query to either the AQS or AirNow API for a specified parameter (param).

Data returned by queries are parsed into pandas DataFrames and processed to convert header labels and column data types into a consistent standard for reference data sets.

Note

This method is configured to return datasets for parameters with the same parameter classification. The sensortoolkit Data Formatting Scheme (SDFS) organizes reference data into three primary classifications (datasets containing parameters corresponding to particulate matter are given the ‘PM’ classification, datasets containing gaseous parameters are assigned the ‘Gases’ classification, and datasets with meteorological parameters are assigned the ‘Met’ classification).

If users wish to query multiple parameters in one API call, the parameters passed to the ref_api_query() function via the param argument must be of the same parameter classification. For example, passing param = ['PM25', 'PM10'] would result in a valid query request, as both PM25 and PM10 have the same classification (PM). If instead, a user passed param = ['PM25', 'O3'], this would result in the function exiting execution as PM25 and O3 have different parameter classifications (PM and Gases).

Also, please note that AQS and AirNow use different naming conventions for parameters (e.g., AQS uses the parameter code 88101 for PM2.5 and AirNow uses ‘PM25’). These naming conventions are each different than the parameter naming convention used for this library. The param_to_api_naming dictionary provides a lookup dictionary for translating from sensortoolkit’s SDFS parameter naming convention to each of the API services, however, the list of associated parameter API names is not comprehensive. Users wishing to query parameters outside those listed below will need to modify this method accordingly.

For additional resources, please consult the linked documentation below for each API service:

Parameters
  • query_type (str) – The API service to query (either 'AQS' or 'AirNow').

  • param (str) – The evaluation parameter for which to return API query data.

  • bdate (str) – The overall starting date for the API query.

  • edate (str) – The overall ending date for the API query.

  • aqs_id (dict) – AQS only: AQS site ID separated into state, county, and site ID components.

  • airnow_bbox (dict) – AirNow only: Bounding box of latitude and longitude values.

  • username (str) – AQS only: email associated with API account

  • key (str) – Both AQS and AirNow: API authentication key code.

Returns

two-element tuple containing:

  • query_data (pandas DataFrame): Data returned by the API for the specified parameter and time frame. Data have been processed with column headers converted into standard naming scheme and column data types converted into a consistent formatting scheme for reference datasets.

  • raw_data (pandas DataFrame): An unmodified version of the dataset returned by the API query.

Return type

(tuple)