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