Navigation Modes

Overview of upstream and downstream navigation modes in the Network Linked Data Index (NLDI).

Navigation Overview

Navigation is one of the core capabilities of the Network Linked Data Index (NLDI).
Each navigation request begins at a specific {featureSource}/{featureID} and returns
information about the hydrologic network upstream or downstream of that location.

The NLDI exposes four primary navigation modes:

  • UM — Upstream Mainstem
  • UT — Upstream with Tributaries
  • DM — Downstream Mainstem
  • DD — Downstream with Diversions

These modes allow users to explore hydrologic connectivity and retrieve flowlines
or linked environmental data along the river network.

The Navigation Endpoint

The modern navigation endpoint uses the following pattern:

/linked-data/{featureSource}/{featureID}/navigation/{navigationMode}/{dataSource}?distance={km}

This endpoint replaced the legacy navigate route, introducing changes that improve clarity and performance.

Key Changes

Flowlines Treated as a dataSource

The updated design treats flowlines as a selectable dataSource, just like NWIS sites or WQP sites.

This means navigation requests first return a list of possible dataSources,
and the caller chooses which one to follow (e.g., flowlines, nwissite, wqp).

distance Parameter

The distance parameter specifies how far to navigate in kilometers. While the API accepts requests without distance, the implicit default is very large (9999 km), which can produce expensive queries and large responses. Always provide an explicit distance value appropriate to your use case.

There is no enforced upper limit on distance, but large distances can return tens of thousands of features, increasing response time and memory use on both server and client. Choose a reasonable default for your use case.

Navigation Modes in Detail

Upstream Mainstem (UM)

Retrieves flowlines or indexed data along the single upstream path following the
mainstem of the river network.

Upstream with Tributaries (UT)

Retrieves all upstream tributaries feeding the starting location. In dendritic networks, this mode can return a large number of stream segments.

Downstream Mainstem (DM)

Follows the primary downstream path from the starting point. Commonly applied to connectivity analysis and downstream tracing.

Downstream with Diversions (DD)

Includes downstream branches, such as diverted flow paths.
This captures more complex hydrologic structures where the river splits.

Example Navigation URLs

Because the NLDI is indexed to catchments, navigation results may include flowlines slightly upstream or downstream of the exact point that appears to define the starting location.

Retrieve flowlines 150 km upstream along the mainstem from an NWIS gage:

https://api.water.usgs.gov/nldi/linked-data/nwissite/USGS-05428500/navigation/UM/flowlines?f=json&distance=150

Find all Water Quality Portal sites within 50 km downstream (with diversions):

https://api.water.usgs.gov/nldi/linked-data/nwissite/USGS-05428500/navigation/DD/wqp?f=json&distance=50

The trimStart Parameter

By default, navigation returns whole NHDPlus reaches, so the first flowline in the result may extend upstream or downstream of the starting feature’s actual position on the reach. The trimStart parameter trims the first flowline so it begins at the feature’s linear-reference location:

.../navigation/UM/flowlines?f=json&distance=100&trimStart=true

trimStart is available on the flowlines data source for all feature sources except comid. Using trimStart=true with a comid starting feature returns a 400 error because comid features represent entire reaches rather than point locations.

Additional Considerations

  • Navigation results include feature IDs from the chosen dataSource. For example, selecting nwissite returns all upstream or downstream NWIS sites reachable within the specified navigation mode and distance.

  • Linked data returned through navigation may not always lie on the main flowpath — features are indexed by catchment membership, so off‑flowpath points can appear.

  • Navigation endpoints also accept excludeGeometry=true to return feature properties without geometry, which can significantly reduce response size when only attributes are needed.

  • To discover available data sources for a navigation mode, request the navigation mode without specifying a data source:

    /linked-data/{featureSource}/{featureID}/navigation/{mode}?f=json

    The response lists all data sources (including flowlines) available for that navigation.

  • See the Swagger UI for the complete parameter reference.

  • See Client Libraries for Python (PyNHD) and R (dataRetrieval, nhdplusTools) examples covering all navigation modes.