USGS Water Services

The USGS National Water Information System provides streamflow, water quality, and related hydrological data from 1.5 million+ sites across the US. No API key is required.

MetaData(USGSWaterServices())

MetaData("", "~5-10 req/s (informal)", :hydrology, Dict(Symbol("00060") => "Streamflow / Discharge (ft³/s)", Symbol("00300") => "Dissolved oxygen (mg/L)", Symbol("00045") => "Precipitation (in)", Symbol("00010") => "Water temperature (°C)", Symbol("00400") => "pH (standard units)", Symbol("00065") => "Gage height (ft)", Symbol("00095") => "Specific conductance (µS/cm at 25°C)", Symbol("63680") => "Turbidity (FNU)", Symbol("00011") => "Air temperature (°C)"), :point, "Station-based", "US", :timeseries, Day(1), "Varies by site (many decades)", "Public Domain", "https://waterservices.usgs.gov/docs/", Dict("DataFrames" => "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"))

Daily Values

Retrieve daily mean discharge for the Potomac River near Washington, DC (site 01646500):

plan = DataAccessPlan(USGSWaterServices(), (-77.1, 38.9),
    Date(2024, 1, 1), Date(2024, 1, 31);
    sites = ["01646500"],
    variables = [Symbol("00060")])
plan

DataAccessPlan for usgswaterservices
  Extent:    1 site(s): 01646500
  Time:      2024-01-01 to 2024-01-31 (31 days)
  Variables: 00060
  service: dv
  statCd: 00003
  sites: ["01646500"]
  API calls: 1
  Est. size: 248 bytes

  Request 1: GET 1 site(s), 31 days → usgswaterservices/3681f53199e103d6.json

files = fetch(plan)
data = JSON.parsefile(files[1])
ts = data["value"]["timeSeries"][1]
println("Site: ", ts["sourceInfo"]["siteName"])
println("Variable: ", ts["variable"]["variableDescription"])
println("Values: ", length(ts["values"][1]["value"]), " records")

Site: POTOMAC RIVER NEAR WASH, DC LITTLE FALLS PUMP STA
Variable: Discharge, cubic feet per second
Values: 31 records

Instantaneous Values

For higher-resolution (~15-minute) data, use service="iv":

plan = DataAccessPlan(USGSWaterServices(service="iv"), (-77.1, 38.9),
    Date(2024, 1, 1), Date(2024, 1, 7);
    sites = ["01646500"],
    variables = [Symbol("00060")])

Finding Sites

Site numbers can be found at USGS Water Data.

Variables

Variables are specified by USGS parameter codes:

Code	Description
`00060`	Streamflow / Discharge (ft³/s)
`00065`	Gage height (ft)
`00010`	Water temperature (°C)
`00011`	Air temperature (°C)
`00045`	Precipitation (in)
`00095`	Specific conductance (µS/cm at 25°C)
`00300`	Dissolved oxygen (mg/L)
`00400`	pH (standard units)
`63680`	Turbidity (FNU)