USGS Water Services Getting Started: Data Access (2026)

Getting started overview

The USGS Water Services provide public access to a vast array of water-related data collected across the United States. This includes real-time and historical data on streamflow, groundwater levels, water quality, and more, primarily through the National Water Information System (NWIS) and the Water Quality Portal (WQP). Unlike many commercial APIs, USGS Water Services are designed for open access, meaning that developers typically do not need to register for an account or obtain API keys to begin making requests. This streamlined approach facilitates quick integration into applications for environmental monitoring, hydrological modeling, and public information services.

To get started, developers will focus on understanding the available web service endpoints and their associated parameters. Data can be retrieved in various formats, including JSON, XML, and CSV, catering to different application needs. The primary method of interaction is through standard HTTP GET requests to specific URLs, with parameters defining the desired data type, location, time range, and output format. For a comprehensive overview of the available services and their functionalities, consult the USGS API and Web Services documentation.

This guide will walk you through the process of making your first successful data request, covering common parameters and providing examples that you can adapt for your own projects. The open nature of these services means that the focus is on constructing correct URLs rather than managing authentication tokens or API keys.

Quick reference table

Create an account and get keys

For most standard data access from USGS Water Services, creating an account or obtaining API keys is not necessary. The United States Geological Survey provides its water data as a public service, making it freely accessible without authentication requirements. This approach significantly simplifies the getting started process, allowing developers to focus immediately on data retrieval rather than credential management.

There are no API keys, client IDs, or secret keys to generate or manage for general hydrological and water quality data access through the primary NWIS and WQP web services. This open access model aligns with the USGS mission to provide scientific information to the public for informed decision-making. Therefore, you can skip typical API setup steps like signing up for a developer account or navigating a developer console to generate credentials.

Developers should, however, be aware of any usage policies or rate limits, though these are generally generous given the public service nature of the data. The USGS web services documentation serves as the primary resource for understanding how to interact with the various data endpoints effectively and responsibly.

Your first request

To make your first request, you will construct a URL that specifies the data you want to retrieve. We'll use the National Water Information System (NWIS) Daily Values service as an example, requesting daily average streamflow data for a specific site. This service is a foundational component for accessing time-series data related to water quantity.

Example 1: Daily Streamflow Data (NWIS)

Let's retrieve the daily average streamflow for the USGS site 02178400 (Haw River at Bynum, NC) for a specific date range, formatted as JSON.

1. Identify the endpoint: For daily values, the base URL is generally https://waterservices.usgs.gov/nwis/dv/.

2. Specify parameters:

   • format=json: Request data in JSON format. The USGS provides multiple output formats.
   • sites=02178400: The USGS site ID. You can find site IDs using the USGS Site Inventory.
   • parameterCd=00060: The parameter code for streamflow, cubic feet per second (cfs). A full list of USGS parameter codes is available.
   • startDT=2023-01-01: The start date for the data.
   • endDT=2023-01-31: The end date for the data.

3. Construct the URL: Combine the base URL and parameters.

   https://waterservices.usgs.gov/nwis/dv/?format=json&sites=02178400&parameterCd=00060&startDT=2023-01-01&endDT=2023-01-31

4. Make the request: You can paste this URL into your web browser, use curl, or use any programming language's HTTP client.

   curl "https://waterservices.usgs.gov/nwis/dv/?format=json&sites=02178400&parameterCd=00060&startDT=2023-01-01&endDT=2023-01-31"

5. Expected (truncated) JSON Response:

   {
     "value": {
       "queryInfo": {
         "criteria": {
           "locationParam": "[parameter:02178400]",
           "parameter": [
             "00060"
           ],
           "timeParam": {
             "beginDateTime": "2023-01-01T00:00:00.000-05:00",
             "endDateTime": "2023-01-31T23:59:59.000-05:00"
           }
         },
         "note": [
           {
             "value": "Explanation of symbols",
             "title": "explanation"
           },
           {
             "value": "dv_json_2_0",
             "title": "schema version"
           },
           {
             "value": "Requesting data from NWIS site: 02178400",
             "title": "siteInfo"
           }
         ]
       },
       "timeSeries": [
         {
           "sourceInfo": {
             "siteName": "HAW RIVER AT BYNUM, NC",
             "siteCode": [
               {
                 "value": "02178400",
                 "network": "NWIS",
                 "agencyCode": "USGS"
               }
             ],
             "geoLocation": {
               "geogLocation": {
                 "srs": "EPSG:4326",
                 "latitude": 35.8119444,
                 "longitude": -79.1677778
               }
             }
           },
           "variable": {
             "variableCode": [
               {
                 "value": "00060",
                 "network": "NWIS",
                 "vocabulary": "NWIS:UnitValues"
               }
             ],
             "variableName": "Stream flow, cubic feet per second",
             "unit": {
               "unitCode": "cfs"
             }
           },
           "values": [
             {
               "dateTime": "2023-01-01T00:00:00.000-05:00",
               "value": "98.0",
               "qualifiers": [
                 "P"
               ]
             },
             {
               "dateTime": "2023-01-02T00:00:00.000-05:00",
               "value": "94.0",
               "qualifiers": [
                 "P"
               ]
             }
             // ... more daily values
           ]
         }
       ]
     }
   }

