v1.2.0

v1.2.0 is a major release. It adds two new data modules — wateruse (USGS National Water Availability Assessment Data Companion) and ngwmn (National Ground-Water Monitoring Network) — both built on a new, API-agnostic OGC engine; migrates the HTTP layer from requests to httpx (unlocking the async, auto-chunked waterdata fan-out); and unifies every module's request failures under a single DataRetrievalError exception taxonomy. It also lands the breaking changes the 1.x line had been deferring: Python 3.10+ is now required, services are accessed through their submodules rather than the flattened top-level namespace, get_samples parameters are snake_case (camelCase still accepted via a shim), and the deprecated nadp / samples shims and NWIS_Metadata.variable_info are removed. Alongside these, a large batch of reliability fixes harden the waterdata OGC getters (chunking, DST handling, error surfacing) and repair wqp / nldi / streamstats edge cases.

Breaking changes

• Require Python >=3.10 and remove the deprecated NWIS_Metadata.variable_info property by @thodson-usgs in #332
• Access services via their submodules instead of the flattened top-level namespace by @thodson-usgs in #315
• Unify request failures under a DataRetrievalError taxonomy by @thodson-usgs in #313
• Refine the error taxonomy to a lean, idiomatic form by @thodson-usgs in #319
• snake_case the get_samples parameters (camelCase kept via a shim) by @thodson-usgs in #331
• Remove the nadp module and the deprecated samples shim by @thodson-usgs in #330
• Return (df, BaseMetadata) from get_codes by @thodson-usgs in #301
• Migrate the HTTP layer from requests to httpx by @thodson-usgs in #289

New modules and features

• Add the wateruse module for USGS NWDC water-use data by @thodson-usgs in #328
• Add NGWMN getters on a shared, API-agnostic OGC engine by @thodson-usgs in #324
• Add get_cql for generalized CQL2 queries by @thodson-usgs in #284
• Add an async parallel chunker over httpx.AsyncClient by @thodson-usgs in #285
• Compact CQL2 JSON to halve the POST chunk count by @thodson-usgs in #292

Reliability and bug fixes

• Naive datetime filters shifted an hour across the DST boundary by @thodson-usgs in #307
• numpy array / Series numeric params leaked their repr into the query by @thodson-usgs in #308
• Raise RequestTooLarge for an unchunkable over-budget request instead of a silent 414 by @thodson-usgs in #309
• Preserve leading zeros on WQP code columns (HUCs, parameter codes, FIPS) by @thodson-usgs in #311
• Drop id from the wire properties so daily / continuous don't 400 by @thodson-usgs in #323
• Gate the chunked fan-out with a semaphore, not the connection pool by @thodson-usgs in #322
• get_ratings — don't abort on one bad feature, don't silently truncate by @thodson-usgs in #304
• Repair WQP_Metadata.site_info and streamstats.Watershed by @thodson-usgs in #295
• Repair WQP_Metadata.site_info (was always None) by @thodson-usgs in #305
• Return an empty GeoDataFrame instead of crashing on empty nldi results by @thodson-usgs in #302
• Coherent error handling and safe cleanups for the non-OGC getters by @thodson-usgs in #298
• Stop nwis emitting a DeprecationWarning at import time by @thodson-usgs in #300
• Small coherence cleanups (annotations, column order, defensiveness) by @thodson-usgs in #306

Docs, testing, and hygiene

• Migrate the userguide, examples, and notebooks to the Water Data API by @thodson-usgs in #290
• Python ports of the new USGS Water Data API vignettes by @thodson-usgs in #291
• Set up mypy and tighten the package to mypy --strict by @thodson-usgs in #314
• Collapse the eight wqp what_* bodies into a shared _what helper by @thodson-usgs in #320
• Unify last_modified typing and reference/build fixups by @thodson-usgs in #326
• Add AGENTS.md and switch pre-commit to ruff-only by @thodson-usgs in #293
• Point get_samples docs at get_codes(), not nonexistent *_lookup() helpers by @thodson-usgs in #303
• Drop R-analogue notes from getter docstrings by @thodson-usgs in #299
• Fix the WQP README example unpacking and stale install instructions by @thodson-usgs in #296
• Copy-edit docstrings and comments for clarity and accuracy by @thodson-usgs in #316
• Copy-edit guides and fix demo-notebook narrative/code inconsistencies by @thodson-usgs in #321
• Misc cleanups from the package review (bbox docs, nwis, empty-list) by @thodson-usgs in #312
• Unify a shared flaky-rerun marker; fix an nwis collection-time call by @thodson-usgs in #329
• Rerun flaky transient 5xx/429 from the chunked fan-out by @thodson-usgs in #325
• Mock the remaining live NWIS tests to stop the CI flakes by @thodson-usgs in #334
• Prune tautological and redundant tests by @thodson-usgs in #335
• Parametrize the wqp what_* tests and factor shared assertions by @thodson-usgs in #336
• Parametrize two clean duplicated-test clusters by @thodson-usgs in #337

