Skip to main content
U.S. flag

An official website of the United States government

Here’s how you know

Dot gov

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

HTTPS

Secure .gov websites use HTTPS
A lock (LockA locked padlock) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

    • Environmental Topics
    • Air
    • Bed Bugs
    • Cancer
    • Chemicals, Toxics, and Pesticide
    • Emergency Response
    • Environmental Information by Location
    • Health
    • Land, Waste, and Cleanup
    • Lead
    • Mold
    • Radon
    • Research
    • Science Topics
    • Water Topics
    • A-Z Topic Index
    • Laws & Regulations
    • By Business Sector
    • By Topic
    • Compliance
    • Enforcement
    • Laws and Executive Orders
    • Regulations
    • Report a Violation
    • Environmental Violations
    • Fraud, Waste or Abuse
    • About EPA
    • Our Mission and What We Do
    • Headquarters Offices
    • Regional Offices
    • Labs and Research Centers
    • Planning, Budget, and Results
    • Organization Chart
    • EPA History

Breadcrumb

  1. Home
  2. National Aquatic Resource Surveys

StreamCat Metrics REST API

Version: 1.0.0

On this page:

  • Parameters
  • Warnings
  • HTTP Response Codes
  • Examples
Base URL: https://java.epa.gov/StreamCAT/metrics

This web service returns metrics from the StreamCat data tables.

When no parameters are passed, this web service returns a JSON file containing a list of available options. Any application that can parse JSON can read this file.

The only parameter that the web service does not enumerate is COMIDs, due to the high volume of possible options.

When parameters are passed, this web service will return a comma-separated variable (CSV) file.

This web service supports the following protocols:

GET:

You can make a GET request by encoding a parameter string and appending it to the URL to the web service, as shown below: https://java.epa.gov/StreamCAT/metrics?name=fert&areaOfInterest=catchment&comid=179

Requests written in this manner can be easily bookmarked and linked to, or even be used in other APIs that support using URLs to CSVs directly, such as the Python function pandas.read_csv. However, URLs must not exceed 8192 characters in length (including the base URL and parameters). Some web browsers may have their own restrictions on URL size limits; for example, Internet Explorer is limited to 2048 characters. For longer and more complex requests, use the POST method.

POST:

You can also encode a parameter string as data in the body of an HTTP POST message. Certain tools, such as curl, can handle creating POST requests:

curl -d "name=fert&areaOfInterest=catchment&comid=179" https://java.epa.gov/StreamCAT/metrics

Parameters:

Parameters should be formatted as a standard HTML query string, using commas (,) to delimit parameters with multiple options. When comid, county, region or state parameters are specified, the web service will return a union of the COMIDs belonging to all specified areas (no duplicates).

Parameter Details
areaOfInterest

Description: Specify the area of interest described by a metric. By default, all available areas of interest for a given metric are returned. See Geospatial Framework and Terms on the StreamCat ReadMe document for more information on the terminology.

Syntax: areaOfInterest=<value1>[,<value2>,<value3>,...]

Values: catchment|watershed|riparian_catchment|riparian_watershed|other

Default: catchment,watershed,riparian_catchment,riparian_watershed,other

Examples:  areaOfInterest=catchment,watershed

comid

Description: Return metric information about specific COMIDs.

Syntax: comid=<comid1>[,<comid2>,<comid3>,...]

Examples: comid=179,1337,1337420

        comid=1337420

conus

Description: Return all COMIDs in the coterminous United States. The default value is false.

Values: true|false

Default: false

countOnly

Description: Returns a CSV containing the row count (ROWCOUNT) and the column count (COLUMNCOUNT) that the server expects to return in a request.

Values: true|false

Default: false

county

Description: Return metric information for COMIDs within a specific county. Users must use FIPS code, not county name, as a way to disambiguate counties.

Syntax: county=<county1>[,<county2>,<county3>,...]

Examples:    county=41003

         county=41003,41043

name

Description: (Required) Names of a metric to query.

Syntax: name=<name1>,<name2>

Examples:    name=fert

         name=pctglaclakefine,pctow2006

region

Description: Return metric information for COMIDs within a specified hydroregion.

Syntax: region=<regionid1>[,<regionid2>,<region3>...]

Examples:    region=region01,region02,region03w

showAreaSqKm

Description: Returns the area in square kilometers of a given area of interest.

Values: true|false

Default: false

showPctFull

Description: Return the percent of each area of interest covered by the parent table of a metric.

Values: true|false

Default: false

state

Description: Return metric information for COMIDs within a specific state. Use a state's abbreviation to query for a given state.

