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 by requesting the root endpoint (/linked-data?f=json), which returns the full list of available sources.

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.

Python Implementation

The NLDI has been migrated from its original Java implementation to Python. The API contract is unchanged — existing URLs, parameters, and response formats work as before. Notable differences:

  • Base URL: https://api.water.usgs.gov/nldi/linked-data
  • Swagger UI: Interactive API documentation is available at /nldi/swagger-ui.html . The OpenAPI specification can be retrieved from /nldi/v3/api-docs .
  • Caching: CloudFront serves responses. Cached responses carry an Age header, but the service does not set explicit Cache-Control headers.