USGS Water Services API for Hydrological Data Access

Overview

USGS Water Services offer a suite of web-based tools and APIs designed to provide access to hydrological, water quality, and groundwater data collected by the U.S. Geological Survey (USGS). These services are built upon the extensive data holdings of the National Water Information System (NWIS) and the Water Quality Portal (WQP), which aggregate data from the USGS, the Environmental Protection Agency (EPA), and other federal, state, and local agencies. The primary objective of these services is to facilitate the dissemination and integration of critical water resource information for scientific research, environmental management, public policy, and educational purposes.

The services cater to a broad audience, including academic researchers, environmental consultants, government agencies, and developers building applications that require accurate and up-to-date water data. For instance, a hydrological modeler might use the NWIS services to retrieve historical streamflow data for a specific basin to calibrate a flood prediction model. An environmental scientist could access water quality parameters from the WQP to assess pollution trends in a watershed. Public utilities can monitor real-time conditions to optimize water treatment and distribution, while agricultural planners might use groundwater level data to inform irrigation strategies.

USGS Water Services excel in scenarios requiring granular, geographically diverse water data across the United States. The underlying NWIS database contains over 1.5 million sites, providing a vast network of observation points for various water parameters including streamflow, lake and reservoir levels, groundwater levels, and water quality measurements. The services are particularly valuable for long-term trend analysis, regional assessments, and real-time monitoring applications where consistent and authoritative data sources are paramount. The commitment to open data access ensures that this information is available without cost, removing financial barriers to research and development in water science. Developers benefit from the clear parameter definitions and multiple data formats, making it feasible to integrate this data into diverse analytical platforms and user interfaces.

Key features

• National Water Information System (NWIS) APIs: Provides access to real-time and historical streamflow, water levels, groundwater levels, and water quality data from thousands of sites across the U.S. (USGS NWIS Web Services documentation).
• Water Quality Portal (WQP) APIs: Offers consolidated access to water quality data from the USGS, EPA, and other contributors, supporting detailed queries on chemical, biological, and physical parameters (WQP API documentation).
• WaterNow: A service providing current and recent water data for specific locations, often used for immediate information retrieval.
• Data Retrieval Options: Supports various data formats, including JSON, XML, CSV, and tab-separated values, allowing flexibility for integration into different programming environments.
• Geospatial Query Capabilities: Enables data retrieval based on geographic criteria, such as bounding boxes, HUC codes, or proximity to specific points.
• Historical Data Access: Provides extensive archives of historical data, facilitating long-term trend analysis and retrospective studies.
• Real-time Data Streams: Offers access to continuously updated data for monitoring dynamic hydrological conditions.

Pricing

USGS Water Services are provided as a public service and are entirely free to use. There are no subscription fees, usage charges, or tiered access models for accessing the data via their APIs or web interfaces. This policy aligns with the USGS mission to provide scientific information to describe and understand the Earth.

Pricing information accurate as of 2026-05-28. For the most current details, refer to the USGS Water Data homepage.

Common integrations

USGS Water Services are commonly integrated into applications and systems that require environmental data inputs. Due to the RESTful nature of the APIs and multiple output formats, they can be consumed by various programming languages and platforms:

• Geographic Information Systems (GIS): Developers frequently integrate USGS water data into GIS platforms like Esri ArcGIS (ArcGIS Developers documentation) to visualize hydrological conditions, analyze spatial patterns, and create interactive maps.
• Environmental Modeling Software: Data from NWIS and WQP are critical inputs for hydrological models (e.g., HEC-RAS, SWAT), water quality models, and climate change impact assessments.
• Data Science and Analytics Platforms: Researchers use programming languages like Python (with libraries like Pandas and requests) or R to fetch, process, and analyze large datasets from USGS services for statistical analysis and machine learning applications.
• Web and Mobile Applications: Developers build custom applications to display real-time streamflow, water levels, or water quality alerts for specific regions or user interests.
• Dashboards and Reporting Tools: Government agencies and environmental organizations often integrate this data into internal dashboards to monitor conditions and generate regulatory compliance reports.

Alternatives

• NOAA National Water Center: Provides hydrological forecasts, flood inundation mapping, and water resources information, often with a focus on predictive modeling and hazard assessment.
• EPA Water Quality Data (WQX): A component of the Water Quality Portal, WQX serves as the primary mechanism for states, tribes, and other organizations to submit and share water quality data with the EPA.
• Open-Meteo: Offers open-source weather and climate APIs, which can provide complementary meteorological data relevant to hydrological studies, though it does not focus on direct water resource measurements.

Getting started

To retrieve real-time streamflow data for a specific USGS site (e.g., site 01646500 on the Potomac River) using the NWIS Daily Values web service, you can make a simple HTTP GET request. This example uses Python's requests library to fetch data in JSON format.

import requests
import json

# USGS NWIS site number for Potomac River near Washington, DC
site_number = "01646500"

# Parameter code for streamflow (discharge) in cubic feet per second (cfs)
# More parameter codes can be found in USGS documentation.
parameter_code = "00060"

# Period of record: last 7 days
period = "P7D"

# Base URL for NWIS Daily Values service
base_url = "https://waterservices.usgs.gov/nwis/dv/"

# Construct the API request URL
# Output format can be 'json', 'xml', 'rdb' (tab-separated), etc.
api_url = f"{base_url}?format=json&sites={site_number}¶meterCd={parameter_code}&period={period}"

print(f"Fetching data from: {api_url}")

try:
    response = requests.get(api_url)
    response.raise_for_status()  # Raise an HTTPError for bad responses (4xx or 5xx)
    
    data = response.json()
    
    # Process the JSON response
    # The structure can be complex; this is a simplified example
    if "value" in data and len(data["value"]["timeSeries"]) > 0:
        time_series = data["value"]["timeSeries"][0]
        site_name = time_series["sourceInfo"]["siteName"]
        variable_description = time_series["variable"]["variableDescription"]
        
        print(f"\nData for: {site_name} - {variable_description}")
        print("---------------------------------------------------")
        
        for item in time_series["values"][0]["value"]:
            date = item["dateTime"].split('T')[0]
            value = item["value"]
            print(f"Date: {date}, Value: {value} cfs")
    else:
        print("No data found for the specified site and parameters.")

except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")
except json.JSONDecodeError:
    print("Failed to decode JSON response. The API might have returned non-JSON.")

This Python script constructs a URL to query the USGS NWIS Daily Values service for streamflow data. It then parses the JSON response to extract and print the daily streamflow values for the specified site over the last seven days. For more detailed parameter codes and advanced query options, consult the USGS NWIS Web Services documentation.