All Collections
User Guides
Plugins: Connect USGS WaterWatch with Ubidots
Plugins: Connect USGS WaterWatch with Ubidots

Add streamflow data from the U.S. Geological Survey (USGS) to your IoT application in just a few clicks

Written by Sergio M
Updated over a week ago


As of February 28th, 2024, we've found out that the USGS API service for real-time streamflow is no longer publicly available. This means that new and existing USGS WaterWatch data plugins won't work, and will display as "Running with errors".

We're looking at updating the used API with a replacement but this requires getting in contact with USGS for guidance.

WaterWatch is a U.S. Geological Survey (USGS) service with current water streamflow conditions in the United States.

This Plugin retrieves current real-time streamflow conditions from a specified site number. We've seamlessly integrated with WaterWatch web service so you don't have to, enabling you to use Ubidots to log streamflow data in just a few clicks:


Table of Contents

  1. Creating a USGS WaterWatch Plugin

  2. Editing a USGS WaterWatch Plugin

  3. Feedback

1. Creating a USGS WaterWatch Plugin

In your Ubidots account, click on the "Plugins" option under the "Devices" navbar menu, then click on the "+" icon in the upper right corner and select USGS WaterWatch:

Configure your Plugin according to these input settings:


  • Site number: A unique 8- to 15-digit identification number as per USGS database. See here a map with all supported site numbers.

  • Your Ubidots token: Every plugin requires an Ubidots token to make all the requests that provision and update your device.

  • Time interval: How often you'd like to retrieve current streamflow conditions for the specified site. Please note that data is updated hourly; choosing a lower update rate will result in repeated values.


This plugin creates a new device with the following attributes:

  • Device name: Station name as returned in the field "station_nm" in USGS' WebService.

  • Device label: The specified site number.

The created device will contain these variables, which will be updated at the specified time interval:

  • Flow: The volume of water, in cfs units, flowing past a given point in the stream in a given period of time.

  • Stage: The height in foot (ft) of the water in the stream above a reference point (also known as gage height). Gage height refers to the elevation of the water surface in the specific pool at the streamgaging station, not along the entire stream. Gage height also does not refer to the depth of the stream. Measurements of gage height are continually recorded by equipment inside a gagehouse on the streambank.

  • Class: Streamflow condition classification (From 0 to 8).

  • Percentile: The value on a scale of one hundred that indicates the percent of the flow distribution that is equal to or below it.

  • Percentile (Median): Flow / long term median * 100, as returned by USGS.

  • Percentile (Mean): Flow / long term mean * 100, as returned by USGS.

Note: This version retrieves data from the "Current Conditions Real-Time Streamflow Service". Additional services can be incorporated in future versions upon request.

After configuring the Plugin, a new item will appear on the Plugins list. Please allow a few seconds for the plugin to finish its provisioning process, and then refresh your browser. When the status of the Plugin goes from "Configuring" to "Running" then you should see a new device in your Devices list.

2. Editing a USGS WaterWatch Plugin

To edit the Plugin, simply click on the Edit button in the Plugins list view. The same "Input" fields that appeared during the creation process will appear. Please note that, every time the Plugin is updated, a provisioning script will run, overriding the current attributes of the target device:

  • Device name

  • Device label

  • Device icon

  • Device description

  • Device color

  • Variable names

  • Variable units

  • Variable colors

3. Feedback

If you have any ideas on how we could improve this plugin, we'd be happy to hear them. Please leave us a note at

Others also found helpful...

Did this answer your question?