pyNWIS
A lightweight Python toolkit for downloading, processing, and filtering
USGS National Water Information System (NWIS) daily water data.
✨ Features
| Feature | Description |
|---|---|
| 📡 Daily Value Fetching | Download daily values from the USGS NWIS API with automatic retries and rate-limit handling |
| 📦 Batch Downloads | Fetch data for hundreds of sites at once with progress bars |
| 🧹 Tidy DataFrames | Convert raw JSON responses into clean Pandas DataFrames |
| 🔍 Parameter Search | Built-in catalog of 30+ common USGS parameter codes with keyword search |
| 🎯 Smart Filtering | Keep only sites with sufficient data for your required variables |
🚀 Installation
pip install pynwis
Or install from source:
git clone https://github.com/Bluerrror/NWIS-Data-Downloader.git
cd NWIS-Data-Downloader
pip install -e .
Requirements: Python ≥ 3.8 | requests | pandas | tqdm
📖 Quick Start
1. Fetch discharge data for a single site
from pynwis import fetch_usgs_daily, usgs_json_to_df
json_data = fetch_usgs_daily(
sites=["01491000"],
parameter_codes=["00060"], # Discharge (ft³/s)
start="2024-01-01",
end="2024-12-31",
)
df = usgs_json_to_df(json_data)
print(df.head())
# site_no time 00060
# 0 01491000 2024-01-01 222.0
# 1 01491000 2024-01-02 201.0
# 2 01491000 2024-01-03 187.0
2. Search the parameter catalog
from pynwis import get_usgs_parameters, search_parameters
params = get_usgs_parameters()
print(params.head())
# parm_cd group parameter_nm parameter_unit
# 0 00010 Physical Temperature, water, degrees Celsius deg C
# 1 00020 Physical Temperature, air, degrees Celsius deg C
# Find sediment-related parameters
results = search_parameters(params, "sediment")
print(results[["parm_cd", "parameter_nm"]])
# parm_cd parameter_nm
# 0 80154 Suspended sediment concentration, mg/L
# 1 80155 Suspended sediment discharge, short tons per day
# 2 80225 Bedload sediment discharge, short tons per day
3. Batch download for multiple sites
from pynwis import fetch_batch_usgs_data
sites = ["01491000", "01646500", "09522500"]
df = fetch_batch_usgs_data(
sites=sites,
parameter_codes=["00060"], # Discharge
start="2020-01-01",
)
print(df.shape)
print(df.head())
Tip: Use
required_params=["80154"]andmin_records=100to keep only sites that have at least 100 suspended-sediment records.
📋 Common Parameter Codes
| Code | Name | Description | Units |
|---|---|---|---|
00010 |
Temperature | Water temperature | °C |
00060 |
Discharge | Streamflow discharge | ft³/s |
00065 |
Gage Height | Gage height | ft |
00045 |
Precipitation | Precipitation depth | in |
00400 |
pH | pH value | std units |
00300 |
Dissolved O₂ | Dissolved oxygen | mg/L |
00630 |
NO₃ + NO₂ | Nitrate plus nitrite | mg/L as N |
80154 |
SSC | Suspended sediment concentration | mg/L |
80155 |
SS Discharge | Suspended sediment discharge | tons/day |
Tip: Call
get_usgs_parameters()for the full built-in catalog, or usesearch_parameters()to find codes by keyword.
📚 API Reference
Core Functions
| Function | Description |
|---|---|
fetch_usgs_daily(sites, parameter_codes, ...) |
Fetch raw NWIS daily-values JSON for one or more sites |
usgs_json_to_df(json_data) |
Convert NWIS JSON response into a tidy DataFrame |
fetch_batch_usgs_data(sites, parameter_codes, ...) |
Batch fetch with progress bars, retries, and filtering |
Parameter Utilities
| Function | Description |
|---|---|
get_usgs_parameters() |
Return the built-in catalog of common parameter codes |
search_parameters(params_df, query, ...) |
Search parameters by keyword |
🤝 Contributing
- Fork the repo
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit changes:
git commit -m "Add amazing feature" - Push:
git push origin feature/amazing-feature - Open a Pull Request
📄 License
MIT License — see LICENSE for details.
🙏 Acknowledgments
Built on the USGS Water Services API.
Metadata
Release files for pynwis 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pynwis-0.1.2.tar.gz | 12.1 kB | Without provenance | Details for pynwis-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pynwis-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for pynwis-0.1.2-py3-none-any.whl |
Total release size: 21.8 kB
Release files / pynwis-0.1.2.tar.gz
| Download URL | pynwis-0.1.2.tar.gz |
|---|---|
| Size | 12.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5c016f3dff7e392b502a8a9c01e6dad89c8ad9152b27e2d32a2895384132a66a
|
|
BLAKE2b-256 checksum How to use checksums |
cad38b94f538cca271fe6d5605a2df3a0115c70479e1c7b5b704733daf400ef6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / pynwis-0.1.2-py3-none-any.whl
| Download URL | pynwis-0.1.2-py3-none-any.whl |
|---|---|
| Size | 9.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
32b1550bf212c50bd9c74263e04e5ece5467cf6bf48eb7aa0862fea5fbde5ddd
|
|
BLAKE2b-256 checksum How to use checksums |
15427967817d5aa9969e8b80aef8a1480429f454a1505ac933f8fbbefe9936ec
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Security for pynwis 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.