Something isn’t showing

It renders differently each time you reload

Cards that are complete on one load and missing a chart on the next, or that say Cached sometimes and not others, are nearly always one thing: the page is asking USGS for more than one visitor is allowed in an hour.

Two questions answer it

How many separate widgets are on the page, and how many people are loading it? That is the whole diagnosis. USGS allows a visitor 1,000 requests an hour, and the page spends some of that every time it loads. If it spends more than it has, the readings start coming from our cached copy instead — which is the widget catching the problem, not causing it.

The cost is per widget, not per river. One widget costs the same whether it holds one river or six, because all of them are fetched together. So the number that matters is how many separate widgets you placed:

Six rivers in one widget costs exactly a sixth of the same six placed separately. If a page is struggling, that is almost always the fix, and it is only a matter of rebuilding the embed.

Two things make the numbers tighter than they look. USGS forbids browsers from storing the readings, so every reload starts over. And each widget refreshes itself every 15 minutes, so a tab left open on a six-widget page keeps spending — about 72 requests an hour with nobody touching it.

Who actually runs out

Rarely an ordinary visitor: 333 page loads in an hour is not normal browsing. The two who do are you, while building the page — reloading to check your work is the fastest way to spend it — and visitors sharing one connection, such as an office, a school, a hotel or a mobile network, where everyone behind it draws on the same allowance.

So an allowance problem usually looks like: fine for visitors, odd for you. If it only misbehaves on your own machine, wait an hour and look again before changing anything.

Fixes, in order of effect

1. Put several gauges in one embed

   Up to six gauges per embed cost the same as one. This is the biggest single win and it is just regenerating the embed code.

2. Or switch that page to data-source="proxy"

   If the layout genuinely needs each gauge placed separately — a river, then a paragraph, then the next river — add data-source="proxy" to each embed. The readings then come from our API instead of the visitor’s browser, which makes zero USGS requests from their machine and cannot be rate limited by what anyone else on their network is doing.

   The trade-off is real and worth stating: readings can be up to 15 minutes old, and the page then depends on our service being up rather than only on USGS. See the FAQ on choosing a data source.

3. Or ask for less per card

   Turning off the chart, or the 6-hour trend, removes one request per embed each. A page of plain current-flow numbers is a third of the cost.

4. Raise or disable the auto-refresh

   data-refresh="0" stops the 15-minute update. Useful on pages with many embeds where visitors do not linger.

Would a USGS API key help?

This is the first thing a developer asks, and the answer is counter-intuitive: no, and it would usually make things worse.

A free USGS key does not raise the allowance. It is the same 1,000 an hour — it just counts against the key instead of against the visitor. That sounds harmless until you notice what the widget currently does: it reads from each visitor’s own browser, so every visitor brings their own 1,000. A hundred visitors an hour means a hundred separate allowances.

Put one key into the page and all of them share a single allowance instead. At three requests a visit, a site that was comfortable starts failing at a few hundred visitors an hour. A key in a web page is also readable by anyone who views the source, so it is not really yours once it ships.

A key is worth having where you control the traffic and can cache — on a server, not in a browser. That is precisely what data-source="proxy" already is: our key, our cache, one request per gauge per 15 minutes shared across everyone using it. If you would rather that server were yours, self-host the script and point it at your own proxy; the self-hosting guide covers what you take on.

What “Cached” means when you see it

It means that card could not be read from USGS directly, so it came from our copy instead. The numbers are real and usually minutes old — it is the widget catching a failure rather than showing you a blank. Seeing it occasionally on a busy page is the system working. Seeing it constantly means the page is over the request budget above.

Before version 2.4.0 this situation produced a card with numbers and no chart and no explanation, because a failed chart request was ignored rather than retried. If you are seeing silent missing charts, you are on an older cached copy of the script — hard-refresh, and confirm with RiverWidget.diagnose().

One widget is not showing data

1. Check the gauge itself is reporting

   This is the most common answer by a distance. Gauges are pulled for the winter, taken down for maintenance, and knocked out by high water. Open the station page for that gauge on the USGS site — if it has no recent reading there, it has none to give us either.

   The card will say “This gauge is not reporting right now” or “Delayed” when this is what is happening.

2. Check the reading you asked for exists

   Not every gauge measures everything. Many report gauge height but not streamflow, and only about one in six carries a thermometer. If you asked for a reading the gauge does not publish, that field is simply absent. Rebuild the embed and the builder will warn you if this is the case.

3. Rebuild the embed and re-paste it

   Quickest way to rule out a mangled snippet. Page builders occasionally strip attributes or rewrite quotes. Build it again, paste over the old one, and reload the live page — not the editor preview, which often blocks scripts.

4. Still broken? Look at the console

   Open your browser’s developer tools (F12, or right-click → Inspect → Console), reload the page, and search the console for River Widget. Everything the widget says is prefixed that way, so it is the only thing you will find.

   Then paste this in and press enter for a full report:

   RiverWidget.diagnose() Copy

   Send both to whoever maintains the site.

Every widget is blank

Start by testing USGS directly

The widget reads the U.S. Geological Survey from your browser, so if USGS is having trouble every widget everywhere goes quiet at once. This makes one live request to a gauge on the Madison River in Montana, only when you press it.