NLDI and Geoconnex

How the Network Linked Data Index (NLDI) relates to geoconnex.us, persistent identifiers, and hydrographic addressing.

Overview

The NLDI is a search engine that indexes data using the river network as its
organizational backbone. It supports discovery of hydrologically linked features
by indexing information to NHDPlus catchments and hydrographic network elements.

The geoconnex.us system complements the NLDI by providing persistent, public‑domain
identifiers for environmental features. These identifiers act similarly to DOIs and
can redirect clients to current authoritative locations for environmental information.

What is geoconnex.us?

Geoconnex.us is a public domain registry operated to provide persistent
identifiers for environmental features. It allows a stable URI such as:

https://geoconnex.us/usgs/monitoring-location/08279500

to redirect to a current authoritative page:

https://waterdata.usgs.gov/monitoring-location/08279500/

Because the redirect can change, geoconnex enables:

  • Long‑term stability of identifiers
  • Freedom for organizations to restructure URLs
  • Reliable linking across distributed systems

How NLDI and Geoconnex Interact

Hydrographic addressing (using reachcode and measure attributes) allows features
to be precisely located on the hydrographic network.
These addresses can be registered with geoconnex.us, and the same identifiers
can be indexed by the NLDI.

This creates a linkage between:

  • Hydrologic network indices (NLDI)
  • Persistent feature identifiers (geoconnex)
  • Authoritative data providers (e.g., waterdata.usgs.gov)

Together, the systems support persistent, discoverable environmental linked data on the internet.

Note: The Python NLDI implementation does not currently support JSON-LD responses or Link headers with geoconnex URIs. Geoconnex identifiers appear in feature properties (e.g., the mainstem field) but are not exposed through HTTP-level linked data mechanisms.

Scope Distinctions

The two systems serve distinct roles:

  • geoconnex.us is only a registry.
    It does not store or serve geospatial data.

  • The NLDI is only an index and data service.
    It does not persist data beyond hydrographic network components.

In practice, this separation allows:

  • Flexibility in how data providers manage their systems
  • Independent evolution of indexing vs. persistent identification
  • Interoperability across agencies and data platforms

Reference Gages

Reference gages serve as common, shared identifiers for stream monitoring locations used by multiple organizations.

Key points:

  • Many organizations measure data at the same real‑world location.
  • Each tends to maintain its own identifiers and spatial metadata.
  • Reference gages unify these descriptions under a shared identifier.

Using reference gages, an organization can link its data to:

  • A common geoconnex identifier
  • Authoritative provider metadata (e.g., NWIS site IDs)
  • Hydrologic network positions exposed by the NLDI

This supports cross‑platform data integration and discovery.

Example of Reference Gage Workflow

The geoconnex identifier:

https://geoconnex.us/ref/gages/1055733

Provides:

  • Provider information (e.g., USGS)
  • The provider’s identifier (e.g., an NWIS site number)
  • A link back to the authoritative monitoring location page

In turn, the authoritative site may include an “about” link back to the reference gage identifier, completing a mutual linkage between systems.

The NLDI indexes reference gages as the ref_gage feature source. You can query a reference gage directly:

https://api.water.usgs.gov/nldi/linked-data/ref_gage/1055733?f=json

The response includes provider information, the provider’s identifier, and navigation links that connect the gage to the NHDPlusV2 network.

Linking NLDI Features to Geoconnex

Many NLDI feature responses include a mainstem property whose value is a geoconnex URI (e.g., https://geoconnex.us/ref/mainstems/377002). This property links the feature’s flowline to its geoconnex mainstem identifier, bridging between NLDI network positions and the geoconnex persistent-ID system.

To discover whether a feature carries geoconnex identifiers, inspect the properties in the JSON response — no special headers or content negotiation are required.