dataretrieval.streamstats

This module is a wrapper for the StreamStats API (streamstats documentation).

class dataretrieval.streamstats.Watershed(rcode: str, xlocation: float, ylocation: float)

Parsed StreamStats watershed result.

Holds the delineated watershed features, the computed basin parameters, and the service workspaceID extracted from a StreamStats watershed response. Build one from an already-fetched payload with from_streamstats_json(), or construct directly from a location to fetch and parse in a single step.

watershed_point

GeoJSON feature for the delineation (pour) point.

Type:

dict

watershed_polygon

GeoJSON feature for the delineated basin polygon.

Type:

dict

parameters

Basin characteristics returned by the service.

Type:

list

_workspaceID

Service workspace id, usable with dataretrieval.streamstats.download_workspace.

Type:

str

__init__(rcode: str, xlocation: float, ylocation: float) → None

Delineate the watershed at (xlocation, ylocation) and parse the response onto this instance.

__weakref__

list of weak references to the object

_populate(streamstats_json: dict[str, Any]) → None

Extract watershed fields from a StreamStats JSON payload onto this instance.

classmethod from_streamstats_json(streamstats_json: dict[str, Any]) → Watershed

Create a Watershed from an already-parsed StreamStats JSON payload, without issuing a new request.

Builds a fresh instance (via __new__, so the network-fetching __init__ is bypassed) and populates it; each call returns an independent object rather than mutating shared class state.

dataretrieval.streamstats.download_workspace(workspaceID: str, format: str = '') → Response

Function to download a StreamStats workspace.

Parameters:

• workspaceID (string) – Service workspace received from watershed result

• format (string) – Download return format. Default will return ESRI geodatabase zipfile. ‘SHAPE’ will return a zip file containing shape format.

Returns:

r – A zip file containing the workspace contents, in either a geodatabase or shape files.

Return type:

geodatabase or shapefiles

dataretrieval.streamstats.get_sample_watershed() → Watershed

Sample function to get a watershed object for a location in NY.

Makes the function call dataretrieval.streamstats.get_watershed with the parameters ‘NY’, -74.524, 43.939, and returns the watershed object.

Returns:

Watershed – Custom object that contains the watershed information as extracted from the StreamStats JSON object.

Return type:

dataretrieval.streamstats.Watershed

dataretrieval.streamstats.get_watershed(rcode: str, xlocation: float, ylocation: float, crs: int | str = 4326, includeparameters: bool = True, includeflowtypes: bool = False, includefeatures: bool = True, simplify: bool = True, format: str = 'geojson') → Response | Watershed

Get watershed object based on location

StreamStats documentation: Returns a watershed object. The request configuration will determine the overall request response. However all returns will return a watershed object with at least the workspaceid. The workspace id is the id to the service workspace where files are stored and can be used for further processing such as for downloads and flow statistic computations.

See: https://streamstats.usgs.gov/streamstatsservices/#/ for more information.

Parameters:

• rcode (string) – StreamStats 2-3 character code that identifies the Study Area – either a State or a Regional Study.

• xlocation (float) – X location of the most downstream point of desired study area.

• ylocation (float) – Y location of the most downstream point of desired study area.

• crs (integer, string, optional) – EPSG spatial reference code, default is 4326

• includeparameters (bool, optional) – Boolean flag to include parameters in response.

• includeflowtypes (bool, string, optional) – Not yet implemented. Would be a comma separated list of region flow types to compute with the default being True

• includefeatures (list, optional) – Comma separated list of features to include in response.

• simplify (bool, optional) – Boolean flag controlling whether or not to simplify the returned result.

• format (string, optional) – Controls the return type, default is ‘geojson’. ‘geojson’ returns the raw httpx.Response; ‘object’ parses the response into a dataretrieval.streamstats.Watershed. ‘shape’ is not implemented and raises NotImplementedError.

Returns:

r – The raw response when format='geojson' (the default), or a custom Watershed object containing the watershed information extracted from the StreamStats JSON when format='object'.

Return type:

httpx.Response or dataretrieval.streamstats.Watershed

Raises:

NotImplementedError – If format='shape', which is not yet implemented.