Release Notes

This release introduces a dedicated ogcapi module that consolidates all OGC API-based web service clients under a single, extensible framework. The module exposes a new OGCAPIBase base class that handles pagination, CQL filtering, geometry queries, feature ID lookups, bounding-box queries, User-Agent identification, optional API-key injection, and automatic cache eviction for error responses. The existing GeoConnex and FabricData classes have been refactored to inherit from OGCAPIBase, and a new NWIS class has been added to access the USGS Water Data OGC API (https://api.waterdata.usgs.gov/ogcapi/v0) as USGS migrates its services to the OGC API standard.

New Features

• Add NWIS class for accessing the new USGS Water Data OGC API (https://api.waterdata.usgs.gov/ogcapi/v0). USGS is migrating its web services to the OGC API standard; this class provides access to monitoring locations, daily/continuous observations, field/channel measurements, and reference code tables. The class reads the USGS_API_KEY environment variable automatically for higher rate limits.
• Add NLDI.get_characteristics_byid method for retrieving local, total, or divergence-routed catchment characteristics for a specific feature directly from the NLDI API.
• Add trim_tolerance parameter to NLDI.navigate_byid and NLDI.navigate_bybox for controlling how aggressively the first flowline is trimmed when trim_start=True.
• Add StreamCat.changelog, StreamCat.data_dictionary, and StreamCat.all_metrics_bycomid methods to expose additional StreamCat API endpoints.

Internal Changes

• Move GeoConnex and FabricData from core to the new dedicated ogcapi module alongside the new NWIS class.
• Introduce OGCAPIBase as a reusable base class for all OGC API services. GeoConnex, FabricData, and NWIS now inherit from it, making it straightforward to add further OGC API-based services.
• OGCAPIBase now sends a User-Agent header (pynhd/<version>) on every request so API providers can identify traffic from HyRiver.
• FabricData and NWIS read the USGS_API_KEY environment variable when no explicit api_key is passed.
• Error responses (e.g., rate-limit or server errors) are automatically evicted from the HTTP cache so they do not persist across retries.
• Fix type annotations across core, network_tools, nhdplus_derived, ogcapi, pygeoapi, and pynhd modules to pass strict Pyright type-checking.

Release Notes

New Features

• Add the development version of the NLDI web service to the NLDI class. This version is not stable and is intended for testing purposes only. The default version is still the production version.

Bug Fixes

• Fix the issue with normalizing variables in streamcat functionc caused by changes in the StreamCat web service.

Release Notes

Internal Changes

• Use orjson instead of ujson due to the package not being maintained anymore. The developer of ujson raised conrcerns about security vulnerabilities and recommended using orjson instead.
• Create two new modules called nldi and pygeoapi for better organization of the codebase.

Release Notes

Breaking Changes

• Remove NLDI.getcharacteristic_byid method since its endpoint will be removed from the NLDI service. The characteristics can still be accessed via the NLDI.get_characteristics method and only requires specifying the characteristic names and optionally the NHDPlus ComIDs. This method calls the pynhd.nhdplus_attrs_s3 function internally.
• Switch to using the new StreamCat web service link. While the public API of the pynhd.streamcat function did not change the web service itself might return different results and metrics names have been changed. Thus, this change might affect the results of the function and is considered a breaking change.

New Features

• Add a new optional argument to pynhd.nhdplus_attrs_s3 to pass a PyArrow Expression for filtering the query.

Internal Changes

• Switch to using the new NLDI web service link. Note that NLDI web service now has a rate limit of 3600 requests per hour per IP.

Release Notes

New Features

• Replace the links to NLDI and PyGeoAPI web services to their new URLs.
• Add two new methods to GeoConnex class for querying bybox and byfilter. Note that CQL query is still not working due to an issue with the GeoConnex service. For now, it's recommended to use the byfilter method for most of the queries, including spatial queries. For simple spatial queries, you can use the bybox method then filter the results based on the actual geometry.

Breaking Changes

• Drop support for Python 3.8 since its end-of-life date is October 2024.
• Remove all exceptions from the main module and raise them from the exceptions module. This is to declutter the public API and make it easier to maintain.

Release Notes

Internal Changes

• Drop support for Python 3.8 since its end-of-life date is October 2024.

Release Notes

New Features

• The function pynhd.streamcat now can be called without any arguments to get a dataframe of all available metrics and their descriptions.

Internal Changes

• Add the exceptions module to the high-level API to declutter the main module. In the future, all exceptions will be raised from this module and not from the main module. For now, the exceptions are raised from both modules for backward compatibility.
• Switch to using the src layout instead of the flat layout for the package structure. This is to make the package more maintainable and to avoid any potential conflicts with other packages.
• Add artifact attestations to the release workflow.

Release Notes

New Features

• Add support for LakeCat dataset in streamcat function. A new argument called lakes_only is added to the function. If set to True, only metrics for lake and their associated catchments will be returned. The default is False to retain backward compatibility.

Bug Fixes

• Modify HP3D class based on the latest changes to the 3D Hydrography Program service. Hydrolocation layer has now three sub-layers:
  • hydrolocation_waterbody for Sink, Spring, Waterbody Outlet,
  • hydrolocation_flowline for Headwater, Terminus, Divergence, Confluence, Catchment Outlet,
  • hydrolocation_reach for Reach Code, External Connection.

Breaking Changes

• EPA's HMS no longer supports the StreamCat dataset, since they have a dedicated service for it. Thus, the epa_nhd_catchments function no longer accepts "streamcat" as an input for the feature argument. For all StreamCat queries, use the streamcat function instead. Now, the epa_nhd_catchments function is essentially useful for getting Curve Number data.

Release Notes

Bug Fixes

• In NLDI.get_basins, the indices used to be station IDs but in the previous release they were reset by mistake. This version retains the correct indices.

New Features

• In nhdplus_l48 function, when the layer is NHDFlowline_Network or NHDFlowline_NonNetwork, merge all MultiLineString geometries to LineString.

Release Notes

Bug Fixes

• Fix an issue in network_xsection and flowline_xsection related to the changes in shapely 2 API. Now, these functions should return the correct cross-sections.