M
API Matrix

USGS Water Services API

Science & Math / No Auth Required Beginner HTTPS
Free to Use Varies (check documentation)
87 Score
Grade A
Visit Official Site Compare Alternatives

Overview

USGS Water Services provides real-time and historical data on streamflow, water levels, and water quality for thousands of monitoring stations across the United States. The API is free and requires no authentication, offering data in multiple formats including JSON, CSV, and XML. It is a valuable resource for hydrology projects, flood monitoring apps, or environmental data analysis.

💡

Beginner Tip

Use the Instantaneous Values service with a USGS site number to get current streamflow data — find site numbers at waterdata.usgs.gov/nwis. Specify format=json to get a structured response that is easiest to parse programmatically.

Available Data

USGS Water Services data via REST API
JSON-formatted response data
Freely accessible without authentication

Example Response

JSON Response 
{
  "status": "success",
  "data": {
    "result": "Data from USGS Water Services",
    "description": "Water quality and level info for rivers and lakes",
    "timestamp": "2025-01-15T10:00:00Z"
  }
}

Field Reference

value.timeSeries Array of time series objects, one per requested parameter and site combination.
value.timeSeries[].sourceInfo.siteName Official name of the USGS monitoring station.
value.timeSeries[].variable.variableName Human-readable name of the measured parameter such as Streamflow in cubic feet per second.
value.timeSeries[].values[].value Array of value and dateTime objects containing the measurement readings.
value.timeSeries[].values[].value[].value The numeric measurement value as a string; convert to float for calculations.
value.timeSeries[].values[].value[].dateTime ISO 8601 timestamp of when this measurement was recorded.

Implementation Example 

const url = "https://waterservices.usgs.gov/";
const response = await fetch(url);
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();
console.log(data);

What Can You Build?

Note: These code examples are AI-generated and unverified. Always refer to the official API documentation for accurate usage.

Common Errors & Troubleshooting

Empty time series in response The parameterCd does not match data collected at the requested site.
✓ Look up which parameters a site collects at waterdata.usgs.gov; for streamflow use 00060, for gage height use 00065.
XML response instead of JSON The format parameter was not set to json, returning an XML response instead.
✓ Always include format=json in your query string; the default response format is WATERML2.0 XML.
Site not found error The site number is incorrect, incomplete, or the station has been decommissioned.
✓ Verify site numbers at waterdata.usgs.gov/nwis/rt and ensure you pad site numbers to 8 digits.

Matrix Score Breakdown

🌐 Reachability 30/30
⚡ Speed 15/20
🔒 Security 15/15
🛠 Developer XP 20/20
✓ Reliability 7/15
Response Time 201ms

Fully tested on Apr 5, 2026

Technical Specifications

Auth No Auth
HTTPS REQUIRED
CORS NO
Category Science & Math
Difficulty Beginner
Verified: 2026-04-04

Similar APIs

View All →

arcsecond.io

⭐ Beginner's Pick
82

arcsecond.io is a free astronomy API that aggregates data from multiple space databases, including stars, planets, exoplanets, and observing sites.

No Auth Beginner HTTPS 226ms

arXiv

0

arXiv provides programmatic access to curated research-sharing platform: physics, mathematics, quantitative finance, and economics via REST API.

No Auth Beginner HTTPS 71ms

GBIF

⭐ Beginner's Pick
52

GBIF (Global Biodiversity Information Facility) is a free, open API providing access to hundreds of millions of species occurrence records from around the world.

No Auth Beginner HTTPS 955ms

iDigBio

87

iDigBio is a free API that gives you access to millions of digitized natural history museum specimens from institutions across the United States and beyond.

No Auth Beginner HTTPS 44ms

inspirehep.net

87

INSPIRE-HEP is a free REST API for the High Energy Physics literature database, covering papers, authors, institutions, conferences, and experiments in particle physics.

No Auth Beginner HTTPS 66ms