Syntax: state=<state1>[<state2>,<state3>...]

Examples:    state=OR

         state=WA

Warnings:

When a request cannot be filled completely, this web service uses a custom HTML header, warning, to report any warnings it comes across. These warnings are returned as a JSON array.

Message Details
Cannot find metric [name]. The web service cannot find any listed values for the given metric.

One or more metrics may not have a [catchment|riparian catchment|watershed|riparian watershed|other] value.

One of the requested metrics does not have a value for an area of interest that was queried.

HTTP response codes:

This service will return one of the following HTTP response status codes to indicate success, partial success, or failure in executing a request. In certain cases, this server will not return a CSV file. Instead, it may return an HTML error code with a corresponding message.

HTTP Status Code Output Format Message Cause Possible Solution
200 CSV or JSON [requested output] The web service has completed successfully and returned the requested metrics. No action is needed.
206 CSV or JSON [partial requested output] The request has returned at least one requested metric. However, some of the requested metrics do not have a value for the given area of interest. Check the 'warnings' header to see which metric areas of interest were not returned.
400 Text Invalid Parameters: [name]: [reason], [name]: [reason], ... The web service attempted to use the supplied parameters, but one or more of the supplied parameters is invalid. The errors encountered should be reported in this message. Address the reported errors in the request and try again.
404 Text The request has no columns to return. The requested metrics have no values for any of the listed areas of interest to return. Check to see if the name parameter contains valid metric names.
500 Text This web service has been shut down until it can be updated. Please try again later. The web service has encountered an error condition that has forced it to stop handling requests. It needs to be reloaded by a server administrator. Try to use this service again later.
500 Text An error occurred while processing this request. Please try again later. Varies. Try to use this service again later.

Example Queries:

https://java.epa.gov/StreamCAT/metrics?name=fert&areaOfInterest=catchment&comid=179

https://java.epa.gov/StreamCAT/metrics?name=fert&areaOfInterest=catchment,watershed&comid=179

GET request, using pandas.read_csv:

df = pandas.read_csv("https://java.epa.gov/StreamCAT/metrics?name=fert&areaOfInterest=catchment&comid=179")

POST request, using curl:

curl -d "name=fert&areaOfInterest=cat&comid=179" https://java.epa.gov/StreamCAT/metrics

Invalid query examples: https://java.epa.gov/StreamCAT/metrics?name=fert&areaOfInterest=catchment&comid=179,B

DISCLAIMER: The U.S. Environmental Protection Agency (EPA) has posted information through this application as a convenience to the application’s users. Although EPA has made every effort to ensure the accuracy of the information posted through this application, users of the application should not rely on information relating to environmental laws and regulations posted through it. Application users are solely responsible for ensuring that they are in compliance with all relevant environmental laws and regulations. In addition, EPA cannot attest to the accuracy of data or information provided by organizations outside of the federal government. Also, the views expressed in this document are those of the author(s) and do not necessarily represent the views or policies of EPA. Any mention of trade names, products, or services does not imply an endorsement by the U.S. Government or EPA. Finally, please be aware that the privacy protection provided on the EPA.gov domain (EPA Privacy and Security Notice) does not apply to these third-party sites.

National Aquatic Resource Surveys

  • Background
    • Indicators
    • Manuals
    • Map of Sampled Sites
  • NARS Data
    • Journal Articles
    • Applying the Data
    • LakeCat
    • StreamCat
  • National Coastal Condition Assessment
  • National Lakes Assessment
  • National Rivers and Streams Assessment
  • National Wetland Condition Assessment
  • Outreach Materials
Contact Us about National Aquatic Resource Surveys
Contact Us to ask a question, provide feedback, or report a problem.
Last updated on December 27, 2024
  • Assistance
  • Spanish
  • Arabic
  • Chinese (simplified)
  • Chinese (traditional)
  • French
  • Haitian Creole
  • Korean
  • Portuguese
  • Russian
  • Tagalog
  • Vietnamese
United States Environmental Protection Agency

Discover.

  • Accessibility Statement
  • Budget & Performance
  • Contracting
  • EPA www Web Snapshot
  • Grants
  • No FEAR Act Data
  • Plain Writing
  • Privacy
  • Privacy and Security Notice

Connect.

  • Data
  • Inspector General
  • Jobs
  • Newsroom
  • Regulations.gov
  • Subscribe
  • USA.gov
  • White House

Ask.

  • Contact EPA
  • EPA Disclaimers
  • Hotlines
  • FOIA Requests
  • Frequent Questions
  • Site Feedback

Follow.