USGS Water Services API

Free USGS Water Services API with no key: real-time river discharge, gauge height, water temperature and groundwater levels from thousands of US sites. Tested.

No API key requiredCORS enabledHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-19

What is the USGS Water Services API?

The USGS Water Services API is a free, key-free US government API providing real-time and historical water data — river discharge, gauge height, temperature and groundwater levels — from thousands of monitoring stations across the United States.

USGS operates a national network of stream gauges reporting at 15-minute intervals, and the data is fully open. It is the authoritative source for flood monitoring, river levels and streamflow in the US.

The response format is the main obstacle: it is WaterML rendered as JSON, which means deeply nested structures with values buried under `value.timeSeries[].values[].value[]`. It is verbose and awkward, but the data underneath is excellent and worth the parsing effort.

Quick facts

Base URL: https://waterservices.usgs.gov/nwis
Authentication: No API key required.
Rate limit: No published hard limit; large multi-site historical queries should be batched.
Pricing: Free public domain US government data.
CORS: Enabled — callable directly from browser JavaScript
Official docs: Read the docs

How to use the USGS Water Services API

Every request below was executed against the live API on 2026-08-19, and the response shown is the real body it returned — not an illustration.

1. Real-time discharge at a gauge site

GET https://waterservices.usgs.gov/nwis/iv/?format=json&sites=01646500&parameterCd=00060

curl

curl 'https://waterservices.usgs.gov/nwis/iv/?format=json&sites=01646500&parameterCd=00060'

JavaScript (fetch)

const res = await fetch("https://waterservices.usgs.gov/nwis/iv/?format=json&sites=01646500&parameterCd=00060");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);

Python (requests)

import requests

res = requests.get("https://waterservices.usgs.gov/nwis/iv/?format=json&sites=01646500&parameterCd=00060", timeout=20)
res.raise_for_status()
print(res.json())

Response — HTTP 200 (truncated)

{
  "name": "ns1:timeSeriesResponseType",
  "declaredType": "org.cuahsi.waterml.TimeSeriesResponseType",
  "scope": "javax.xml.bind.JAXBElement$GlobalScope",
  "value": {
    "queryInfo": {
      "queryURL": "http://waterservices.usgs.gov/nwis/iv/format=json&sites=01646500&parameterCd=00060",
      "criteria": {
        "locationParam": "[ALL:01646500]",
        "variableParam": "[00060]",
        "parameter": []
      },
      "note": [
        {
          "value": "[ALL:01646500]",
          "title": "filter:sites"
        },
        {
          "value": "[mode=LATEST, modifiedSince=null]",
          "title": "filter:timeRange"
        },
        {
          "value": "methodIds=[ALL]",
          "title": "filter:methodId"
        },
        {
          "value": "2026-08-19T20:28:29.183Z",
          "title": "requestDT"
        },
        {
          "value": "89ded9e0-9c0c-11f1-8c10-2cea7f58f5ca",
          "title": "requestId"
        },
        {
          "value": "Provisional data are subject to revision. Go to http://waterdata.usgs.gov/nwis/help/?provisional for more information.",
          "title": "disclaimer"
        },
        {
          "value": "vaas01",
          "title": "server"
        }
      ]
    },
    "timeSeries": [
      {
        "sourceInfo": {
          "siteName": "POTOMAC RIVER NEAR WASH, DC LITTLE FALLS PUMP STA",
          "siteCode": [
            {
              "value": "01646500",
              "network": "NWIS",
              "agencyCode": "USGS"
            }
          ],
          "timeZoneInfo": {
            "defaultTimeZone": {

Parameters

Parameter	Type	Required	Description
`format`	string	Required	Set to `json` — the default is WaterML XML. `json`
`sites`	string	Optional	Comma-separated USGS site numbers. `01646500`
`parameterCd`	string	Optional	Parameter code: 00060 discharge, 00065 gauge height, 00010 temperature. `00060`
`stateCd`	string	Optional	Query every site in a state. `va`
`period`	string	Optional	ISO-8601 duration for historical data. `P7D`

Response fields

value.timeSeriesarray: One entry per site and parameter combination.
value.timeSeries[].sourceInfo.siteNamestring: Human-readable gauge name.
value.timeSeries[].variable.variableNamestring: What is being measured, with units.
value.timeSeries[].values[].value[]array: The actual readings, each with a value and dateTime.
value.timeSeries[].values[].value[].valuestring: The measurement as a STRING — parse before use.

What you can build with the USGS Water Services API

Monitor river levels for flood warning systems
Show current streamflow for paddling, fishing or rafting sites
Analyse long-term hydrological trends and drought
Support water resource and environmental research

Common errors and how to fix them

XML instead of JSON

The `format=json` parameter was omitted.

Fix: Always pass format=json; WaterML XML is the default.

Values of -999999

USGS's no-data sentinel, not a real reading.

Fix: Filter these out before charting or averaging.

Empty timeSeries

The site does not report that parameter, or is offline.

Fix: Not every gauge measures every parameter; check the site's capabilities first.

USGS Water Services API — frequently asked questions

Is the USGS water data API free?

Yes, completely free with no API key. It is public domain US government data.

Why is the response structure so deeply nested?

It is WaterML, a hydrology data standard, serialised as JSON. Readings live under value.timeSeries[].values[].value[] — verbose, but the underlying data is authoritative.

What are the common parameter codes?

00060 is discharge in cubic feet per second, 00065 is gauge height in feet, and 00010 is water temperature in Celsius.

What does -999999 mean?

It is the USGS no-data sentinel for a missing or invalid reading. Always filter these values out before calculating averages or plotting.

Tools that pair with this API

JSON Formatter

Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.

Unit Converter

Convert between units of length, weight, temperature, area, volume, speed, time and data storage instantly, with a swap button and common conversion tables.

CSV to JSON Converter

Convert CSV to a JSON array of objects online. Header-row detection, comma/semicolon/tab delimiters and pretty-printed output — 100% in your browser.

USGS Water Services is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-19; always check the official documentation before relying on this API in production, as terms and limits can change.