USGS Streamflow Scraper

Export current USGS streamflow and river gauge observations from the official USGS Water Services API. Select known gauges, a US state, or a geographic bounding box and receive normalized discharge and gage-height rows ready for spreadsheets, GIS tools, dashboards, and scheduled monitoring.

The Actor uses a public, keyless USGS endpoint. It does not scrape visual pages, require an account, or use a proxy.

What does USGS Streamflow Scraper do?

The Actor requests the latest instantaneous values available for your location filter and selected USGS parameter codes. It converts nested WaterML JSON into one flat row for each station, parameter, and observation.

Each result includes:

• official station ID and name;
• coordinates and hydrologic location fields;
• parameter code, name, and description;
• numeric value and source unit;
• observation timestamp;
• qualifier codes and normalized approval status;
• USGS station and API provenance links;
• retrieval time.

USGS no-data sentinel values are returned as null, not as valid measurements.

Who is this Actor for?

• Water operations teams refreshing selected river-gauge readings.
• Flood analysts assembling current official observations for downstream models.
• Anglers, paddlers, and recreation apps checking discharge or gage height.
• Researchers and journalists exporting source-linked measurements.
• GIS and data engineers feeding scheduled USGS observations into pipelines.

This Actor provides measurements, not forecasts, alerts, or flood-stage decisions.

Why use this USGS streamflow exporter?

USGS WaterML responses are authoritative but nested. The Actor supplies a stable, flat dataset and the same input contract for site, state, and bounded-area queries. It also handles transient official-host failures with bounded retries and an alternate official USGS hostname.

The default dataset works directly with Apify exports, API clients, webhooks, Zapier, Make, Google Sheets, and database integrations.

Choose a location mode

Provide exactly one location selector:

1. siteIds for a stable list of known gauges;
2. stateCode for current observations in one US state; or
3. boundingBox for a GIS-style area query.

Combining location modes fails validation instead of silently broadening the request.

Input parameters

Field	Type	Default	Description
siteIds	string array	—	1–100 numeric USGS monitoring-location IDs.
stateCode	string	—	Two-letter US postal abbreviation such as CA.
boundingBox	number array	—	[west, south, east, north] in decimal degrees.
parameterCodes	string array	00060, 00065	1–10 five-digit USGS parameter codes.
maxItems	integer	100	Maximum rows saved, from 1 to 10,000.

Common parameter codes:

• 00060 — discharge in cubic feet per second;
• 00065 — gage height in feet;
• 00010 — water temperature in degrees Celsius where available.

Availability varies by station. A requested parameter that a station does not measure produces no row.

Get started

1. Open the Actor input page.
2. Keep the prefilled site 01646500, or replace it with your gauges.
3. Keep discharge and gage height, or add supported parameter codes.
4. Set maxItems for your downstream workflow.
5. Click Start.
6. Open the dataset and export JSON, CSV, Excel, XML, or RSS.

Example input for one gauge:

{
  "siteIds": ["01646500"],
  "parameterCodes": ["00060", "00065"],
  "maxItems": 10
}

Example state query:

{
  "stateCode": "CA",
  "parameterCodes": ["00060", "00065"],
  "maxItems": 100
}

Example bounded-area query near Sacramento:

{
  "boundingBox": [-121.65, 38.45, -121.25, 38.75],
  "parameterCodes": ["00060", "00065"],
  "maxItems": 50
}

Output fields

Field	Meaning
stationId	Official USGS monitoring-location ID.
stationName	Official station name.
latitude, longitude	Station coordinates.
stateCode, countyCode	Numeric source geography codes.
hydrologicUnitCode	USGS hydrologic unit code.
siteTypeCode	Source site type, for example ST.
parameterCode	Five-digit USGS parameter code.
parameterName	Human-readable parameter name.
parameterDescription	Detailed source description.
value	Numeric reading, or null for source no-data.
unit	Source unit code.
observedAt	Timestamp with station timezone offset.
qualifiers	USGS qualifier codes such as P or A.
status	provisional, approved, or unknown.
methodId	Source method ID where supplied.
sourceUrl	Public station page.
requestUrl	Official API request used.
retrievedAt	UTC normalization time.

Example result

Values change continuously. A current result has this shape:

{
  "stationId": "01646500",
  "stationName": "POTOMAC RIVER NEAR WASH, DC LITTLE FALLS PUMP STA",
  "latitude": 38.94977778,
  "longitude": -77.12763889,
  "stateCode": "24",
  "countyCode": "24031",
  "hydrologicUnitCode": "020700081005",
  "siteTypeCode": "ST",
  "parameterCode": "00060",
  "parameterName": "Streamflow, ft³/s",
  "parameterDescription": "Discharge, cubic feet per second",
  "value": 1330,
  "unit": "ft3/s",
  "observedAt": "2026-09-19T09:50:00.000-04:00",
  "qualifiers": ["P"],
  "status": "provisional",
  "methodId": 69928,
  "sourceUrl": "https://waterdata.usgs.gov/monitoring-location/01646500/",
  "requestUrl": "https://nwis.waterservices.usgs.gov/nwis/iv/?format=json&sites=01646500",
  "retrievedAt": "2026-09-19T13:55:00.000Z"
}

