Getting started
What is this?
An embeddable panel showing live river conditions — streamflow, gauge height, a six-hour trend and a chart — from any of about 10,600 active USGS stream gauges in the United States. You pick your rivers, style it, and paste one snippet.
Do I need an account or an API key?
No. No sign-up, no email, no key, no quota. The widget reads USGS from your visitor’s browser, and USGS allows that anonymously.
Where do I paste it?
Anywhere that accepts HTML: an Elementor HTML widget, WordPress’s Custom HTML block,
a Squarespace code block, a Shopify theme file, or straight into a hand-written page.
If your platform strips <script>, use the iframe embed instead.
My old USGS graphs stopped working. Is that related?
Almost certainly. USGS retired waterservices.usgs.gov and the old
nwisweb/graph images, so thousands of pages that embedded them now show
404s or blanks. Those were static image tags with nowhere to push a fix. This widget
runs on the current API, and because the script is served centrally, future API changes
can be handled without you re-pasting anything.
Script or iframe
Which should I use?
The script embed, almost always. Use the iframe only when your platform will not run a script, or when it only accepts a URL.
- Script embed
- Inherits your site’s typeface, resizes with whatever container it sits in, needs no fixed height, and is one small file shared by every widget on the page.
- iframe embed
- Works where scripts are blocked — Wix, free-tier Squarespace, Notion, Substack, locked-down intranets.
What do I give up with an iframe?
- Height is fixed and guessed. An iframe cannot size itself to its content, so the generated snippet estimates a height from your settings. Change the chart or add a gauge and you may need to adjust it.
- It cannot inherit your fonts. Styles do not cross the frame boundary, so it falls back to a system typeface.
- It is a second page load. Slightly slower, and one more request.
- It is invisible to your page. Nothing outside can style or measure it.
None of this is fatal — the iframe renders exactly the same card. It is simply a worse fit when a script is an option.
I pasted it and nothing appears.
- Check the page is not in a builder preview that blocks scripts. Save and view the live page.
- Check your platform did not strip the
<script>tag — view source and look for it. If it is gone, switch to the iframe embed. - Open the browser console. Without JavaScript the embed stays a working link to the USGS station page, which is the intended fallback rather than a failure.
Layout and multiple widgets
Can I put several on one page?
Yes, as many as you like, each with its own gauges and styling — a hero river above the fold, a compact grid below it, one at the foot of a blog post. The loader is id-guarded, so pasting the snippet alongside every embed still loads the script exactly once. See a page doing all four.
One embed with six gauges, or six embeds?
Whichever suits the layout. One embed with several gauges lays them out in a responsive grid together; separate embeds let your own page decide where each sits. Widgets asking for the same gauges share a single request either way.
Is it responsive?
It sizes to its container rather than to the viewport, so the same embed works in a full-width band, a 300px sidebar or a phone without a media query on your end.
Where the data comes from
Who serves the numbers?
The U.S. Geological Survey, read directly by your visitor’s browser from
api.waterdata.usgs.gov. We are not in the middle of it.
How fresh is it, and will it match the USGS site?
It matches exactly, and that is the reason for reading direct. USGS publishes on a roughly 15-minute cycle, and the widget shows whatever the API is serving at the moment the page loads. An angler who checks your page and then checks waterdata.usgs.gov or a river app sees the same number.
A cached middle layer would have been cheaper for us and would have made your page the one that looked wrong.
Does it update while the page is open?
Every 15 minutes by default, matching the publish cycle. Refreshing faster returns the same number twice. A visitor who reads and leaves makes one request.
What does “provisional” mean?
Real-time readings have not yet been reviewed and approved by USGS, and may be revised later. USGS requires that notice to travel with the data, so every card carries it and links to the source station. It is not a sign anything is wrong.
Can it show non-USGS gauges?
Not yet. Some rivers are gauged by dam operators, state agencies or NOAA’s river forecast centres, each with a different API. Only USGS stream gauges are supported today.
When a reading is missing
The card shows gauge height but no streamflow.
That gauge does not publish discharge. Plenty of stations measure stage only — the Bogachiel in Washington is one. Ask a gauge for a reading it does not carry and the field simply does not appear. The builder warns you about this when you pick your metrics.
Why is water temperature greyed out?
Only about one gauge in six carries a thermometer. The builder disables the option when your chosen gauge is not one of them.
It says the gauge is not reporting.
Many gauges, especially in the West, are pulled for the winter and returned in spring. Others go offline for maintenance or after high water damages equipment. These stay searchable and are labelled “quiet” in the builder rather than hidden — knowing a river has a gauge that is currently down is worth something.
It says “delayed”.
The last reading is more than three hours old. Usually a telemetry problem at the station rather than anything to do with your page.
Styling
How much can I change?
Seven colours independently — accent, numerals, body text, labels, card background, border, and hydrograph gridlines — plus corner radius, drop shadow, density, typeface and units. Start from a theme and override what clashes.
Can I remove the card entirely?
Yes. Turn off the background and border and the readings sit straight on your own
section. The bare theme goes further and inherits your colours.
Sparkline or hydrograph?
A sparkline is a bare trend line with no axes; it reads at a glance in a sidebar. A hydrograph is the chart anglers already know from USGS — a real axis in the gauge’s units, day labels, and the full 15-minute record rather than daily averages. Gridlines on it are optional; axis numbers stay either way.
Which timezone are times shown in?
The river’s, not the visitor’s. Someone planning a trip from Denver wants
lodge time. The builder bakes the gauge’s timezone into the embed;
data-tz overrides it.
Privacy
Does it set cookies?
No. No cookies, no local storage, no fingerprinting, no visitor identifier of any kind, and no third-party analytics. Embedding it adds nothing to your consent banner.
What do you count, then?
A single request per render tells us the embedding domain, the theme, which gauges and a
coarse country from Cloudflare. Never an IP address, a user agent, a session, or anything
about the page beyond its domain. data-beacon="0" switches it off.
Do you publish who uses it?
No. Only aggregate totals — the install count on the homepage. Which sites embed it is our customers’ business.
Licensing
Is it really free, including for client work?
Yes. Personal or commercial, on your own site or one you built for a client, and you may charge for the build. No sign-up and no quota.
Who owns the data?
Nobody. USGS data is a work of the U.S. Government and sits in the U.S. public domain, free to use, adapt and redistribute without permission. USGS asks to be credited as the source, which every card does and which is not removable.
And the code?
MIT. Use it, fork it, host your own copy. Machine-readable licence.
Technical
Which browsers?
Modern browsers get full style isolation via Shadow DOM. Older ones, back to IE11, get a scoped inline render. With JavaScript off the embed stays a working link to the USGS station page.
Will it slow my page down?
The script is about 12 KB compressed, loads asynchronously after your content, and has no dependencies. A card shows a skeleton until its numbers arrive, so nothing jumps.
What if USGS goes down?
The widget falls back to our cached copy, up to fifteen minutes behind, which beats a blank card. If that is also unreachable, the embed stays a link to the station page.
Can I host it myself?
Yes — the whole project is MIT and deploys to Cloudflare Pages. Point
data-river-api at your own origin.
Something is broken
A widget stopped showing numbers. What now?
Work through the troubleshooting guide. It splits on the question that matters first — is one widget affected or all of them — because the answers are entirely different. One is nearly always that gauge; all of them is the data source, the script, or the page.
It includes a button that makes a single live request to a USGS gauge when you press it, so you can tell in one click whether the data source is up before doing anything else.
Where do I find the error?
Open your browser’s developer tools, go to the Console, reload the page, and search
for River Widget. Everything the widget reports is prefixed that way.
For a fuller picture, type RiverWidget.diagnose() and press enter: it prints
the version, every embed on the page, what each one asked for, and the recent errors.
How do I report a bug or ask for a feature?
Through the support repository, which holds the issue tracker, release notes and
reporting instructions rather than code. Include the page URL, what you expected, what
you saw, and the RiverWidget.diagnose() output.
Open an issue, or see
the troubleshooting guide.