Getting Started with the NLDI Core API

Introduction to the Network Linked Data Index (NLDI), its core concepts, and the structure of the Python-based API.

The documentation in this section was derived from the following blog posts on the USGS Water Data for the Nation blog:

Introduction

The Network Linked Data Index (NLDI) is a system that indexes data to NHDPlusV2 catchments and provides a search service to discover data linked to the river network. It supports data sources such as streamgages, water quality sites, and watershed outlets.

Every request made to the NLDI API begins with a network-linked feature defined by:

  • {featureSource} — the collection (dataset) from which the feature originates
  • {featureID} — the identifier of the specific feature within that source

Examples of feature sources include NWIS streamgages (nwissite), Twelve-digit hydrologic unit outlets (huc12pp), and others published by the service. The special feature source comid corresponds to NHDPlusV2 catchment and flowline IDs.

Core API Concepts

NLDI API endpoint structure
NLDI API endpoint structure

Feature Sources

Feature sources represent collections of indexed features the NLDI knows about. They can be discovered using the getDataSources request in the NLDI Swagger documentation.

Each feature source contains a set of features, each with its own {featureID}, accessible through the getFeatures request. This endpoint returns all features for the chosen feature source.

The comid Feature Source

The comid feature source corresponds to NHDPlusV2 catchments and flowlines. It includes a special position query that performs a point-in-polygon lookup to find the catchment containing a given coordinate.

Basic Operations

Navigation functions allow you to retrieve network-connected flowlines or linked data relative to a starting {featureSource}/{featureID}. Navigation options include: upstream mainstem (UM), upstream tributaries (UT), downstream mainstem (DM), and downstream diversions (DD).

Basin

The basin operation returns the full upstream drainage area for the starting feature. No navigation parameters are required; the API derives the upstream polygon based on NHDPlusV2 topology.

Hydrolocation

The hydrolocation endpoint provides a linear reference on a flowline, either by snapping to the nearest flowline within 200 meters or by running a “raindrop trace” to the nearest downstream flowline using an elevation surface.

Service Evolution

The original “navigate” endpoint was replaced with an improved navigation endpoint, which:

  • Treats flowlines as a dataSource
  • Requires an explicit distance parameter

These refinements were introduced to make navigation more consistent and to reduce resource‑intensive unconstrained queries.

Notes & TODOs

  • TODO: Insert a short explanation of the migration to the Python implementation.
  • TODO: Add current base URL patterns for Python-backed endpoints.
  • TODO: Clarify caching behavior of the Python implementation.