pygeohydro.waterdata

Accessing WaterData related APIs.

Module Contents

class pygeohydro.waterdata.SensorThings

Class for interacting with SensorThings API.

static odata_helper(columns=None, conditionals=None, expand=None, max_count=None, extra_params=None)

Generate Odata filters for SensorThings API.

Parameters:

• columns (list of str, optional) – Columns to be selected from the database, defaults to None.

• conditionals (str, optional) – Conditionals to be applied to the database, defaults to None. Note that the conditionals should have the form of cond1 operator 'value' and/or cond2 operator 'value. For example: properties/monitoringLocationType eq 'Stream' and ...

• expand (dict of dict, optional) – Expand the properties of the selected columns, defaults to None. Note that the expand should have the form of {Property: {func: value, ...}}. For example: {"Locations": {"select": "location", "filter": "ObservedProperty/@iot.id eq '00060'"}}

• max_count (int, optional) – Maximum number of items to be returned, defaults to None.

• extra_params (dict, optional) – Extra parameters to be added to the Odata filter, defaults to None.

Returns:

odata (dict) – Odata filter for the SensorThings API.

Return type:

dict[str, str]

query_byodata(odata, outformat='json')

Query the SensorThings API by Odata filter.

Parameters:

• odata (str) – Odata filter for the SensorThings API.

• outformat (str, optional) – Format of the response, defaults to json. Valid values are json and geojson.

Returns:

pandas.DataFrame or geopandas.GeoDataFrame – Requested data.

Return type:

geopandas.GeoDataFrame | pandas.DataFrame

sensor_info(sensor_ids)

Query the SensorThings API by a sensor ID.

Parameters:

sensor_ids (str or list of str) – A single or list of sensor IDs, e.g., USGS-09380000.

Returns:

pandas.DataFrame – Requested sensor data.

Return type:

pandas.DataFrame

sensor_property(sensor_property, sensor_ids)

Query a sensor property.

Parameters:

• sensor_property (str or list of str) – A sensor property, Valid properties are Datastreams, MultiDatastreams, Locations, HistoricalLocations, TaskingCapabilities.

• sensor_ids (str or list of str) – A single or list of sensor IDs, e.g., USGS-09380000.

Returns:

pandas.DataFrame – A dataframe containing the requested property.

Return type:

pandas.DataFrame

class pygeohydro.waterdata.WaterQuality

Water Quality Web Service https://www.waterqualitydata.us.

Notes

This class has a number of convenience methods to retrieve data from the Water Quality Data. Since there are many parameter combinations that can be used to retrieve data, a general method is also provided to retrieve data from any of the valid endpoints. You can use get_json to retrieve stations info as a geopandas.GeoDataFrame or get_csv to retrieve stations data as a pandas.DataFrame. You can construct a dictionary of the parameters and pass it to one of these functions. For more information on the parameters, please consult the Water Quality Data documentation.

data_bystation(station_ids, wq_kwds)

Retrieve data for a single station.

Parameters:

• station_ids (str or list of str) – Station ID(s). The IDs should have the format “Agency code-Station ID”.

• wq_kwds (dict, optional) – Water Quality Web Service keyword arguments. Default to None.

Returns:

pandas.DataFrame – DataFrame of data for the stations.

Return type:

pandas.DataFrame

get_csv(endpoint, kwds, request_method='GET')

Get the CSV response from the Water Quality Web Service.

Parameters:

• endpoint (str) – Endpoint of the Water Quality Web Service.

• kwds (dict) – Water Quality Web Service keyword arguments.

• request_method (str, optional) – HTTP request method. Default to GET.

Returns:

pandas.DataFrame – The web service response as a DataFrame.

Return type:

pandas.DataFrame

get_json(endpoint, kwds, request_method='GET')

Get the JSON response from the Water Quality Web Service.

Parameters:

• endpoint (str) – Endpoint of the Water Quality Web Service.

• kwds (dict) – Water Quality Web Service keyword arguments.

• request_method (str, optional) – HTTP request method. Default to GET.

Returns:

geopandas.GeoDataFrame – The web service response as a GeoDataFrame.

Return type:

geopandas.GeoDataFrame

get_param_table()

Get the parameter table from the USGS Water Quality Web Service.

lookup_domain_values(endpoint)

Get the domain values for the target endpoint.

station_bybbox(bbox, wq_kwds)

Retrieve station info within bounding box.

Parameters:

• bbox (tuple of float) – Bounding box coordinates (west, south, east, north) in epsg:4326.

• wq_kwds (dict, optional) – Water Quality Web Service keyword arguments. Default to None.

Returns:

geopandas.GeoDataFrame – GeoDataFrame of station info within the bounding box.

Return type:

geopandas.GeoDataFrame

station_bydistance(lon, lat, radius, wq_kwds)

Retrieve station within a radius (decimal miles) of a point.

Parameters:

• lon (float) – Longitude of point.

• lat (float) – Latitude of point.

• radius (float) – Radius (decimal miles) of search.

• wq_kwds (dict, optional) – Water Quality Web Service keyword arguments. Default to None.

Returns:

geopandas.GeoDataFrame – GeoDataFrame of station info within the radius of the point.

Return type:

geopandas.GeoDataFrame