Overview

The USGS National Hydrologic Geospatial Fabric (NHGF) exposes its vector geospatial layers through a pygeoapi server at https://api.water.usgs.gov/fabric/pygeoapi. The service provides the spatial backbone of the NHGF — stream networks, catchments, waterbodies, hydrologic unit boundaries, and reference gage locations — all queryable over standard HTTP.

It implements two complementary OGC API standards:

• OGC API – Features — query and retrieve vector geospatial features (points, lines, polygons) as GeoJSON. This is the primary interface for data access.
• OGC API – Tiles — access pre-rendered Mapbox Vector Tiles (MVT) for performant map display at multiple zoom levels.

If you are new to OGC API: it is a family of RESTful standards that replace older OGC services (WMS, WFS, WCS) with modern JSON/HTTP patterns. Every endpoint returns standard JSON by default and supports content negotiation via a ?f= parameter — more on that below .

This service replaces the legacy GeoServer WFS at https://api.water.usgs.gov/geoserver/wmadata/ows, which is being retired. See Migration from Legacy GeoServer for details.

Available Collections

The service hosts 19 feature collections organized into four groups. Browse the full list at /collections .

NHDPlusV2 Hydrography

The NHDPlusV2 is a national dataset of stream flowlines, catchment boundaries, and waterbodies used as the spatial framework for USGS hydrologic modeling and analysis.

Connecting to the NLDI: The comid attribute in these collections is the same identifier used by the NLDI to index features to the hydrologic network. If the NLDI returns a comid, you can retrieve the corresponding geometry here — for example, /collections/nhdflowline_network/items?comid=13297246 or /collections/catchmentsp/items?comid=13297246. See Connecting Fabric Data to the NLDI for a walkthrough.

Gages-II Reference Gages

The GAGES-II dataset provides locations and drainage basin delineations for streamgages across the United States.

NHDPlusV2 Hydrologic Units

Hydrologic units are standardized watershed boundaries organized in a nested hierarchy from large regions (HUC2) down to small sub-watersheds (HUC12). These collections are derived from the NHDPlusV2 snapshot of the Watershed Boundary Dataset (WBD).

NHDPlusHR Hydrologic Units

The same six hydrologic unit levels sourced from the higher-resolution NHDPlusHR dataset, which includes Alaska and U.S. territories beyond CONUS.

Querying Features

Listing and Retrieving Items

Request features from any collection as a paginated GeoJSON FeatureCollection:

GET /collections/{collectionId}/items

Results are paginated. Use the limit parameter to control page size and follow the next link in the response to retrieve additional pages. To retrieve a single feature by its server-assigned ID:

GET /collections/{collectionId}/items/{featureId}

Filtering with Queryables

Each collection exposes filterable properties at its queryables endpoint. For example, see the flowline network queryables for the full list of available filters.

Filter by appending query parameters:

/collections/nhdflowline_network/items?comid=13297246
/collections/nhdflowline_network/items?gnis_name=Connecticut%20River
/collections/nhdplusv2-huc08/items?huc8=01080205

Bounding Box Queries

Use the bbox parameter to retrieve features within a geographic extent (min longitude, min latitude, max longitude, max latitude):

/collections/nhdflowline_network/items?bbox=-73.5,42.0,-72.5,43.0

Coordinate Reference Systems

The service supports CRS negotiation per OGC API – Features Part 2 . The default storage CRS is NAD83. Use the crs parameter to request output in a different coordinate reference system. Supported CRS options are listed in each collection’s metadata.

Vector Tiles

Collections also expose Mapbox Vector Tile (MVT) tilesets for use in web mapping libraries such as MapLibre GL JS, Mapbox GL JS, or OpenLayers.

Tile URL pattern:

/collections/{collectionId}/tiles/{tileMatrixSetId}/{z}/{y}/{x}

Tileset metadata (available matrix sets and zoom levels) is at:

/collections/{collectionId}/tiles

Use vector tiles when you need to display features on an interactive map without downloading full GeoJSON datasets. Note that tiles may not include all attributes available through the Features interface — use Features queries when you need the complete attribute set.

Connecting Fabric Data to the NLDI

The NLDI uses NHDPlusV2 comid values as its spatial backbone. Every feature in the NLDI is indexed to a catchment and its associated flowline via comid. This means you can move between the two services:

1. NLDI → Fabric: Use the NLDI to navigate the network (e.g., find all flowlines upstream of a gage), then query Fabric for the corresponding catchment or waterbody geometries using the comid values from the NLDI response.

2. Fabric → NLDI: Start with a spatial query in Fabric (e.g., flowlines in a bounding box), then use the returned comid values to look up linked data sources in the NLDI (gages, water quality sites, etc.) via /linked-data/comid/{comid}.

Client Libraries

For routine data access, consider using a high-level client library instead of constructing raw HTTP requests:

• Python — HyRiver: docs.hyriver.io — a suite of Python packages for accessing NHDPlus data, WBD boundaries, and other hydrologic datasets. The PyNHD package specifically wraps NHDPlusV2 and NLDI queries.

• R — nhdplusTools: doi-usgs.github.io/nhdplusTools — provides functions for NHDPlus data access, network navigation, and watershed analysis.

These libraries handle pagination, CRS details, and response parsing. Use the raw OGC API endpoints for custom queries, integration work, or languages without a dedicated client.

Using the Built-In Developer Tools

The HTML views that pygeoapi generates are not a user interface — they are browser-based API introspection tools intended for developers during integration and testing. They render the same data the JSON API returns, formatted for human reading.

Every endpoint supports a ?f= parameter for content negotiation:

• ?f=json — GeoJSON (default for programmatic access)
• ?f=jsonld — JSON-LD (linked data format)
• ?f=html — human-readable HTML view (auto-generated by pygeoapi)

Useful developer entry points:

• Swagger UI — /openapi?f=html — interactive endpoint testing; try queries and inspect request/response shapes
• HTML collection browser — append ?f=html to any endpoint (e.g., /collections/nhdflowline_network?f=html ) to browse metadata and available query options
• Queryables viewer — /collections/nhdflowline_network/queryables?f=html — see all filterable properties for a collection

Key Endpoints

All paths are relative to https://api.water.usgs.gov/fabric/pygeoapi.

Migration from Legacy GeoServer

The legacy GeoServer WFS at https://api.water.usgs.gov/geoserver/wmadata/ows served the same core data as 15 WFS layers (NHDPlusV2 hydrography, gagesii, and WBD layers with date-stamped names like wbd02_20201006). That service is being retired.

Key differences in the Fabric pygeoapi replacement:

• RESTful JSON instead of XML-based WFS GetFeature requests
• Stable collection IDs without date stamps (e.g., nhdplusv2-huc08 instead of wbd08_20201006)
• Vector tile support for web mapping use cases
• Queryables-based filtering instead of CQL/OGC filter encoding
• NHDPlusHR hydrologic units added (not available in the legacy service)

Notes & TODOs

• TODO: Add example query URLs with concrete parameter values for each collection group
• TODO: Verify vector tile matrix set IDs and supported zoom levels
• TODO: Add a worked example showing the NLDI-to-Fabric comid lookup workflow with actual response snippets
• TODO: Cross-link to notebooks once authored
• TODO: Document any rate limits or pagination maximums