StreamStats Services are being decommissioned

StreamStats Services will be replaced by a new API at an unknown date after December 15, 2024. The new API will feature new endpoints, input parameters, and responses. Users of the current StreamStats Services will need to switch to the new API. Please stay tuned on this page for updates.

The National Streamflow Statistics Services and Gage Statistics Services will remain in service.

For more information, please contact streamstats@usgs.gov.

Introduction

The StreamStats application is supported by web services. The StreamStats application manages interactions between the user and the services. These web services can be directly accessed using the StreamStats Service API documented here or consumed by a custom client application using HTTP protocols.

The StreamStats Service API performs multiple high-level procedures, which include database queries, geospatial calculations, and service requests in order to compile and create simple objects that can be consumed by custom client applications. As documented by this page, which can also serve as an URL builder, the StreamStats Service API is built following RESTful principles to ensure scalability and predictable URLs.

Getting Started

The URL of each resource can be obtained by accessing one of the resources located to the left.

Every resource is exposed as a URL and follows the outlined pattern described below:

• The description of the resource
• The service URL
• Optional response formats, such as xml, json, or geojson
• URL parameters (if any)
  • Parameter Name
  • Value Type (string, number, boolean, etc.)
  • A description of what the parameter represents
  • Whether the parameter is required or optional
  • Example input parameter.
• A REST Query URL test tool that builds an example url, based on the given input parameter values
• Example response from the REST Query

Important Notes about Using StreamStats Services

• StreamStats Services occasionally return HTTP status code 200 (OK) but fail to return the expected results. For this reason, we recommend using checks to ensure the expected data was returned and retry the service request, if needed.
• StreamStats is hosted on two identical servers. When using StreamStats Services, you must ensure that you use the same server for subsequent requests. For example, if you request to delineate a basin, you must request to compute flow statistics on the same server. The are several ways to do this:
1. Make requests to one specific server: prodweba.streamstats.usgs.gov or prodwebb.streamstats.usgs.gov.
2. Set the "withCredentials" request header to be true.
3. Look at the "usgswim-hostname" property of the response. The value will be "PRODWEBA" or "PRODWEBB". Make subsequent requests to prodweba.streamstats.usgs.gov if the value is "PRODWEBA" or prodwebb.streamstats.usgs.gov if the value is "PRODWEBB".
• Please use the StreamStats Services responsibly:
• Limit service queries to no more than four simultaneous requests.
• Periodically check service responses to ensure that desired results are being returned.
• For assistance with using the services, please contact streamstats@usgs.gov.
• Please note that we may change how we apply and enforce rate limits at any time.