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.

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"
... )
dataretrieval.nldi.get_features(data_source: str | None = None, navigation_mode: str | None = None, distance: int = 50, feature_source: str | None = None, feature_id: str | None = None, comid: int | None = None, lat: float | None = None, long: float | None = None, stop_comid: int | None = None, as_json: bool = False) → GeoDataFrame | dict[str, Any][source]

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
... )