dataretrieval.streamstats

Wrapper for the StreamStats API (streamstats documentation).

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

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[source]

Delineate the watershed at (xlocation, ylocation).

Parses the response onto this instance.

__weakref__

list of weak references to the object

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

Extract watershed fields from streamstats_json onto this instance.

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

Create a Watershed from a parsed StreamStats JSON payload.

No new request is issued. 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[source]

Download a StreamStats workspace.

Parameters:

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

  • format (string) – Format of the download. The default returns an ESRI geodatabase zipfile; ‘SHAPE’ returns 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[source]

Get a watershed object for a sample location in NY.

Calls dataretrieval.streamstats.get_watershed with the parameters ‘NY’, -74.524, and 43.939, and returns the resulting 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[source]

Get a watershed object for a 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) – Whether to include parameters in the response.

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

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

  • simplify (bool, optional) – Whether 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.