This response contains metadata about the site and variable, followed by an array of daily values, each with a timestamp, the measured value, and any associated qualifiers. For a detailed explanation of the NWIS Daily Values service and its parameters, refer to the USGS Daily Values Service documentation.

Common next steps

Once you've successfully retrieved data from USGS Water Services, consider these common next steps to expand your usage and integrate the data effectively into your applications:

• Explore other data services: USGS offers various services beyond daily values. Investigate the Real-Time Water Data (NWIS) for current conditions, Unit Values for sub-daily measurements, or the Water Quality Portal (WQP) for comprehensive water quality data from multiple agencies. Each service has its own specific endpoints and parameter requirements.

• Parameter and site discovery: Learn how to programmatically discover available sites and parameter codes relevant to your area of interest. The USGS Site Service can help you find sites based on geographical criteria or agency. Similarly, understanding the USGS parameter code catalog is crucial for requesting specific types of data.

• Data parsing and integration: Develop robust parsing logic for the JSON, XML, or CSV responses. Libraries in your chosen programming language can help with this. Integrate the parsed data into your database, analytics platform, or visualization tools. Consider how you will handle missing data, data qualifiers, and units of measurement.

• Error handling: Implement error handling in your application to gracefully manage situations where a request fails, returns no data, or encounters an invalid parameter. While USGS services are robust, network issues or incorrect parameters can lead to unexpected responses.

• Rate limiting and responsible usage: While no explicit API keys are required, it is good practice to implement rate limiting on your end to avoid overwhelming the USGS servers. Frequent, rapid requests for large datasets can strain public infrastructure. Refer to the USGS general usage guidelines for best practices.

• Visualization and analysis: Utilize the retrieved data for charting, mapping, or statistical analysis. Tools like Python (with libraries such as Pandas, Matplotlib, Folium) or R are commonly used for environmental data manipulation and visualization. For geographical data, consider integrating with mapping libraries or services like ArcGIS Developer resources or Google Maps Platform.

• Stay updated: The USGS may update its web services or introduce new data products. Regularly check the USGS Water Data News and Announcements page to stay informed about changes.

Troubleshooting the first call

Encountering issues with your first API call is common. Here's a guide to troubleshooting typical problems when working with USGS Water Services:

• Incorrect URL or Endpoint:

  • Issue: The URL returns a 404 Not Found error or an unexpected response.
  • Solution: Double-check the base URL for the specific service you are trying to access (e.g., waterservices.usgs.gov/nwis/dv/ for daily values, www.waterqualitydata.us/data/result/json for WQP). Verify against the official USGS API documentation. Typos in service names or domain can lead to this.

• Missing or Invalid Parameters:

  • Issue: The response is empty, incomplete, or contains an error message indicating invalid input.
  • Solution: Review all specified parameters (sites, parameterCd, startDT, endDT, format, etc.). Ensure they are correctly spelled, have valid values, and are in the expected format (e.g., dates as YYYY-MM-DD). Consult the USGS parameter definitions for the specific service. For example, using a site ID that doesn't exist or a parameter code not applicable to that site will result in no data.

• Date Range Issues:

  • Issue: No data returned for a specified date range.
  • Solution: Verify that data actually exists for the requested site and parameter within your specified startDT and endDT. Some sites may have discontinuous records or only begin collecting data after a certain date. Shorten your date range for testing, or check the USGS Surface Water Data for the Nation portal to see if data is graphically available for your chosen site and period.

• Incorrect Output Format:

  • Issue: The response is not in the expected JSON, XML, or CSV format, or your parser fails.
  • Solution: Ensure the format parameter is correctly set (e.g., format=json, format=xml, format=rdb for tab-separated). If using a browser, it might render XML directly. If using curl, ensure you're correctly handling the output. Verify the content-type header of the response to confirm the actual format received.

• Network or Firewall Restrictions:

  • Issue: Requests time out, or you receive connection errors from your development environment.
  • Solution: Check your local network connection, firewall settings, or proxy configurations. Ensure that your environment can make outbound HTTP requests to waterservices.usgs.gov or www.waterqualitydata.us. Test with a simple command like curl google.com to confirm general internet connectivity.

• Understanding the Response Structure:

  • Issue: The request succeeds, but you're having difficulty parsing the data within the JSON or XML structure.
  • Solution: The USGS responses, especially for NWIS, can be nested. Use a JSON formatter/viewer (like those built into modern browsers or online tools) to inspect the full structure. Pay attention to arrays (timeSeries, values) and nested objects. The USGS documentation for each service often provides detailed schema examples.