Skip to main content

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

The Network Linked Data Index Geoprocessing with OGC API Processes

Update on the Network Linked Data Index processing capabilities using OGC API Process

Date Posted April 12, 2022 Last Updated June 16, 2025
Author David Blodgett
Reading Time 4 minutes Share

The Network Linked Data Index (NLDI) is a search engine that indexes data to the flowpaths and/or catchments of a river network and provides discovery services based on position in that network. Like a search engine, it can cache and index new data. It also offers some convenient data services like basin boundaries and accumulated catchment characteristics.

Previous waterdata blog post (intro , new functionality and linked-data ) describe what the Network Linked Data Index (NLDI) is and what it can do in detail.

This post announces new capabilities that extend the base NLDI API with processing capabilities implemented as open-source python-based geoprocessing services that are exposed using the new OGC-API Processes specification.

NLDI API Background:

For those not familiar, a quick overview follows. The NLDI API offers an intuitive set of web resources via a linked-data endpoint. It is hosted on https://labs.waterdata.usgs.gov. ... below is used as shorthand for this base URL. For full API details, see the Swagger API documentation here.

A set of featureSources can be discovered at the linked-data root.
.../api/nldi/linked-data/

Each featureSource is made up of a set of features. each with its own featureID. A specific featureID can be accessed with a URL like:
.../api/nldi/linked-data/{featureSource}/{featureID}

The NLDI has a navigation api based on each featureID providing upstream/downstream search and access to network-data.
.../api/nldi/linked-data/{featureSource}/{featureID}/navigation
.../api/nldi/linked-data/{featureSource}/{featureID}/navigation/{mode}/{dataSource}

Two other capabilities stem from each featureID – one to retrieve a basin polygon upstream of the feature and one to retrieve local, total accumulated, or divergence-routed accumulated landscape characteristics.
.../api/nldi/linked-data/{featureSource}/{featureID}/basin
.../api/nldi/linked-data/{featureSource}/{featureID}/{local|tot|div}

comid is a “special” featureSource which corresponds to identifiers for the catchment polygons and flowpath lines of the base index.
.../api/nldi/linked-data/comid/

The comid feautureSource offers a position endpoint allowing discovery of network identifiers for a given lon/lat location. This is a simple “point in polygon” query that returns the flowline for the catchment area the provided coordinates are in.
.../api/nldi/linked-data/comid/position?coords=POINT({lon} {lat})

There is also a hydrolocation endpoint that returns a linear reference to a flowline. If the provided point is within 200 meters, it is “snapped” to the flowline, otherwise the linear reference is derived using a “raindrop trace” that follows an elevation surface downstream to the nearest flowline.
.../api/nldi/linked-data/hydrolocation?coords=POINT({lon lat})

Diagram showing the overall Network Linked Data Index API

NLDI API Summary Diagram

NLDI Processing Updates:

Simple map depicting a drainage basin upstream of a streamgage.

This figure shows a stream gage (black dot) at the outlet of a drainage basin. In this case, the streamgage is at a naturally occurring basin outlet in the hydrographic data used by the NLDI. But this is not always the case. Sometimes, as shown below, we need to derive a drainage basin for a point midway up a flowline river segment.

The NLDI hydrolocation and basin endpoints both rely on some custom elevation-based processing. The two processes are referred to as “raindrop trace” and “split catchment” algorithms. Two other algorithms, both to retrieve cross sections are included in the current (Spring 2022) NLDI processing services. These algorithms retrieve cross sections either at a point along a flowline from the NLDI or between two provided points (presumable spanning a river to form a cross section).

These raindrop trace an split catchment algorithms are available as stand alone python packages: nldi-xstool and nldi-flowtools as well as hosted processing services via the NLDI “pygeoapi” server. pygeoapi is a python OGC API server that the USGS waterdata teams use for a number of applications.

Both the hydrolocation and basin endpoints use the raindrop trace algorithm. It ensures that a flowline within the local catchment of a selected point is found, rather than one that is nearby but in a different catchment and the point used for basin retrieval is along a flowline rather than a small dributary implied by elevation data.

Simple map depicting a raindrop trace intersection with a flowline and the resulting split catchment and basin boundary.

This figure shows a raindrop trace (dark blue) that intersects an existing flowline (lighter blue), the local NHDPlusV2 catchment area (green), and a custom drainage basin for the intersection point (faint green with blue border).

The second process called in the code behind the basin endpoint is the split catchment algorithm. This algorithm requires that a precise location along a flowline be provided (as can be derived from the raindrop trace algorithm). Given this point, the process retrieves needed data to delineate a “split catchment”, returning one polygon upstream of the provided point and one downstream. These two polygons “split” the catchment polygon that defines the area that drains to the flowline in question. This split catchment can be used in conjunction with an upstream basin to provide a “precise” basin that is delineated to any provided location.

Simple map depicting a custom delineated drainage basin.

This figure is a zoomed out version of the one just above. It shows how we now have a custom delineated basin to this specific location.

Share:

Related Posts

  • The Network Linked Data Index and geoconnex.us

    May 14, 2021

    The NLDI is a search engine that uses the river network as it’s index. Like a search engine, it can cache and index new data. Beyond indexing and data discovery, it also offers some convenient data services like basin boundaries and accumulated catchment characteristics.

  • NextGen WaterAlert is out!

    October 18, 2022

    Our team is pleased to announce that the transition from Legacy WaterAlert to NextGen WaterAlert is complete! Access NextGen WaterAlert now !

    WaterAlert is a near real-time hydrologic alerting system. It can be used to set custom alerts to monitor stream, lake, and coastal conditions at USGS monitoring locations across the nation. NextGen WaterAlert is replacing a legacy version of WaterAlert which was first released in 2011. The NextGen version is the product of 12 months of user-centered design and development. Read more about the transition, feedback, and enhancements below.

  • The WDFN tech stack

    April 14, 2022

    The goal of this post is to give a technical reader an idea of what technologies the Water Data for the Nation (WDFN) team uses, because it is both varied and ever changing. There are three areas that the WDFN team focuses on, and each have their own unique tech stacks. These areas are: the Front End, for user interfaces; the Back End, for databases and APIs; and Data Engineering, where we transform the data from upstream systems and prepare it for the APIs and ultimately display.

  • Modernization of Statistical Delivery and WaterWatch Decommission

    June 10, 2025

    USGS is modernizing how statistical information is delivered through a suite of new features and products. These are replacing WaterWatch , which offered unique statistics delivery that differentiated it from the core data delivery through legacy NWISWeb. WaterWatch and Water Quality Watch are set to be decommissioned by the end of 2025 as new products become available. This blog details where you can find the statistics previously offered on WaterWatch.

  • Big changes to USGS Water Data in 2025

    May 28, 2025

    Introduction

    USGS Water Data: Big changes in 2025 banner with icons that preview the new services listed in the caption.

    Some of the new features in WDFN for 2025, including API services, explore historical water data, create a list of your favorite monitoring locations, and view latest conditions and weather events.