How much does it cost to export USGS river gauge observations?

Pricing is pay per event. A run has a $0.0001 start fee plus one observation event for each saved row. On the BRONZE tier, an observation is $0.00728.

BRONZE billing examples:

Saved observations	Charged events
1	1 start + 1 observation
10	1 start + 10 observations
25	1 start + 25 observations
100	1 start + 100 observations

Multiply the active observation price by the saved count and add one start fee. Your active Apify pricing tier determines the exact price displayed in Console. Charges exclude platform-plan costs and may be affected by refunds, fraud, disputes, taxes, corrections, or clawbacks.

Rows rejected during normalization and empty results do not incur observation events.

Schedule recurring river monitoring

Create an Apify schedule for hourly or daily runs. Prefer siteIds for a stable watchlist. Send completed datasets through a webhook or integration, then compare value, observedAt, and status with your previous run.

The Actor itself does not persist baselines or issue alerts. Your downstream system decides what change is meaningful.

Export to spreadsheets and data pipelines

Use the dataset export menu for CSV or Excel. For automated ETL, read the default dataset API after the run succeeds. Stable station IDs and parameter codes make suitable compound keys; include observedAt when retaining a time series.

Do not interpret retrievedAt as the measurement time. Use observedAt for the actual observation.

Run through the Apify API with cURL

curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~usgs-river-gauge-levels/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteIds":["01646500"],"parameterCodes":["00060","00065"],"maxItems":10}'

Keep tokens in environment variables or a secret manager. Never commit them.

Run with JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/usgs-river-gauge-levels').call({
  siteIds: ['01646500'],
  parameterCodes: ['00060', '00065'],
  maxItems: 10,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Run with Python

import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/usgs-river-gauge-levels').call(run_input={
    'siteIds': ['01646500'],
    'parameterCodes': ['00060', '00065'],
    'maxItems': 10,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)

Use with Apify MCP

Add the Actor to Claude Code:

claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/usgs-river-gauge-levels"

Claude Desktop, Cursor, and VS Code MCP setup

Use this same remote-server JSON in Claude Desktop, Cursor, or VS Code's MCP configuration:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/usgs-river-gauge-levels"
    }
  }
}

Example prompts:

• “Get the latest discharge and gage height for USGS station 01646500.”
• “Export up to 50 current USGS observations in this Sacramento bounding box.”
• “Fetch California streamflow observations for my spreadsheet pipeline.”

Reliability and retry behavior

The Actor first calls nwis.waterservices.usgs.gov. Transient failures receive one bounded retry; the Actor then tries the alternate official waterservices.usgs.gov hostname. Each request has a 45-second timeout.

After all bounded attempts fail, the run fails visibly. It does not return a misleading empty success for an upstream outage.

Limits and data freshness

• Results are the latest instantaneous values returned by USGS, not historical archives.
• maxItems limits saved rows; the upstream state or area response may contain more series.
• A gauge may not publish every requested parameter.
• USGS can mark data provisional and later revise it.
• Source coverage, cadence, station status, units, and methods vary.
• Large state queries depend on official service response size and availability.
• USGS has announced migration away from legacy Water Services in 2027; this Actor may require a future API migration.

Legality and responsible use

The Actor retrieves public US government hydrologic observations. Follow USGS terms, notices, and attribution guidance. Preserve sourceUrl, requestUrl, qualifiers, units, and timestamps when republishing results.

Do not treat a raw gauge reading as an emergency warning, forecast, navigation guarantee, or safety instruction. Consult official local authorities and relevant National Weather Service products for hazardous conditions.

The Actor is independently operated and is not affiliated with or endorsed by the USGS.

FAQ and troubleshooting

Why did I get “Provide exactly one location filter”?

Remove extra location fields. Keep only siteIds, stateCode, or boundingBox.

Why is the dataset empty?

The selected stations or area may not have a current value for the requested parameter codes. Confirm the codes and station activity on the linked USGS pages. An actual upstream failure causes a failed run instead of an empty success.

Why is value null?

USGS returned its no-data sentinel for that series. The Actor deliberately converts the sentinel to null so it cannot be mistaken for a physical reading.

Why is the status provisional?

A P qualifier means USGS may revise the measurement. An A qualifier is normalized as approved; unrecognized combinations remain unknown while the raw codes stay in qualifiers.

Can I request history?

Not in this release. It exports the latest instantaneous observation available per returned time series. Use a schedule and store successive datasets if you need a recurring snapshot workflow.

Related automation-lab Actors

• Weather.gov Active Alerts Tracker — pair observations with official active weather alerts.
• NOAA Historical Weather Observations — export bounded historical daily weather station data.
• NOAA Buoy Data Scraper — retrieve marine station observations.

Support

Use the Actor issue tab with a sanitized input, run ID, expected result, and observed behavior. Do not include Apify tokens or other credentials.