Skip to content

What's New

The notes of each GitHub release.

v0.2.0 - 2026-11-14

NWIS is now WaterData, in both water_ogcapi and water_ogcapi.aio, with no alias left behind: replace the name in imports and constructors when upgrading. The new WaterDataSTAC class queries the USGS Water Data STAC API, reads its key from USGS_STAC_API_KEY with USGS_API_KEY as the fallback, and splits a site list longer than 50 into concurrent pieces. Python 3.12 is now supported. A query split into pieces refuses offset with ValidationError, and iter_pages() is typed as a generator, so calling close() on it type-checks.

Added

  • Support Python 3.12 (0aaec86)
  • Give WaterDataSTAC its own key variable and site splitting (bcfe1bb)
  • Add WaterDataSTAC for the Water Data STAC API (b751560)
  • Rename NWIS to WaterData with no deprecation release (breaking) (b219366)

Fixed

  • Type iter_pages as a generator so callers can close it (d350fa1)
  • Send a query with an empty in-list whole (76aff88)
  • Merge equal numbers when deduping a split in-list (5a44789)
  • Refuse an offset on a query split into pieces (a797152)

v0.1.0 - 2026-11-04

First final release of water-ogcapi, a Python client for USGS water data over OGC API Features, blocking by default with async twins in water_ogcapi.aio. It follows next links on NWIS, FabricData, and GeoConnex, splits an NWIS query into concurrent pieces on request, spaces requests as a service's quota runs down, and resumes a failed query from a checkpoint. Since v0.1.0rc1, requests send a water-ogcapi User-Agent, a 2xx in a coding httpx2 cannot decode raises, and Transport bounds requests per host (max_per_origin=4) and in total (max_concurrent=16), so a caller who set max_concurrent above 4 for one host also sets max_per_origin. Checked against NWIS API 1.11.2, FabricData 0.25.dev0, and GeoConnex 0.24.dev0.

Added

  • Let a download keep the server's modification time in #207
  • Let a check refuse a download before it replaces the file in #206
  • Let a download keep the error text of a query it built in #205
  • Bound requests in flight per origin and in total in #204
  • Let one call set its own timeout in #203
  • Send a water-ogcapi User-Agent by default in #190
  • Add a user_agent keyword to Transport in #173
  • Take numbers and booleans as transport query values (364c0a5)
  • Decode a response body with Response.text() (b45d7b8)
  • Export Response and Download (42c39ef)
  • Let one call set its own retries (4241125)
  • Add Client.run to run a coroutine on the background loop in #171
  • Add a blocking HTTP Client in #160
  • Stream a download to a file, following redirects (8c15618)
  • Keep the body of an error response in ServiceError in #158
  • Convert a single page to an Arrow table in #149
  • Pickle a service that has sent requests in #142
  • Write any pyproj-readable CRS as GeoArrow PROJJSON, x first (a0e954e)
  • Convert a QueryResult to an Arrow table (4b283fe)
  • Read a repeated feature id as unknown (f419df8)
  • Split NWIS queries and run the pieces concurrently (988d9e9)
  • Resume a query from a Checkpoint (09fb724)
  • Pace requests with a quota governor (31a9a2b)
  • Make the blocking classes the top-level names (e502b2b)
  • Check queries against cached metadata before sending (3770e63)
  • Raise ValidationError for invalid caller input (c4c736a)
  • Cache metadata documents with ETag revalidation (e1b029f)
  • Add the blocking sync API in water_ogcapi.sync (85376e1)
  • Add the GeoConnex service class in #91
  • Export Transport in #90
  • Add the FabricData service class (5ef6dce)
  • Add the NWIS service class (a121bf5)
  • Add service profiles with default and maximum page sizes in #88
  • Add identifier filters and item fetch in #80
  • Add CQL2-Text and CQL2-JSON filter keyword in #79
  • Add bbox and geometry query keywords in #78
  • Add Transport.request and carry method and body on errors (44ea23e)
  • Record CRS provenance in QueryResult (5706d43)
  • Add collect() with PartialResultsError and completeness checks (cea6890)
  • Add iter_pages() with next-link pagination (92e34d5)
  • Add the OGCService base client (b888853)
  • Add collection metadata models that keep every member in #67
  • Add Page and QueryResult with credential redaction (fd36bc7)
  • Log transport retries and completed requests (b5453a0)
  • Add the package logger and configure_logger() (96cddad)
  • Add the async HTTP transport (157d4eb)
  • Add the exception hierarchy (f7f879c)

