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.