dataretrieval.nldi

Retrieve hydrologic network features from the Network Linked Data Index (NLDI).

The getters below navigate the hydrologic network from an origin – a feature source and id, a comid, or a lat/long point – and return flowlines, basins, or registered features as a geopandas.GeoDataFrame, or as raw JSON when as_json=True. This module requires geopandas.

See https://api.water.usgs.gov/nldi/linked-data for the API reference.

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

Settings for NLDI calls alone.

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

This adapter is imported on demand for the geopandas extra, so this class registers itself later than the rest – which is exactly why the adapter roster lives in ADAPTERS rather than being derived from what has been imported.

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) – Linked-data base to send NLDI requests to, instead of the service’s own (NLDI_API_BASE_URL). Every navigation, basin and catalog request is built on 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] = 'nldi': 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.

dataretrieval.nldi.get_basin(feature_source: str, feature_id: str, simplified: bool = True, split_catchment: bool = False, as_json: bool = False) → GeoDataFrame | dict[str, Any][source]

Get the aggregated basin for the specified feature.

The basin is returned in WGS84 lat/lon as a GeoDataFrame or as JSON, containing a polygon geometry.

Parameters:

feature_source (string, name of the feature source)
feature_id (string, identifier of the feature)
simplified (bool, simplified, default is True)
split_catchment (bool, split catchment, default is False)
as_json (bool, return basin as JSON if set to True, otherwise return) – as GeoDataFrame, default is False

Returns:

gdf – GeoDataFrame/dict of basin

Return type:

GeoDataFrame or dict

Examples

>>> # Get basin for a feature source: WQP and feature id: USGS-01031500
>>> gdf = dataretrieval.nldi.get_basin(
...     feature_source="WQP", feature_id="USGS-01031500"
... )

Get all features along a navigation, either by comid or by feature source.

Features are returned as points in WGS84 lat/long coordinates - a GeoDataFrame containing a point geometry.

Parameters:

feature_source (string, optional, name of the feature source,) – required if comid is not provided
feature_id (string, optional, identifier of the feature,) – required if comid is not provided
navigation_mode (string, navigation mode, allowed values are 'UM', 'DM', 'UT', 'DD')
data_source (string, data source)
distance (int, distance in kilometers, default is 50)
comid (integer, optional, comid, required if feature source is not provided)
lat (float, optional, latitude, if provided, long is also required)
long (float, optional, longitude, if provided, lat is also required)
stop_comid (integer, optional, stop comid)
as_json (bool, optional, return features as JSON if set to True,) – otherwise return as GeoDataFrame, default is False

Returns:

gdf – GeoDataFrame/dict of features

Return type:

GeoDataFrame or dict

Examples

>>> # Get registered features for a feature source: WQP,
>>> # feature id: USGS-01031500
>>> gdf = dataretrieval.nldi.get_features(
...     feature_source="WQP", feature_id="USGS-01031500"
... )
>>> # Get features for a feature source: WQP, feature id: USGS-01031500,
>>> # and data source: nwissite in the upstream main
>>> gdf = dataretrieval.nldi.get_features(
...     feature_source="WQP",
...     feature_id="USGS-01031500",
...     navigation_mode="UM",
...     data_source="nwissite",
...     distance=50,
... )
>>> # Get features for a comid: 13294314, and data source: nwissite
>>> # in the upstream main
>>> gdf = dataretrieval.nldi.get_features(
...     comid=13294314,
...     navigation_mode="UM",
...     data_source="nwissite",
...     distance=50,
... )
>>> # Get features for a latitude: 43.073051 and longitude: -89.401230
>>> gdf = dataretrieval.nldi.get_features(lat=43.073051, long=-89.401230)

dataretrieval.nldi.get_features_by_data_source(data_source: str) → GeoDataFrame[source]

Get all features for the specified data source.

Features are returned as points in WGS84 lat/long coordinates as a GeoDataFrame containing a point geometry.

Parameters:: data_source (string, data source)
Returns:: gdf – GeoDataFrame of features
Return type:: GeoDataFrame

Examples

>>> # "nwissite" returns every NWIS site nationwide, so this example is
>>> # skipped in the doctest build to avoid the (very large) download.
>>> gdf = dataretrieval.nldi.get_features_by_data_source(
...     data_source="nwissite"
... )

