A Catalog of USGS Water-Data Web APIs

Want the latest real-time water data from a river, groundwater well, or other USGS monitoring location? This is your newest open-standard way to do that. SensorThings is being designed to help usher in the Internet of Things. It is a simple-to-understand API that encourages software developers to use it in their applications (previous open standards like WaterML were thorough and meticulous, but tedious to parse to extract the actual data itself).

Endpoint for our beta OGC SensorThings API implementation: https://labs.waterdata.usgs.gov/sta/v1.1/

Getting Started

Want to try out our SensorThings API? We hope to release an example Python Notebook by Spring 2022, so you can try it out for yourself. In the meantime, here’s a super-quick way to dive into it:

1. Make a web request for one of the things (our things are USGS monitoring locations). For example, here is the thing for Colorado River at Lees Ferry, Arizona .
2. Inside the JSON structure² returned for a thing in (1) are elements containing additional URLs that can be opened to obtain data for this station. Find the element named Datastreams@iot.navigationLink and open the URL in this property to see datastreams associated with this thing .
3. The URL in (2) returns an array of recent time-series data available for this station. Each object in the array has a description element describing the time series, as well as a properties element that contains a ParameterCode element describing the time series with a 5-digit USGS parameter code (e.g., 00060 signifies Discharge and 00065 signifies Gage Height).³
4. Following the Observations@iot.navigationLink element’s URL will start returning the data of interest.

You also might like the Internet of Water’s SensorThings resources , and for the more adventurous reader there is the official SensorThings specification .

A majority of data collected and exchanged in the world today has a geographic location as a core attribute. USGS water data is no exception! So we’re adopting the OGC API as a flagship API. Our implementation of OGC API offers detailed metadata about multiple stations for easy map plotting, and offers certain limited forms of water data. We’ve only just begun to use this API and we plan to expand our use of it considerably, particularly as OGC API continues to evolve. Presently we implement its foundational Part 1: Features-Core .

Endpoint for our beta OGC API implementation: https://labs.waterdata.usgs.gov/api/observations/collections/

Getting Started

Want to try out our OGC API? We are considering what developer-friendly materials we can provide and suggestions on client software libraries you might consider. Please check back and also look for other blog posts. In the meantime, here’s a super-quick way to dive into it:

1. Make a web request for the Active Groundwater Level collection .
2. The response provides an overview of this network of USGS monitoring locations, which are modeled as features in a collection. The features themselves in this collection (i.e., the monitoring locations in this network) can be seen here .
3. The properties elements within this response contain helpful monitoring location metadata.
4. More information about any one of these features is available at a more specific URL (e.g., here is the USGS Winslow, Arizona I-40 well ).
5. Digging one level deeper into the observations associated with any feature may offer certain forms of water data we have begun to populate in this API (e.g., the Winslow I-40 well’s observations include daily-values and discrete groundwater levels).

You also might like the provisional Swagger Documentation we have published for our OGC API implementation.

Interested in water quality and the laboratory analyses that inform us about the quality of the nation’s water? Then the flagship Water Quality Portal is for you. It is a joint endeavor among several government agencies that collect these types of data; you can obtain data from the USGS and also other government organizations like the Environmental Protection Agency.

Discrete water-quality data are inherently richer, more complex, and challenging to interpret than time-series data. Accordingly, the primary output format is the relatively complex Water Quality eXchange (WQX) open standard. But fret not! The Water Quality Portal also supports the OGC Web Map Service (WMS) open-standard API to easily get dots put on map tiles and thus on interactive maps. Even though the underlying data are complex and rich in structure, support of WMS allows a low barrier to entry to begin exploring the spatial distribution of these data.

Getting Started

Read our documentation for the portal’s API . It’s about a 15-minute read and should let you begin to understand basic functionality. Or get started even faster by interactively building a search ; after the query is built using the advanced form, the website will give you code you can embed directly into your application.

NOTE WQX data are output in a long format, which has the benefit of creating a standard, pre-defined number of fields that convey important metadata. The downside of this format is that is splits up individual measurements or results for a particular sampling event. However, there are many tools available to help reformat WQX data for ease of analysis. In fact, the USGS has created and maintains the R package dataRetrieval , which can issue necessary API calls and facilitate conversion of the resulting dataset into formats more friendly for immediate use.

The NLDI allows your application to programmatically “swim” up and down the river and stream network of the United States, discovering USGS monitoring locations along the way. It also returns shapes that define watershed boundaries. The output format is GeoJSON, making it easy to integrate into web-based maps. Essentially, it is a web-based API we have placed in front of the National Hydrography Dataset (NHD).

