Split Catchment

Split an NHDPlusV2 catchment polygon into upstream and downstream portions at a flowline position.

Overview

The split catchment process (nldi-splitcatchment) divides an NHDPlusV2 catchment polygon into an upstream and a downstream portion using a precise location along a flowline. This location is typically derived from a raindrop trace . The process optionally returns the full upstream drainage basin.

How the Algorithm Works

The process requires a coordinate (lat/lon). Internally, the raindrop trace algorithm identifies the hydrologically correct position along the nearest flowline.

Given this flowline position, the algorithm:

  1. Identifies the local catchment polygon associated with the flowline.
  2. Splits this polygon into two parts:
    • The upstream portion draining to the linear-reference point
    • The downstream portion below the point
  3. Returns both polygons as separate GeoJSON geometries.

When upstream is true, the upstream split polygon is combined with all upstream NHDPlusV2 catchments to produce a complete drainage basin.

Drainage basin upstream of a streamgage, showing the basin context
Drainage basin upstream of a streamgage, showing the basin context

A stream gage (black dot) at the outlet of a drainage basin. When a point does not coincide with a natural basin outlet, the split catchment algorithm derives a precise boundary.

Custom delineated drainage basin produced by combining split catchment with upstream accumulation
Custom delineated drainage basin produced by combining split catchment with upstream accumulation

The resulting custom-delineated basin, produced by combining the split catchment upstream polygon with all upstream NHDPlusV2 catchments.

Role in Basin Delineation

Combine the split catchment output with the NLDI upstream accumulation (basin retrieval) to create a precise drainage basin for any point along a flowline.

This workflow:

  • Ensures that the downstream limit is placed exactly at the user-defined location
  • Produces a basin boundary that better reflects the actual drainage divide, since it splits the local catchment rather than using its full extent
  • Supports use cases such as custom watershed boundaries or flowpath-specific studies

See Basin and Hydrolocation for how splitCatchment=true triggers this process from the core NLDI basin endpoint.

Example Request

Split the catchment at a point near Madison, WI and return the full upstream drainage basin:

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

{
  "inputs": {
    "lat": 43.0864,
    "lon": -89.35,
    "upstream": true
  }
}

When upstream is true, the response includes three GeoJSON geometries: the local catchment, the splitCatchment (upstream portion of the local catchment), and the full drainageBasin (all upstream catchments combined with the split portion). When false, only the local catchment and split catchment are returned.

Explore the Full Parameter Schema

The pygeoapi process description provides the complete parameter schema: /processes/nldi-splitcatchment?f=json