dataretrieval.streamstats

Wrapper for the StreamStats API (streamstats documentation).

class dataretrieval.streamstats.StreamstatsConfiguration(retries: int | None = <not set>, stall_timeout: float | int | None = <not set>, base_url: str | None = <not set>)[source]

Settings for StreamStats calls alone.

No fan-out dials: a StreamStats query is answered by a single request.

Lives here rather than in dataretrieval.configuration because which settings a service reads is the service’s own knowledge (ADR 0011); what each of them means is shared, so the fields come from the setting groups declared beside their grammar.

Parameters:

  • retries (int, optional) – Retries attempted after a transient failure; 0 disables retrying.

  • stall_timeout (float, optional) – Seconds a call may go without receiving any data before retrying stops.

  • base_url (str, optional) – Services base to send StreamStats requests to, instead of its own (STREAMSTATS_URL). Both endpoints hang off it. Code only: the file and the environment refuse it.

__delattr__(name)

Implement delattr(self, name).

__eq__(other)

Return self==value.

__hash__()

Return hash(self).

__init__(retries: int | None = <not set>, stall_timeout: float | int | None = <not set>, base_url: str | None = <not set>) → None
__repr__()

Return repr(self).

__setattr__(name, value)

Implement setattr(self, name, value).

adapter: ClassVar[str] = 'streamstats'

The adapter this configuration targets, by the name of the module a caller imports. None on the package-wide Configuration, which every adapter reads. A ClassVar, not a field: the adapter is a property of the class, which is what stops the caller restating it at every call site and stops the roster being spelled twice.

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.