Explore USGS Water Data API Basics
The Explore USGS Water Data API provides users with a fast, flexible way to request specific data from various sources.
Use the Explore USGS Water Data API for quick access to national-scale water data.
Get Started
The Explore USGS Water Data API was created using GraphQL to provide a way to request specific data from multiple sources. This API lets clients scale and focus results to retrieve only what is needed.
Key Components
A request to the Explore USGS Water Data API includes three components.
Query: The process used to read or fetch values. The most popular response is JSON.
Resolver: The method that provides the value for a type or field and is the key component that connects items with their associated data and services.
Schema: This is the description of the data that can be requested.
What Can I Request?
| Parameter | Description |
|---|---|
| features | Provides the option of search based upon geographic feature (examples: mountain or lake). |
| type | Defines the data type for the request (example: water level, water flow, chemical data). |
| geometry | Defines how the information can be plotted on a map. |
| coordinates | Maximum latitude and longitude and minimum latitude and longitude used to define a geographic area. |
| properties | Everything known about a specific location. |
| id | Provides the monitoring location identifier which includes the agency code and location number. |
| locationtype | Requests information related to surface water, groundwater, spring, atmospheric, and/or other. Multiple types can be requested. |
| locationname | Requests a list of information associated with a specific location. Requests can include zip code, city, state. |
| agencyCD | An agency code is a fixed value assigned by the National Water Information System (NWIS). This code is the agency reporting the data. |
| huc8 | A hydrologic unit code that maps medium-sized river basins. |
| locationsubtype | Provides additional information connected to specific location types if additional information is available. |
| keywords | Provides the ability to filter results based upon data of interest. Multiple keywords can be entered. |
| iv_data_only | Determines if data should be IV. It is a boolean flag that will override age of data year even if a vaulue is passed. |
Interactions with the Explore USGS Water Data API can be created using only the parameters needed.
Logical Operators
Logical Operator fields define logical combinations of independent objects. A logical operator field has the following form:
<Operator>:_``[<QueryInput>,``...
| Operator | Description |
|---|---|
| And | Finds results that match all of the provided objects. |
| Not | Finds results that match no objects. |
| Or | Finds results that match any of the provided objects. |
Comparison Operators
Comparison Operator fields define a more complex decision. A comparison operator field has the following form:<Field Name>_``<Operator>:``<Operator Value>
| Operator | Description |
|---|---|
| gt | Finds results where the field is greater than the specified value. |
| gte | Finds results where the field is greater than or equal to the specified value. |
| lt | Finds results where the field is less than the specified value. |
| lte | Finds results where the field is less than or equal to the specified value. |
| ne | Finds results where the field is not equal to the specified value. |
| in | Finds results where the field is equal to any value in the specified array. |
| nin | Finds results where the field is not equal to any value in the specified array. |
Result Format
The Explore USGS Water Data API provides responses in a GeoJSON format.
Examples:
I would like to see turbidity and pH data for surface water in Green Bay, WI. I want to limit the data to the most recent five years.
query ExampleQuery {
getByBoundingBox(
northEastBound: {
x: -88.10186999999998,
y: 44.42120000000004
},
southWestBound: {
x: -87.91786999999998,
y: 44.60520000000004
},
locationTypes: [SURFACE_WATER],
ageOfDataYear:2018,
ivDataOnly:false,
keywords: ["Turbidity", "pH"]
) {
count
features {
type
geometry {
type
coordinates
}
properties {
id
agencyCd
locationType
locationSubType
locationName
locationNumber
}
}
}
}
curl "https://labs-beta.usgs.gov/monitoring-location/graphql" ^
-H "authority: monitoring-location-testing.wma.chs.usgs.gov" ^
-H "accept: */*" ^
-H "accept-language: en-US,en;q=0.9" ^
-H "cache-control: no-cache" ^
-H "content-type: application/json" ^
-H "origin: https://webvadevvs04.er.usgs.gov" ^
-H "pragma: no-cache" ^
-H "referer: https://webvadevvs04.er.usgs.gov/" ^
-H "sec-ch-ua: ^\^"Not.A/Brand^\^";v=^\^"8^\^", ^\^"Chromium^\^";v=^\^"114^\^", ^\^"Microsoft Edge^\^";v=^\^"114^\^"" ^
-H "sec-ch-ua-mobile: ?0" ^
-H "sec-ch-ua-platform: ^\^"Windows^\^"" ^
-H "sec-fetch-dest: empty" ^
-H "sec-fetch-mode: cors" ^
-H "sec-fetch-site: same-site" ^
-H "user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36 Edg/114.0.1823.51" ^
--data-raw "^{^\^"operationName^\^":^\^"GetLocations^\^",^\^"query^\^":^\^"^\^\n query GetLocations (^\^\n ^$northEastBound: InputPoint^!,^\^\n ^$southWestBound: InputPoint^!,^\^\n ^$locationTypes: ^[MonitoringLocationSiteType^!^],^\^\n ^$ageOfDataYear: Int,^\^\n ^$keywords: ^[String^!^],^\^\n ^$ivDataOnly: Boolean^\^\n ) ^{^\^\n getByBoundingBox(^\^\n northEastBound: ^$northEastBound,^\^\n southWestBound: ^$southWestBound,^\^\n locationTypes: ^$locationTypes,^\^\n ageOfDataYear: ^$ageOfDataYear,^\^\n keywords: ^$keywords,^\^\n ivDataOnly: ^$ivDataOnly^\^\n ) ^{^\^\n count^\^\n features ^{^\^\n type^\^\n geometry ^{^\^\n type^\^\n coordinates^\^\n ^}^\^\n properties ^{^\^\n id^\^\n agencyCd^\^\n locationType^\^\n locationSubType^\^\n locationName^\^\n locationNumber^\^\n keywords^\^\n ^}^\^\n ^}^\^\n ^}^\^\n ^}^\^",^\^"variables^\^":^{^\^"northEastBound^\^":^{^\^"x^\^":-88.10186999999998,^\^"y^\^":44.42120000000004^},^\^"southWestBound^\^":^{^\^"x^\^":-87.91786999999998,^\^"y^\^":44.60520000000004^},^\^"locationTypes^\^":^[^\^"SURFACE_WATER^\^"^],^\^"ageOfDataYear^\^":2018,^\^"keywords^\^":^[^\^"Turbidity^\^",^\^"pH^\^"^],^\^"ivDataOnly^\^":false^}^}" ^
--compressed
import requests
url = "https://labs-beta.usgs.gov/monitoring-location/graphql"
body = {
"operationName": "GetLocations",
"query": "\n query GetLocations (\n $northEastBound: InputPoint!,\n $southWestBound: InputPoint!,\n $locationTypes: [MonitoringLocationSiteType!],\n $ageOfDataYear: Int,\n $keywords: [String!],\n $ivDataOnly: Boolean\n ) {\n getByBoundingBox(\n northEastBound: $northEastBound,\n southWestBound: $southWestBound,\n locationTypes: $locationTypes,\n ageOfDataYear: $ageOfDataYear,\n keywords: $keywords,\n ivDataOnly: $ivDataOnly\n ) {\n count\n features {\n type\n geometry {\n type\n coordinates\n }\n properties {\n id\n agencyCd\n locationType\n locationSubType\n locationName\n locationNumber\n keywords\n }\n }\n }\n }", "variables": {
"northEastBound": {
"x": -88.10186999999998,
"y": 44.42120000000004
},
"southWestBound": {
"x": -87.91786999999998,
"y": 44.60520000000004
},
"locationTypes": [
"SURFACE_WATER"
],
"ageOfDataYear": 2018,
"keywords": [
"Turbidity",
"pH"
],
"ivDataOnly": False
}
}
response = requests.post(url=url, json=body)
print("response status code: ", response.status_code)
if response.status_code == 200:
print("response : ", response.content)
{"data": {"getByBoundingBox": {"count": 1, "totalCount": 1, "features": [{"type": "Feature", "geometry": {"type": "Point", "coordinates": [-88.09888889, 44.445]}, "properties": {"id": "USGS-040850684", "agencyCd": "USGS", "locationType": "SURFACE_WATER", "locationSubType": "Stream", "locationName": "ASHWAUBENON CREEK AT GRANT ST NR WEST DEPERE, WI", "locationNumber": "040850684", "keywords": ["Turbidity"]}}]}}}
Query Design
The Explore USGS Water Data API has a flexible structure. Once a location in selected, data can be throttled and scaled in multiple ways.