Full Changelog: v1.1.5...v1.2.0

v1.1.5

v1.1.5 is a reliability-and-robustness release on the waterdata module. Multi-value queries now issue GET requests with comma-separated values, large OGC requests auto-chunk under the server's URL byte limit, and pagination failures surface loudly instead of silently truncating — alongside a cleaner single-line progress indicator and a handful of fixes across the shared utilities. No new public getters and no new module deprecations this cycle.

waterdata reliability and performance

• Use GET with comma-separated values for multi-value waterdata queries by @thodson-usgs in #233
• Auto-chunk OGC requests over the URL byte limit by @thodson-usgs in #283
• Replace per-page logger.info with a single progress line by @thodson-usgs in #288

Bug fixes

• Raise on any mid-pagination failure instead of silently truncating by @thodson-usgs in #279
• Fix silent / misleading failures in paginated waterdata pagination by @thodson-usgs in #273
• Validate monitoring_location_id format in waterdata functions by @thodson-usgs in #229
• Handle non-JSON error response bodies in _error_body by @SAY-5 in #274
• Parse Date / Time / TimeZone triplets in samples and wqp by @thodson-usgs in #272

Deprecations and removals

• Point get_gwlevels deprecation at the continuous / daily services by @thodson-usgs in #237

Docs and hygiene

• Clean up README and drop unused requirements-dev.txt by @thodson-usgs in #286
• Auto-retry live-API tests on transient upstream errors by @thodson-usgs in #277
• Fix missing comma in get_reference_table doctest example by @thodson-usgs in #275

New Contributors

• @SAY-5 made their first contribution in #274

Full Changelog: v1.1.4...v1.1.5

v1.1.4

v1.1.4 is a feature-and-cleanup release on the waterdata module: five new public getters that bring Python toward parity with the R dataRetrieval package, the formal start of the nwis deprecation (each function now emits a per-call DeprecationWarning naming its waterdata.* replacement; module removal scheduled on or after 2027-05-06), and a long tail of bug fixes across waterdata, nldi, wqp, and the shared utilities. Closes #270.

New waterdata getters

• Add waterdata.get_peaks for the annual peak-streamflow OGC collection by @thodson-usgs in #267
• Add waterdata.get_ratings for USGS stage-discharge ratings via STAC by @thodson-usgs in #269
• Add waterdata.get_field_measurements_metadata by @thodson-usgs in #268
• Add waterdata.get_combined_metadata for combined location + time-series inventory by @thodson-usgs in #264
• Add waterdata.get_samples_summary for per-location sample inventory by @thodson-usgs in #262
• Add waterdata.get_nearest_continuous helper by @thodson-usgs in #239
• Add CQL filter / filter_lang passthrough to OGC waterdata getters by @thodson-usgs in #238
• Isolate the filter feature behind a clean rollback flag; flag lex-comparison pitfall by @thodson-usgs in #240

Deprecations and removals

• Deprecate remaining active nwis functions ahead of 2027-05-06 removal by @thodson-usgs in #271
• Deprecate nadp module ahead of 2026-11-01 removal by @thodson-usgs in #243
• Remove waterwatch module by @thodson-usgs in #228
• Simplify defunct stubs and fix O(n²) pagination concats by @thodson-usgs in #225

Bug fixes

• Fix _arrange_cols: stop mutating the caller's properties list by @thodson-usgs in #254
• waterdata.get_stats_data: preserve geometry across continuation pages by @thodson-usgs in #255
• Fix _format_api_dates: parse ISO 8601 datetimes by @thodson-usgs in #247
• Fix nldi: validate data source on every call, not just cache-miss by @thodson-usgs in #246
• nldi: fix several user-visible bugs in get_features, get_flowlines, search by @thodson-usgs in #252
• nldi: raise ValueError (not TypeError) for invalid navigation mode by @thodson-usgs in #258
• Polish wqp.py: silence prints, fix exception shape, fix typos by @thodson-usgs in #256
• Fix wqp.get_results: preserve user-supplied WQX3.0 dataProfile by @thodson-usgs in #250
• Fix get_reference_table: propagate limit to query args by @thodson-usgs in #248
• Make _handle_stats_nesting tolerant of missing drop columns by @thodson-usgs in #257
• Fix IndexError in _read_rdb when NWIS returns no data rows by @thodson-usgs in #227

Docs and hygiene

• Enrich waterdata getter docstrings with examples adapted from R by @thodson-usgs in #265
• Bump geopandas in dev requirements to 1.1.2 to remediate GHSA-6497-prx7-gpmq by @Copilot in #235
• Use PEP 639 SPDX license identifier in pyproject.toml by @thodson-usgs in #226
• Skip NADP live-API tests (module deprecated) by @thodson-usgs in #259

New Contributors