NLDI conveys the relationships between a USGS monitoring location and waterbodies. It also conveys how individual parts of the river and stream network are connected to form the overall national river and stream network. NLDI is, therefore, a form of water metadata. For the actual quantitative water data itself, use other APIs like SensorThings and OGC API.

Getting Started

The best way to understand NLDI is to read its overview documentation . Another helpful starting point can be this overview blog post .

Through some light reverse engineering⁴ of a USGS monitoring location page courtesy of a browser’s network-debugger tool (usually the F12 key), we can observe the function calls these pages make to the NLDI API. Other NLDI API calls are possible, but it may be instructive to inspect these:

1. Upstream flowlines. A GeoJSON LineString representing the river upstream of the station. The distance parameter limits draw distance to 322 kilometers for performance reasons on Monitoring Location Pages, but draw distances up to 10,000 kilometers may be specified.
2. Downstream flowlines. Same as the upstream query, but in a downstream direction.
3. Watershed catchment area. A GeoJSON MultiPolygon that draws the watershed boundary upstream of this station.

The quickest way to integrate USGS time-series water data onto your own web page or into your own application may be the simple process of embedding a nifty bitmap image of a hydrograph. It’s a one-line addition to an HTML file! Minimally all you need is the USGS monitoring location identifier (typically an 8-digit number). The functionality is limited: you cannot customize the bitmap image beyond the parameters we offer you, and the image is not interactive. Still, this remains a popular, low-complexity way to show your favorite river’s recent streamflow or other measured data.

Getting Started

Read our documentation for this API . Or simply paste the following fragment into your HTML, and modify the reasonably self-explanatory URL parameters to the right of the ? as needed (the result will look like this ):

<img src="https://labs.waterdata.usgs.gov/api/graph-images/monitoring-location/09380000/?parameterCode=00060&width=640&title=true&period=P14D" alt="Hydrograph of recent 14 days of 00060 streamflow at 09380000" >

Another potential solution is the USGS Graphing Water Information System JavaScript software library. This library places an interactive hydrograph on your web page with just a few lines of code. It is a more complex approach, however, in that it adds 150-240 KiB of JavaScript to your web page, and the code is provisional in its development. If you’d like to try it, we’d appreciate hearing what you think of it!

Around 2007 we launched a generation of APIs⁵ that output water data in an open-standard format known as WaterML . For years, these were our prime API offerings for water data. Although we are striving to phase these aging APIs out in favor of newer flagship APIs, they will yet be around for some time because existing client software already relies on them, and not all of their functionality has been conserved in our new flagship APIs.

Each API listed below links to URL generation pages⁶ that serve as a form of concise, interactive documentation (a link to fuller documentation also can be found at the top of each of these pages). Although output formats include open-standard WaterML, input arguments are USGS specific and do not conform to any open standard.

• Instantaneous-values data. ⁷ POPULAR These are sensor observations and calculations of natural phenomena made at regular intervals (typically every 15 minutes). These include stream gage height, streamflow (discharge), water temperature, and much more. If you need data only from the last 4 months, we recommend our new flagship SensorThings API over this legacy API. But if you need data farther back into the past, this continues to be the API you should use. Its main output formats are tab-delimited file and WaterML.

• Daily-values data. ⁸ From the 1880s until around 2007, continuous monitoring of water resources by the USGS typically resulted in one statistically reduced data value per day: the daily-mean value (sometimes also daily minimum and maximum values). This was a practical⁹ number of data values that could convey water-resources in printed publications¹⁰ and could be stored digitally up through the 1990s when computer storage was still prohibitively expensive. Some workflows continue to rely on daily values, and any analyses or workflows that go back in time before around 2007 usually must incorporate daily values to achieve historical continuity. Our OGC API offers a subset of USGS daily-values data (groundwater daily values), but until OGC API offers all daily-values data this legacy API may well be what you must use.

• Discrete groundwater levels. ¹¹ Individual manual measurements of groundwater levels made by USGS technicians in the field. These days the flagship OGC API provides these same data in a more modern format. One key ability of this legacy API not (yet) offered by OGC API is the ability to query for multiple monitoring locations at a time.

• Sites. ¹² Key metadata about USGS monitoring locations across the United States such as latitude and longitude, station name, county location, and so forth. These days, this same metadata is available nearly equally well from SensorThings and OGC API in the popular GeoJSON format for getting dots on maps quickly. But this legacy API continues to offer this information in tab-delimited files, as well as Keyhole Markup Language (KML), an XML open standard popular in the early 2000s. One key ability this API offers that our flagship APIs do not (yet) provide is querying for monitoring locations based on the type of data they collect and the time range those data are available. (e.g., all active monitoring locations in Kansas monitoring real-time water temperature ).

