aquarius_webportal developer API

class aquarius_webportal.AquariusWebPortal(server='water.data.sa.gov.au', session=None, **kwargs)

Access data from a deployment of Aquarius Web Portal.

Parameters:

• server (str) – URL of the Web Portal deployment.

• session (optional) – requests.Session object to use

The main methods to use are:

• aquarius_webportal.AquariusWebPortal.fetch_locations(): fetch metadata for all locations

• aquarius_webportal.AquariusWebPortal.fetch_datasets(): fetch metadata for datasets measuring a queried parameter

• aquarius_webportal.AquariusWebPortal.fetch_dataset(): fetch data for a single timeseries

Relevant attributes of the AquariusWebPortal object are:

server

as initialised

Type:

str

params

the available parameters. If the portal is disclaimer-blocked, this will be empty (see ReadTheDocs documentation for further details)

Type:

pd.DataFrame

session

reqeusts.Session object

fetch_dataset(dset_name, date_range=None, extra_data_types=None, start=None, finish=None, session=None, **kwargs)

Fetch timeseries data for a single dataset.

Parameters:

• dset_name (str) – the dataset name as param.label@location - you can get this from the dset_name column of the table returned by aquarius_webportal.AquariusWebPortal.fetch_datasets()

• extra_data_types (str/sequence) – The additional metadata fields to retrieve for each data point - either “all”, None, or a sequence of strings with one or more of “grade”, “approval”, “qualifier”, and “interpolation_type”. None is the default.

• data_range (str) – either None (the default) or “Days7”

• start (pd.Timestamp) – earliest data to retrieve - None by default

• finish (pd.Timestamp) – latest data to retrieve - None by default

There are three ways of querying to speed things up, and these are selected depending on the values of the date_range, start and finish arguments:

(1) Entire period of record - the default - leave the date_range, start and finish arguments null.

(2) A custom period - leave date_range null and provide start and finish arguments.

(3) The last week - use “Days7” for date_range and leave start and finish null.

Returns:

a table of timeseries data. The table has a DateTimeIndex with timezone-aware timestamps. The time zone is derived from that provided by Aquarius Web portal in the header of the CSV which is downloaded in the background by this function. The first column will be the requested parameter (short) name with its unit in parentheses e.g. “Discharge (m^3/s)”. Following columns will be the extra_data_types if requested.

Return type:

pd.DataFrame

fetch_datasets(param_name=None, param_desc=None, param_id=None)

Fetch a list of all datasets from the portal with a given parameter

Parameters:

• param_name (str) – select a parameter with this name

• param_desc (str) – select a parameter with the description (note that usually the description functions as a “long name”)

• param_id (int) – select the parameter with this ID number

Returns:

a table of dataset metadata. The available fields may vary between different portals, but these may be present:

• wp_loc_id (called “LocationId” in the AQWP internal APIs)

• wp_dset_id (called “DatasetId” in the AQWP internal APIs)

• lon (called “LocX” in the AQWP internal APIs)

• lat (called “LocY” in the AQWP internal APIs)

• loc_name (called “Location” in the AQWP internal APIs)

• loc_id (called “LocationIdentifier” in the AQWP internal APIs)

• dset_name (called “DatasetIdentifier” in the AQWP internal APIs)

• loc_type (called “LocType” in the AQWP internal APIs)

• loc_folder (called “LocationFolder” in the AQWP internal APIs)

• dset_start (called “StartOfRecord” in the AQWP internal APIs)

• dset_end (called “EndOfRecord” in the AQWP internal APIs)

• param (str) - derived from dset_name

• label (str) - derived from dset_name

Return type:

pd.DataFrame

fetch_list(param_id=None)

Internal function that fetches list data from the /Data/Data_List endpoint.

Parameters:

param_id (int) – if not supplied, the list is of Locations. If supplied, the list is of Datasets/Time series.

Returns:

a table of results with some columns renamed for convenience:

• wp_loc_id (called “LocationId” in the AQWP internal APIs)

• wp_dset_id (called “DatasetId” in the AQWP internal APIs)

• lon (called “LocX” in the AQWP internal APIs)

• lat (called “LocY” in the AQWP internal APIs)

• loc_name (called “Location” in the AQWP internal APIs)

• loc_id (called “LocationIdentifier” in the AQWP internal APIs)

• dset_name (called “DatasetIdentifier” in the AQWP internal APIs)

• loc_type (called “LocType” in the AQWP internal APIs)

• loc_folder (called “LocationFolder” in the AQWP internal APIs)

• dset_start (called “StartOfRecord” in the AQWP internal APIs)

• dset_end (called “EndOfRecord” in the AQWP internal APIs)

• classification (called “Classification” in the AQWP internal APIs)

• bgcolor (called “Background” in the AQWP internal APIs)

• seq (called “Sequence” in the AQWP internal APIs)

• param (str) - derived from dset_name if the latter exists

• label (str) - derived from dset_name if the latter exists

Any other columns will not be renamed.

Return type:

pd.DataFrame

fetch_locations()

Fetch a list of all locations from the portal.

Returns:

a table of location metadata. The available fields may vary between different portals, but these may be present:

• wp_loc_id (called “LocationId” in the AQWP internal APIs)

• lon (called “LocX” in the AQWP internal APIs)

• lat (called “LocY” in the AQWP internal APIs)

• loc_name (called “Location” in the AQWP internal APIs)

• loc_id (called “LocationIdentifier” in the AQWP internal APIs)

• loc_type (called “LocType” in the AQWP internal APIs)

• loc_folder (called “LocationFolder” in the AQWP internal APIs)

Return type:

pd.DataFrame

fetch_params(payload=None)

Fetch the list of available parameters.

Returns:

a table of available parameters with these columns:

• param_id (int)

• param_name (str)

• param_desc (str)

Return type:

pd.DataFrame

get_param(param_name=None, param_desc=None, param_id=None)

Fetch/identify a single parameter from the params attribute.

Parameters:

• param_name (str) – select a parameter with this name

• param_desc (str) – select a parameter with the description (note that usually the description functions as a “long name”)

• param_id (int) – select the parameter with this ID number

Returns:

the relevant row from self.params with these fields:

• param_id (int)

• param_name (str)

• param_desc (str)

Return type:

pd.Series

aquarius_webportal.parse_params_from_html(source)

Obtain a list of parameter names, descriptions, and IDs from the HTML source of a Web Portal page (either the List or Map pages will work).

Returns:

a table of available parameters with these columns:

• param_id (int)

• param_name (str)

• param_desc (str)

Return type:

pd.DataFrame