Basin and Hydrolocation

Understanding basin retrieval, hydrolocation, and elevation-based processing used by the NLDI.

Overview

The NLDI provides two key operations that return spatial information based on
network location:

  1. Basin — returns the upstream drainage area for a given {featureSource}/{featureID}
  2. Hydrolocation — returns a precise linear reference on the hydrologic network

These operations rely on both NHDPlusV2 network geometry and specialized
processing algorithms.

Basin Endpoint

The basin endpoint returns an upstream basin polygon for any registered feature.

Example:

https://api.water.usgs.gov/nldi/linked-data/nwissite/USGS-05428500/basin?f=json

The basin is assembled from all catchments upstream of the feature’s associated comid, producing a polygon representing the full watershed contributing flow to that point.

Parameters

Parameter Default Description
simplified true When true, returns a reduced-vertex polygon suitable for display. Set to false for full-resolution NHDPlusV2 geometry.
splitCatchment false When true, the local catchment containing the feature is split at the feature’s linear-reference position, and only the upstream portion is included. This produces a more precise drainage boundary for features that do not coincide with a catchment outlet.

Both parameters are optional. A basic basin request with no parameters returns a simplified polygon based on whole upstream catchments.

See the Swagger UI for the complete parameter reference.

Hydrolocation

The hydrolocation endpoint provides a linear referencing position along a flowline.
When you submit a point via coords=POINT(lon lat), the endpoint:

  • Snaps the point to the nearest flowline if within 200 meters
  • Otherwise performs a raindrop trace to find the nearest downstream flowline

Example — snap a coordinate near Madison, WI to the hydrologic network:

https://api.water.usgs.gov/nldi/linked-data/hydrolocation?f=json&coords=POINT(-89.35 43.0864)

The result includes the flowline geometry, the comid, and a measure value indicating the linear-reference position along the reach.

Raindrop Trace Algorithm

The raindrop trace algorithm uses elevation data to follow the path of steepest
descent from the input coordinate to the nearest flowline in the correct catchment.

As a result, hydrolocation references:

  • Identify a valid flowline within the local catchment
  • Avoid snapping to nearby but hydrologically incorrect tributaries
  • Provide a consistent starting point for basin or split-catchment operations

The nldi-flowtools and nldi-xstool Python packages implement this algorithm. The NLDI pygeoapi server exposes them as standalone services.

The raindrop trace and split-catchment algorithms are also available as standalone geoprocessing services through the NLDI pygeoapi processes .

Split Catchment Algorithm

The split catchment algorithm divides the local NHDPlus catchment polygon into
two polygons:

  • Upstream portion contributing to the hydrolocation point
  • Downstream portion below the hydrolocation point

This process requires:

  • A precise location on a flowline (typically provided by raindrop trace)
  • NHDPlusV2 catchment geometry
  • Flow direction and network connectivity metadata

The resulting upstream polygon can be combined with the larger basin polygon to produce a precise, point‑specific drainage area.

The split catchment is also available as a standalone geoprocessing service; see Split Catchment for the OGC API Processes endpoint and a working POST example.

Example Workflow (Conceptual)

  1. User provides a coordinate.
  2. Hydrolocation identifies the flowline position (snap or elevation trace).
  3. Split catchment divides local catchment into upstream and downstream components.
  4. Basin endpoint supplies the full upstream catchment accumulation.
  5. Combined output yields a custom delineated basin for the exact point.

See Client Libraries for Python and R examples of basin retrieval.