• @Copilot made their first contribution in #235

Full Changelog: v1.1.3...v1.1.4

v1.1.3

What's Changed

• Query params for get_reference_table by @jessamynsmith in #214
• Add stats service by @ehinman in #207
• Add channel measurement endpoint by @ldecicco-USGS in #218
• Lint and format all files with ruff by @nodohs in #219
• Add pandas 3x, legacy xfails, and samples API key by @thodson-usgs in #221
• Remove Defunct NWIS Functions by @thodson-usgs in #222
• Stabilize NWIS Tests and Improve 5xx Error Handling by @thodson-usgs in #223
• Small cleanups: idiomatic Python and a precedence fix by @thodson-usgs in #224

New Contributors

• @jessamynsmith made their first contribution in #214
• @ldecicco-USGS made their first contribution in #218

Full Changelog: v1.1.2...v1.1.3

v1.1.2

What's Changed

• Restrict pandas 3.0.0 by @nodohs in #212 : <3.0.0 is fine, but we also want to specify that pandas should be at least 2.+. In a future release, we may include 3.0.0 as well, but this is a quick fix to get the new features available on conda-forge.

New Contributors

• @nodohs made their first contribution in #212

Full Changelog: v1.1.1...v1.1.2

v1.1.1

What's Changed

• Update README.md imports by @thodson-usgs in #193
• Change limit to 50000 by @ehinman in #197
• Set waterdata data types by @thodson-usgs in #195
• Add continuous endpoint by @ehinman in #199
• Add row ordering by time and monitoring_location_id, if applicable, plus... by @ehinman in #203
• Add py.typed by @davetapley in #186
• add reference tables function by @ehinman in #205
• Add waterdata demo by @ehinman in #208
• Make ref table function way simpler and more efficient by @ehinman in #209

Full Changelog: v1.1.0...v1.1.1

v1.1.0

🎊 New waterdata module added 🎊

This module provides access to USGS's modernized Water Data APIs, serving information such as monitoring location info, daily values, field measurements, timeseries metadata, latest continuous and daily data values, discrete water quality data, and more. Please give the new functions a try and provide feedback via issues.

What's Changed

• Fix gwlevels pcode by @ehinman in #180
• Remove qwdata documentation, tests, etc. and replace with waterdata.get_samples() by @ehinman in #178
• Add waterdata infrastructure by @ehinman in #183
• Fix pathing so new waterdata documentation is available by @ehinman in #189
• Another attempt to fix documentation issues by @ehinman in #190
• Get rid of NLDI import by @ehinman in #191
• Combine two lines of strings by @ehinman in #192

Full Changelog: v1.0.12...v1.1.0

v1.0.12

What's Changed

• Add new module samples.py that introduces the new get_usgs_samples() and get_codes() functions by @ehinman and @thodson-usgs in #173

Full Changelog: v1.0.11...v1.0.12

v1.0.11

Warning

v1.0.10 assigned the incorrect datum to gage location data (#169).
The default datum has been changed to EPSG:4269 (NAD 83), even though some gages still use other datums.

What's Changed

• Add NAQWA data pull demo by @kjdoore in #151
• Remove hardcoded format in nwis.get_discharge_measurements by @thodson-usgs in #150
• Rename, fix, and extend NAWQA (NWQN) demo by @thodson-usgs in #153
• Adjust code.json to point to new repo location by @ehinman in #156
• Update maintainers by @thodson-usgs in #159
• Add info about gwlevels service by @ehinman in #160
• Update README.md with some badges by @thodson-usgs in #161
• First crack at changing the url for one function by @ehinman in #152
• Lint and format by @thodson-usgs in #164
• Update code.json to include both dev and official versions by @ehinman in #165
• [#157] Example notebook for NLDI data access by @pkdash in #158
• update nldi service urls by @dblodgett-usgs in #167
• Update GH action tags to most recent release commit hashes by @jzemmels in #168
• fix!: correct nwis module GeoDataFrames crs to EPSG:4269 (NAD 83) by @aaraney in #169

New Contributors

• @kjdoore made their first contribution in #151
• @dblodgett-usgs made their first contribution in #167
• @jzemmels made their first contribution in #168
• @aaraney made their first contribution in #169

Full Changelog: v1.0.10...v1.0.11

v1.0.10

What's Changed

• update(nldi.py): Add CRS information to GeoDataFame objects by @jlarsen-usgs in #142
• Remove coveralls link by @thodson-usgs in #145
• feat(geopandas support): return GeoDataFrame if geopandas is installed by @jlarsen-usgs in #143
• Adjust gwlevels URL services by @ehinman in #147 - adjusted due to discontinuation of GW levels RDB/WaterML2 endpoints, which caused breaking changes to the gwlevels service. See Water Data for the Nation blog post for more information.

New Contributors

• @jlarsen-usgs made their first contribution in #142

Full Changelog: v1.0.9...v1.0.10