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 and introduced several
important changes to improve clarity and performance.

Key Changes

Flowlines Treated as a dataSource

Under the updated design, flowlines are now represented 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 Is Required

All navigation requests must explicitly provide a distance value (in kilometers).
In earlier implementations, a large implicit default distance allowed extremely
expensive queries to be triggered inadvertently. The updated requirement prevents
accidental high‑cost requests.

There is no upper limit on distance, but developers should choose reasonable
defaults to protect applications and users.

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.
This mode may return a large number of stream segments in dendritic networks.

Downstream Mainstem (DM)

Follows the primary downstream path from the starting point.
Useful for connectivity analysis and downstream impact studies.

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 location.

Example (illustrative pattern only):

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

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; they are indexed by catchment membership.
    Users should be aware that off‑flowpath points can appear.

TODOs

  • TODO: Confirm default distances recommended for Python‑based NLDI deployments.
  • TODO: Document trimStart behavior once implemented or confirmed.
  • TODO: Add examples of oversized distance queries and recommended safeguards.