StreamCat Metrics REST API
Version: 1.0.0
On this page:
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: Default: Examples: |
| comid |
Description: Return metric information about specific COMIDs. Syntax: comid=<comid1>[,<comid2>,<comid3>,...] Examples:
|
| conus |
Description: Return all COMIDs in the coterminous United States. The default value is Values: Default: |
| 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: Default: |
| 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:
|
| name |
Description: (Required) Names of a metric to query. Syntax: name=<name1>,<name2> Examples:
|
| region |
Description: Return metric information for COMIDs within a specified hydroregion. Syntax: region=<regionid1>[,<regionid2>,<region3>...] Examples: |
| showAreaSqKm |
Description: Returns the area in square kilometers of a given area of interest. Values: Default: |
| showPctFull |
Description: Return the percent of each area of interest covered by the parent table of a metric. Values: Default: |
| 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:
|
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 |
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.