NLDI pygeoapi Processes

Geoprocessing services — raindrop trace, split catchment, and cross sections — exposed via OGC API – Processes.

The documentation in this section was derived from The Network Linked Data Index Geoprocessing with OGC API Processes on the USGS Water Data for the Nation blog.

Introduction

The NLDI exposes several geoprocessing capabilities through an OGC API – Processes interface hosted by a pygeoapi server at https://api.water.usgs.gov/nldi/pygeoapi. These processes extend the core NLDI beyond indexing and navigation, providing elevation-based analysis tools for flowline tracing, catchment splitting, and cross-section extraction.

All processes operate on NHDPlusV2 network and catchment data and use 3DEP elevation data for surface analysis.

The OGC API – Processes Pattern

All NLDI pygeoapi processes follow the OGC API – Processes standard, which defines a uniform interface for discovering, executing, and retrieving results from server-side geoprocessing.

Synchronous Execution

Send a POST request to /processes/{processId}/execution with a JSON body containing the process inputs. The server returns the result directly in the response:

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"
  }
}

For simple requests, synchronous execution returns results immediately in the response body.

Asynchronous Execution

For processes that may take longer to complete, use the asynchronous pattern:

Submit — POST to /processes/{processId}/execution with the header Prefer: respond-async. The server returns 201 Created with a Location header containing the job URL.
Poll — GET the job URL (/jobs/{jobId}) to check status. The response includes a status field (accepted, running, successful, or failed).
Retrieve — When status is successful, GET /jobs/{jobId}/results to retrieve the output.

All NLDI pygeoapi processes support both synchronous and asynchronous execution.

Available Processes

Process	Description	Docs	Explore
`nldi-flowtrace`	Trace the path of steepest descent to the nearest NHDPlusV2 flowline	Raindrop Trace	JSON
`nldi-splitcatchment`	Split the local NHDPlusV2 catchment at a flowline position	Split Catchment	JSON
`nldi-xsatpoint`	Extract a cross-sectional elevation profile at a point	Cross Section at a Point	JSON
`nldi-xsatendpts`	Construct a cross-sectional transect between two endpoints	Cross Section at Endpoints	JSON
`nldi-xsatpathpts`	Extract elevation along a user-provided coordinate path	—	JSON

The current process list can always be discovered at /processes?f=json .

The pygeoapi Process Description

The pygeoapi server provides a machine-readable process description for every process. These descriptions show the complete parameter schema, including input types, defaults, and constraints.

To inspect the full schema for any process, append ?f=json to the process URL — for example: /processes/nldi-flowtrace?f=json .

The process descriptions are the authoritative parameter reference. This documentation focuses on how each process works conceptually and provides one working example per process. For complete input and output details, consult the process description.

The full OpenAPI specification is also available via Swagger UI .

Relationship to Core NLDI API

Two core NLDI endpoints rely internally on these processes:

hydrolocation — uses raindrop trace for point snapping
basin — uses both raindrop trace and split catchment to construct precise drainage basins

The pygeoapi endpoints expose these same algorithms as standalone services for custom geoprocessing workflows. See Basin and Hydrolocation for details on how these algorithms are used within the core NLDI API.

NLDI API Summary

The diagram below shows how the pygeoapi process endpoints fit alongside the core NLDI linked-data API.