Time series · streamflow-daily
Daily streamflow
Daily mean discharge at every USGS stream gage over the last 400 days, flagged provisional, estimated or ice-affected, with the USGS qualifier codes. Re-read in full every day, because USGS revises provisional values for months.
- Updates
- Daily
- Coverage
- —
- Current version
- —
- Last published
- —
- Validation
- —
- License
- US Government work
- Commercial use
- Allowed
Chart
Use the API
Each series and location is its own small file. The examples follow the series and location picked above. See the docs for versions, caching and errors.
curl
# One series for one place (.json or .csv)
curl -s "https://api.waterdata.dev/v1/streamflow-daily/discharge/{location}.json"
# Every series and place in one file
curl -sO "https://api.waterdata.dev/v1/streamflow-daily/download/streamflow-daily.csv"Python (polars)
import polars as pl
# One series for one place
df = pl.read_csv("https://api.waterdata.dev/v1/streamflow-daily/discharge/{location}.csv")
# Every series and place, with series and location columns
everything = pl.read_parquet("https://api.waterdata.dev/v1/streamflow-daily/download/streamflow-daily.parquet")JavaScript
const res = await fetch("https://api.waterdata.dev/v1/streamflow-daily/discharge/{location}.json");
if (!res.ok) throw new Error((await res.json()).detail); // errors are problem+json
const { meta, data } = await res.json();
console.log(meta.location_name, data.at(-1)); // { date, value, ... }Downloads
The whole dataset in one file, with series and location columns. Parquet keeps the column types and is much smaller.
- streamflow-daily.csv CSV
- streamflow-daily.parquet Parquet
Schema and series
Each series file has these columns. The bulk downloads add series and location columns in
front.
| Column | Type | Unit | Can be empty | Description |
|---|---|---|---|---|
| date | date (YYYY-MM-DD) | — | no | Local calendar day at the gage |
| value | number | ft^3/s | yes | Daily mean discharge. Null where USGS publishes the day without a value (ice, equipment, seasonal); negative where tidal or regulated flow runs upstream |
| provisional | true / false | — | no | True until USGS approves the value; provisional data are subject to revision |
| estimated | true / false | — | no | USGS qualifier ESTIMATED |
| ice | true / false | — | no | USGS qualifier ICE (ice-affected) |
| qualifiers | text | — | yes | Every USGS qualifier code for the day, comma-separated, e.g. BACKWATER,ESTIMATED |
Series
| Series id | Name |
|---|---|
| discharge | Daily mean discharge |
Locations
Covers stations whose ids match usgs-\d{8,15}.
Source and license
- Source
- USGS Water Data APIs (OGC API), daily values
- Publisher
- U.S. Geological Survey
- License
- US Government work (public domain in the United States) (
LicenseRef-US-Government-Work) - Commercial use
- Allowed
Credit the source with this exact text:
Streamflow data courtesy of the U.S. Geological Survey.
Checked every 1 day. If the source hasn't changed in 3 days, the status page flags it as stale.
Endpoints
Every URL for this dataset. To pin the current version, put it after the id:
/v1/streamflow-daily@<version>.
The API reference describes each response.
| What | URL |
|---|---|
| Metadata: version, coverage, downloads, validation | /v1/streamflow-daily |
| Versions and monthly snapshots | /v1/streamflow-daily/versions |
| Series and locations | /v1/streamflow-daily/locations |
| Daily mean discharge (JSON) | /v1/streamflow-daily/discharge/{location}.json |
| Daily mean discharge (CSV) | /v1/streamflow-daily/discharge/{location}.csv |
| Whole dataset (CSV) | /v1/streamflow-daily/download/streamflow-daily.csv |
| Whole dataset (Parquet) | /v1/streamflow-daily/download/streamflow-daily.parquet |