• Statistical period-of-record data. ¹³ This API outputs statistical information about time-series data from a USGS monitoring location. It is most popularly known as the API that examines the full period of approved time-series streamflow at a monitoring location and, for each day of the year, calculates the long-term median, maximum, minimum, and other statistical flow percentiles (example ). This same statistical calculation is performed for all other approved time-series data and made available through this legacy API. We have not yet determined how we may convey these data in a flagship API, so until then this is the API you should use.

Starting around the year 2000, we began publishing water data in machine-friendly flat-file formats on a national scale. These URL endpoints are a primitive form of web service from an earlier time in the history of the Web. They output data in simple tab-delimited RDB files and they do not conform to any open standard. The input parameters (URL parameters) are not formally documented and must be deduced by (1) using search tools on web pages, (2) noting the resulting URL, and (3) cleverly incorporating the URL into your software by modifying input parameters as needed.

USGS intends to decommission these endpoints in the coming years, but not until adequate replacements have been developed. Until then, although we caution that these old endpoints may be challenging to incorporate into modern software, you may find them uniquely valuable if they provide the water data your application needs.

• Annual-peaks data. The single highest flow rate and stream water level in a given year is a useful statistic for engineers and others concerned with planning related to water hazards. In recent years these peak data values may be found directly within the instantaneous-values data records. But sometimes, particularly at streamgages with long periods of record and large historic floods, the one annual-maximum flow and water level are original, primary data, not a mere statistical derivation of data in some 12-month time window. In fact, in some cases weeks or even months of hydrologic analysis is undertaken to produce a single annual-peak data value! If your application needs these values, use the search tool linked to here, indicate tab-delimited output, and note the resulting URL (e.g., annual-peak flows and gage height for Colorado River at Lees Ferry, Arizona ).

• Rating-curve depot. Most users do not need the technical and detailed rating curves used to convert gage-height¹⁴ data to streamflow data; they simply need the high-quality streamflow data USGS publishes. But certain key cooperating agencies like the National Weather Service need rating curves for their computer-modeling needs. The ratings depot provides this information, as well as a way to detect when rating curves have been updated by USGS staff. The most popular output table is the expanded, shift-adjusted rating (EXSA), effectively a lookup table for all possible valid values of gage height in hundredth-of-a-foot increments at a given station (e.g., the EXSA table for Barton Springs at Austin, Texas ). Only stage-discharge ratings are available; index-velocity and slope-area curves are not supported.

• Current surface-water conditions in historical context. If your application wishes to create a “dot map” of current streamflow¹⁵ conditions—to what degree USGS monitoring locations are above and below historical flow rates—presently your most practical option is the realtime endpoint of this catalog of legacy endpoints. The output format is JSON, but not an open-standard format such as GeoJSON (e.g., the data needed for a dot-map of Kansas ). We are considering how our flagship APIs might present this valuable information in an open-standard way. It is also possible to calculate this information yourself using the legacy statistical period-of-record API and an API returning the most recent instantaneous values.

• Discrete surface-water field measurements. ¹⁶ To keep a continuous time-series monitoring location operating properly, USGS technicians periodically visit the station and manually measure water depths and flow rate. These data help ensure USGS sensors and rating curves are functioning properly and get repaired and updated as needed. Although typically seen as means-to-an-end water data, they may be useful in some circumstances. If your application needs these values, use the search tool linked to here, indicate tab-delimited output, and note the resulting URL (e.g., all of these measurements for Colorado River at Lees Ferry, Arizona ).

These web services and endpoints should no longer be used. New users and existing users should consider using new flagship or beta APIs that provide the same water data in more modern formats.

• Legacy discrete water-quality data endpoint. You can download tab-delimited “wide” formats of USGS water-quality data by using this search interface, indicating tab-delimited output, and noting the resultant URL (example ). Although this format is convenient for certain workflows, we recommend the Water Quality Portal to obtain discrete water-quality data. We are in the latter stages of a multi-year modernization effort of our discrete water-quality data systems. When that modernization is complete, we intend to decommission this web endpoint.

• Legacy hydrograph bitmap endpoint. A URL that generates a standalone bitmap image of a hydrograph using late 20th-century plotting technology (example ). Please try using our beta hydrograph bitmap-image API instead (above), and give us feedback on what you think of it. This endpoint is scheduled to be decommissioned January 2023.

_{There are some notable acknowledgements for this article.¹⁷}