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.
It requires no additional parameters and is based on upstream accumulation of
NHDPlusV2 catchments.

Example pattern:

/linked-data/{featureSource}/{featureID}/basin

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.

Hydrolocation

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

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

Example pattern:

/linked-data/hydrolocation?coords=POINT(lon lat)

The result includes the flowline identifier and a measure value indicating the
location along the network.

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.

This ensures that 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
and are also exposed through the NLDI pygeoapi server.

Associated figures referenced in the source blog post:

  • map_base.png — base map showing drainage context
  • basin_zoom.png — zoomed depiction of a raindrop trace and resulting basin
  • basin.png — final delineated basin

(Images must be placed manually in the static directory for final site generation.)

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.

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.

Notes & TODOs

  • TODO: Confirm whether simplified=true remains the default for Python-backed basin operations.
  • TODO: Clarify semantics of splitCatchment=true in the Python API once implemented.
  • TODO: Add coordinate format examples for hydrolocation beyond WKT once final spec is known.