Agent skill

usgs-data-download

Download water level data from USGS using the dataretrieval package. Use when accessing real-time or historical streamflow data, downloading gage height or discharge measurements, or working with USGS station IDs.

Stars 897
Forks 232

Install this agent skill to your Project

npx add-skill https://github.com/benchflow-ai/skillsbench/tree/main/tasks/flood-risk-analysis/environment/skills/usgs-data-download

SKILL.md

USGS Data Download Guide

Overview

This guide covers downloading water level data from USGS using the dataretrieval Python package. USGS maintains thousands of stream gages across the United States that record water levels at 15-minute intervals.

Installation

bash
pip install dataretrieval

nwis Module (Recommended)

The NWIS module is reliable and straightforward for accessing gage height data.

python
from dataretrieval import nwis

# Get instantaneous values (15-min intervals)
df, meta = nwis.get_iv(
    sites='<station_id>',
    start='<start_date>',
    end='<end_date>',
    parameterCd='00065'
)

# Get daily values
df, meta = nwis.get_dv(
    sites='<station_id>',
    start='<start_date>',
    end='<end_date>',
    parameterCd='00060'
)

# Get site information
info, meta = nwis.get_info(sites='<station_id>')

Parameter Codes

Code Parameter Unit Description
00065 Gage height feet Water level above datum
00060 Discharge cfs Streamflow volume

nwis Module Functions

Function Description Data Frequency
nwis.get_iv() Instantaneous values ~15 minutes
nwis.get_dv() Daily values Daily
nwis.get_info() Site information N/A
nwis.get_stats() Statistical summaries N/A
nwis.get_peaks() Annual peak discharge Annual

Returned DataFrame Structure

The DataFrame has a datetime index and these columns:

Column Description
site_no Station ID
00065 Water level value
00065_cd Quality code (can ignore)

Downloading Multiple Stations

python
from dataretrieval import nwis

station_ids = ['<id_1>', '<id_2>', '<id_3>']
all_data = {}

for site_id in station_ids:
    try:
        df, meta = nwis.get_iv(
            sites=site_id,
            start='<start_date>',
            end='<end_date>',
            parameterCd='00065'
        )
        if len(df) > 0:
            all_data[site_id] = df
    except Exception as e:
        print(f"Failed to download {site_id}: {e}")

print(f"Successfully downloaded: {len(all_data)} stations")

Extracting the Value Column

python
# Find the gage height column (excludes quality code column)
gage_col = [c for c in df.columns if '00065' in str(c) and '_cd' not in str(c)]

if gage_col:
    water_levels = df[gage_col[0]]
    print(water_levels.head())

Common Issues

Issue Cause Solution
Empty DataFrame Station has no data for date range Try different dates or use get_iv()
get_dv() returns empty No daily gage height data Use get_iv() and aggregate
Connection error Network issue Wrap in try/except, retry
Rate limited Too many requests Add delays between requests

Best Practices

  • Always wrap API calls in try/except for failed downloads
  • Check len(df) > 0 before processing
  • Station IDs are 8-digit strings with leading zeros (e.g., '04119000')
  • Use get_iv() for gage height, as daily data is often unavailable
  • Filter columns to exclude quality code columns (_cd)
  • Break up large requests into smaller time periods to avoid timeouts

Expand your agent's capabilities with these related and highly-rated skills.

benchflow-ai/skillsbench

csv-processing

Use this skill when reading sensor data from CSV files, writing simulation results to CSV, processing time-series data with pandas, or handling missing values in datasets.

897 232
Explore
benchflow-ai/skillsbench

pid-controller

Use this skill when implementing PID control loops for adaptive cruise control, vehicle speed regulation, throttle/brake management, or any feedback control system requiring proportional-integral-derivative control.

897 232
Explore
benchflow-ai/skillsbench

yaml-config

Use this skill when reading or writing YAML configuration files, loading vehicle parameters, or handling config file parsing with proper error handling.

897 232
Explore
benchflow-ai/skillsbench

simulation-metrics

Use this skill when calculating control system performance metrics such as rise time, overshoot percentage, steady-state error, or settling time for evaluating simulation results.

897 232
Explore
benchflow-ai/skillsbench

vehicle-dynamics

Use this skill when simulating vehicle motion, calculating safe following distances, time-to-collision, speed/position updates, or implementing vehicle state machines for cruise control modes.

897 232
Explore
benchflow-ai/skillsbench

web-interface-guidelines

Vercel's comprehensive UI guidelines for building accessible, performant web interfaces. Use this skill when reviewing or building UI components for compliance with best practices around accessibility, performance, animations, and visual stability.

897 232
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results