pyNWIS

A lightweight Python toolkit for downloading, processing, and filtering
USGS National Water Information System (NWIS) daily water data.

✨ Features

🚀 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"] and min_records=100 to keep only sites that have at least 100 suspended-sediment records.

📋 Common Parameter Codes

Tip: Call get_usgs_parameters() for the full built-in catalog, or use search_parameters() to find codes by keyword.

📚 API Reference

Core Functions

Parameter Utilities

🤝 Contributing

1. Fork the repo
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m "Add amazing feature"
4. Push: git push origin feature/amazing-feature
5. Open a Pull Request

📄 License

MIT License — see LICENSE for details.

🙏 Acknowledgments

Built on the USGS Water Services API.