dataretrieval.nldi.get_flowlines(navigation_mode: str, distance: int = 5, feature_source: str | None = None, feature_id: str | None = None, comid: int | None = None, stop_comid: int | None = None, trim_start: bool = False, as_json: bool = False) → GeoDataFrame | dict[str, Any][source]

Get the flowlines for a navigation, either by comid or by feature source.

Flowlines are returned in WGS84 lat/long coordinates as a GeoDataFrame containing a polyline geometry.

Parameters:

navigation_mode (string, navigation mode, allowed values are 'UM', 'DM', 'UT', 'DD')
distance (int, distance in kilometers, default is 5)
feature_source (string, optional, name of the feature source,) – required if comid is not provided
feature_id (string, optional, identifier of the feature,) – required if comid is not provided
comid (integer, optional, comid, required if feature source is not provided)
stop_comid (integer, optional, stop comid)
trim_start (bool, trim start, default is False)
as_json (bool, optional, return flowlines as JSON if set to True,) – otherwise return as GeoDataFrame, default is False

Returns:

gdf – GeoDataFrame/dict of flowlines

Return type:

GeoDataFrame or dict

Examples

>>> # Get flowlines for a feature source: WQP and
>>> # feature id: USGS-01031500 in the upstream main
>>> gdf = dataretrieval.nldi.get_flowlines(
...     feature_source="WQP",
...     feature_id="USGS-01031500",
...     navigation_mode="UM",
... )
>>> # Get flowlines for comid: 13294314 in the upstream main
>>> gdf = dataretrieval.nldi.get_flowlines(
...     comid=13294314, navigation_mode="UM"
... )

dataretrieval.nldi.search(feature_source: str | None = None, feature_id: str | None = None, navigation_mode: str | None = None, data_source: str | None = None, find: Literal['basin', 'flowlines', 'features'] = 'features', comid: int | None = None, lat: float | None = None, long: float | None = None, distance: int = 50) → dict[str, Any][source]

Search NLDI for the specified feature and return the results as a dict.

Parameters:

feature_source (string, name of the feature source)
feature_id (string, identifier of the feature)
navigation_mode (string, optional, navigation mode,) – allowed values are ‘UM’, ‘DM’, ‘UT’, ‘DD’
data_source (string, optional, data source)
find (string, search for 'basin', 'flowlines', or 'features', default is 'features')
comid (int, optional, comid, default is None)
lat (float, optional, latitude, default is None)
long (float, optional, longitude, default is None)
distance (int, optional, distance in kilometers, default is 50)

Returns:

dict

Return type:

search results

Examples

>>> # Search for aggregated basin for feature source: WQP
>>> # and feature id: USGS-01031500
>>> search_results = dataretrieval.nldi.search(
...     feature_source="WQP", feature_id="USGS-01031500", find="basin"
... )
>>> # Search for flowlines for feature source: WQP and
>>> # feature id: USGS-01031500 in the upstream main
>>> search_results = dataretrieval.nldi.search(
...     feature_source="WQP",
...     feature_id="USGS-01031500",
...     navigation_mode="UM",
...     find="flowlines",
... )
>>> # Get registered features for a feature source: WQP,
>>> # feature id: USGS-01031500
>>> gdf = dataretrieval.nldi.get_features(
...     feature_source="WQP", feature_id="USGS-01031500"
... )
>>> # Search for features for feature source: WQP, feature id: USGS-01031500,
>>> # and data source: census2020-nhdpv2 in the upstream main
>>> search_results = dataretrieval.nldi.search(
...     feature_source="WQP",
...     feature_id="USGS-01031500",
...     data_source="census2020-nhdpv2",
...     navigation_mode="UM",
...     find="features",
... )
>>> # Search for features for comid: 13294314,
>>> # and data source: census2020-nhdpv2 in the upstream main
>>> search_results = dataretrieval.nldi.search(
...     comid=13294314,
...     data_source="census2020-nhdpv2",
...     navigation_mode="UM",
... )
>>> # Search for flowlines for comid: 13294314 in the upstream main
>>> search_results = dataretrieval.nldi.search(
...     comid=13294314, navigation_mode="UM", find="flowlines"
... )
>>> # Search for features for latitude: 43.073051 and longitude: -89.401230
>>> search_results = dataretrieval.nldi.search(
...     lat=43.073051, long=-89.401230
... )