Table · stream-gages
USGS stream gages
Every USGS stream gage (streams, canals, ditches and tidal streams) that reported a daily mean discharge in the last 400 days: name, state, county, hydrologic unit, coordinates, drainage area and period of daily record. These are the gages in streamflow-daily, under the same ids.
- Updates
- Daily
- Coverage
- —
- Current version
- —
- Last published
- —
- Validation
- —
- License
- US Government work
- Commercial use
- Allowed
Preview
Use the API
The examples follow the rows picked above. See the docs for versions, caching and errors.
curl
# All rows (.json or .csv)
curl -s "https://api.waterdata.dev/v1/stream-gages/table/all.json"
# The whole table in one file
curl -sO "https://api.waterdata.dev/v1/stream-gages/download/stream-gages.csv"Python (polars)
import polars as pl
# All rows
df = pl.read_csv("https://api.waterdata.dev/v1/stream-gages/table/all.csv")
# The whole table
everything = pl.read_parquet("https://api.waterdata.dev/v1/stream-gages/download/stream-gages.parquet")JavaScript
const res = await fetch("https://api.waterdata.dev/v1/stream-gages/table/all.json");
if (!res.ok) throw new Error((await res.json()).detail); // errors are problem+json
const { meta, rows } = await res.json();
console.log(meta.rows, rows[0]);Downloads
The whole dataset in one file. Parquet keeps the column types and is much smaller.
- stream-gages.csv CSV
- stream-gages.parquet Parquet
Schema
Rows are identified by site_id.
The rows are also split into one file per value of region.
Tables up to 50,000 rows also have a single table/all file.
| Column | Type | Unit | Can be empty | Description |
|---|---|---|---|---|
| site_id key | text | — | no | Location id used across waterdata: usgs- plus the site number |
| site_number | text | — | no | USGS site number (8 to 15 digits) |
| name | text | — | no | USGS station name |
| site_type_code | text | — | no | ST stream, ST-CA canal, ST-DCH ditch, ST-TS tidal stream |
| site_type | text | — | no | — |
| region partition | text | — | no | Registry id of the state or territory (us-md); for gages outside the US, of the country (can) |
| country | text | — | no | Registry id of the country (usa or can) |
| state | text | — | yes | Two-letter USPS code; null outside the US |
| county_fips | text | — | yes | Five-digit county FIPS code (matches drought-county's us-county-<FIPS>) |
| county_name | text | — | yes | — |
| huc | text | — | yes | Hydrologic unit code as USGS records it (8 or 12 digits) |
| huc8 | text | — | yes | The 8-digit subbasin containing the gage |
| latitude | number | degrees | no | WGS 84 |
| longitude | number | degrees | no | WGS 84 |
| drainage_area | number | mi^2 | yes | — |
| contributing_drainage_area | number | mi^2 | yes | — |
| altitude | number | ft | yes | Gage datum altitude above altitude_datum |
| altitude_datum | text | — | yes | Vertical datum, e.g. NAVD88 or NGVD29 |
| time_zone | text | — | yes | Standard time zone abbreviation |
| time_series_id | text | — | no | USGS id of the daily mean discharge series used in streamflow-daily |
| sublocation | text | — | yes | USGS sublocation of that series |
| daily_begin | date (YYYY-MM-DD) | — | yes | First day of the daily discharge record |
| daily_end | date (YYYY-MM-DD) | — | no | Latest day of the daily discharge record |
Source and license
- Source
- USGS Water Data APIs (OGC API), monitoring-locations and time-series-metadata
- 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:
Stream gage information 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/stream-gages@<version>.
The API reference describes each response.
| What | URL |
|---|---|
| Metadata: version, coverage, downloads, validation | /v1/stream-gages |
| Versions and monthly snapshots | /v1/stream-gages/versions |
| Partitions | /v1/stream-gages/locations |
| Rows for one region (JSON) | /v1/stream-gages/table/{region}.json |
| Rows for one region (CSV) | /v1/stream-gages/table/{region}.csv |
| All rows in one file (tables up to 50,000 rows) | /v1/stream-gages/table/all.json |
| Whole dataset (CSV) | /v1/stream-gages/download/stream-gages.csv |
| Whole dataset (Parquet) | /v1/stream-gages/download/stream-gages.parquet |