Raindrop Trace

Trace the path of steepest descent from a coordinate to the nearest NHDPlusV2 flowline.

Overview

The raindrop trace process (nldi-flowtrace) follows an elevation surface downstream from a user-supplied coordinate to the nearest valid NHDPlusV2 flowline. It is used internally by the NLDI hydrolocation and basin endpoints and is also available as a standalone OGC API Process.

How the Algorithm Works

When a point is provided to the raindrop trace process:

  1. The algorithm samples elevation data around the input coordinate.
  2. The algorithm follows the direction of steepest descent downstream.
  3. The trace continues until it intersects a valid NHDPlusV2 flowline.
  4. The resulting intersection location becomes the hydrologic reference point.

This ensures that the flowline found is within the local catchment of the selected point, rather than one that is nearby in Euclidean space but belongs to a different catchment.

Raindrop trace (dark blue) intersecting a flowline (lighter blue), with the local NHDPlusV2 catchment (green) and custom drainage basin (faint green with blue border)
Raindrop trace (dark blue) intersecting a flowline (lighter blue), with the local NHDPlusV2 catchment (green) and custom drainage basin (faint green with blue border)

The figure shows a raindrop trace (dark blue) following the elevation surface to intersect an existing flowline (lighter blue). The green polygon is the local NHDPlusV2 catchment; the faint green area with blue border is the custom drainage basin derived for that intersection point.

Relationship to Hydrolocation

The NLDI hydrolocation endpoint behaves as follows:

  • If the given point lies within 200 meters of a flowline, it is snapped directly.
  • If not, the raindrop trace algorithm determines the downstream path to the appropriate flowline.

This ensures that hydrolocations are always associated with the correct catchment and are not misassigned to nearby but hydrologically unrelated tributaries.

See Basin and Hydrolocation for details on how raindrop trace integrates with basin delineation.

Example Request

Trace from a point near Madison, WI to the nearest flowline, returning the complete NHD flowline and the raindrop path:

POST https://api.water.usgs.gov/nldi/pygeoapi/processes/nldi-flowtrace/execution?f=json
Content-Type: application/json

{
  "inputs": {
    "lat": 43.0864,
    "lon": -89.35,
    "direction": "none"
  }
}

Set direction to "up" or "down" to receive only the upstream or downstream portion of the intersected flowline. Use "none" (the default) for the complete flowline.

The response includes GeoJSON features for the NHD flowline (or its upstream/downstream portion). If the input point does not already lie on a flowline, the response also includes a raindropPath geometry showing the traced path.

Explore the Full Parameter Schema

The pygeoapi process description provides the complete parameter schema, including input types and output descriptions: /processes/nldi-flowtrace?f=json