Changed

  • Validate against the parsed queryables only (eb68272)
  • Encode CQL2-JSON filters without a custom encoder (5474806)
  • Drop the unused limit stop reason (bfa34d6)
  • Refetch expired metadata without conditional requests (c8ee546)
  • Refuse a name the cached metadata lacks without refetching (104cb12)
  • Share held features when collect() resumes (9b18f8f)
  • Rename Crs and CrsSource to CRS and CRSSource in #107
  • Move response parsing out of _client.py (ae3f2dd)
  • Raise on a page without a body in collect() (3a97d07)
  • Build items requests in _query.py behind a _pieces() seam in #93
  • Route iter_pages through a method-aware traversal in #75

Fixed

  • Sum a split query's count over its pieces in #214
  • Expose profile on the blocking services (3ed9f20)
  • Refuse a timeout, total, or backoff that is not a usable number (ec8448b)
  • Read a response's rate-limit headers as they arrive (f883f90)
  • Book a governor slot only once both permits are held (b2ce4ee)
  • Await a download check that returns an awaitable (c61d206)
  • Book a governor slot only once the origin permit is held (df510f0)
  • Keep the status of an error whose body fails to read in #202
  • Keep URL credentials out of caller-built objects in #201
  • Refuse a URL whose authority does not parse in #200
  • Raise on a 2xx whose Content-Encoding httpx2 cannot decode in #191
  • Keep guide scripts from shadowing the modules they import (e49a1c7)
  • Name the missing arrow extra before reading the document in #180
  • Refuse userinfo in an OGCService base_url in #179
  • Keep URL userinfo out of Response.url (5d36ed3)
  • Log download retries and completions as docs/logging.md says (5d47674)
  • Convert service query values as the transport sends them (e910595)
  • Keep URL userinfo out of request log records in #159
  • Refuse non-str URLs, names, and values in credential checks in #143
  • Check the params copy a Request stores in #141
  • Check the params copy Transport.request() sends (014d415)
  • Validate the params copy the request sends (50d0d19)
  • Close a call's coroutine when the loop has already stopped in #135
  • Raise when the background loop thread has stopped (9fab181)
  • Refuse a blocking call made on the background loop (3e93eea)
  • Leave the API key out of a pickled NWIS service (4240061)
  • Refuse pages with credential links and mixed counts (875fe29)
  • Bind aio and exceptions on a plain import in #106
  • Send the header snapshot that passed the check on every attempt in #96
  • Refuse a header value that is not printable ASCII (2d7546d)
  • Mask credentials in a ServiceError URL in #94
  • Resolve a relative next link against its page (a6c572e)
  • Refuse a collection name that addresses another path (d7dfeea)
  • Refuse a collection index without a collections list (f52d564)
  • Keep hpack's debug log from recording the API key in #89
  • Record the requested sort key in Pagination.sort_by (ac7dd24)
  • Report the attempts behind a response that fails validation (d3f11af)
  • Send every service request through one origin-checked method (9acc546)
  • Split a repeated Content-Crs header into its values in #74
  • Read the requested crs from the request as sent (55685c3)
  • Leave a crs request no page confirmed out of the effective CRS (e831ad9)
  • List a passing count check whatever the completeness verdict in #73
  • Treat a next link back to the first request as a repeat (7d14b39)
  • Read a malformed page count as unknown completeness (3c9b7cf)
  • Report a next link carrying a credential as a page failure (8974def)
  • Keep PartialResultsError's result through copy and pickle (7aa6cc4)
  • Read a page that returned fewer features than it reported as unknown (b6aef45)
  • Stop a traversal at a repeated next link (8aae4a0)
  • Fail a page that is not a FeatureCollection with sound links (7247a1f)
  • Report a failed request by the URL as sent (bfd94af)
  • Lint untracked files that pre-commit skips in #71
  • Keep result mappings read-only dicts and reject raw links (82468e4)
  • Lock typing-extensions so the 3.15 release candidate passes --locked in #62
  • Require h2 4.4.1 to exclude two request-smuggling advisories (483b816)
  • Keep the API key out of redirect errors (f95010a)
  • Reject a key after a semicolon in the query string (76a3156)
  • Keep the URL query when get() is given params in #49

v0.1.0rc1 - 2026-10-09 (pre-release)

Release candidate that reserves the water-ogcapi name on PyPI. It holds the async transport and the result types, and has no query API yet. Install from the GitHub repository until the first final release.