USGS Water Services Scraper

USGS Water Services Scraper

Scrape USGS water data from any monitoring site, up to a million records per run. Get streamflow, gauge height, temperature, groundwater levels, and more in a flat, analysis-ready format. Export to CSV, JSON, Excel, or XML.

The USGS Water Data portal is a maze of clicks and manual downloads. This scraper queries the USGS Water Services API directly, pulling instantaneous values, daily summaries, or groundwater levels for any list of site codes. You get clean, structured records without writing a single line of code.

Who uses it	What they scrape USGS Water Services for
Hydrologists	Monitor real-time streamflow and gauge height across a watershed.
Environmental consultants	Pull historical daily values for water quality compliance reports.
Data journalists	Track river levels during a flood event for a news story.
Researchers	Collect groundwater level time series for a long-term study.

What it does

This Actor collects water data from USGS monitoring sites by service type, site code, parameter, and date range, and returns each reading as a flat row.

• 📈 Instantaneous Values: Current readings from active sensors, refreshed every 15 to 60 minutes.
• 📅 Daily Values: Daily statistics like mean, max, and min for any recorded parameter.
• 🕳️ Groundwater Levels: Depth-to-water measurements from dedicated monitoring wells.
• 🎯 Site and Parameter Filtering: Query multiple sites at once and narrow results to specific parameter codes like discharge or pH.
• 📆 Date Range Control: Limit the scrape to a specific time window, or leave dates empty for the most recent readings only.

Results export to CSV, JSON, Excel, or XML, or straight from the API.

What you can do with USGS Water Services data

🌊 Monitor flood conditions.

An emergency manager pulls instantaneous discharge and gauge height for a set of river sites every hour to decide on evacuation orders.

📊 Build a water quality database.

An environmental scientist scrapes daily values for dissolved oxygen and pH across a basin to populate a long-term trend analysis.

📰 Report on drought impacts.

A journalist collects groundwater levels from monitoring wells in an agricultural region to illustrate the severity of a drought.

🏗️ Plan construction dewatering.

A civil engineer pulls historical groundwater levels near a project site to estimate the depth and duration of dewatering needed.

Why choose this scraper

	What you get
No manual downloads	Skip the point-and-click interface and get data for hundreds of sites in one run.
Fixed, flat schema	Every record arrives with the same columns, ready for a database or spreadsheet.
Three data products	Instantaneous values, daily summaries, and groundwater levels from one Actor.
Parameter-aware	Request only the parameters you need, like streamflow or water temperature.

How it compares

No other Store actor targets USGS Water Services the same way, so the honest comparison is with the alternatives teams actually weigh.

	USGS Water Services Scraper	Build it in-house	By hand
Setup	Run it now, zero config	Days of engineering	None, but hours per pull
When USGS Water Services changes	Maintained for you	You fix it	You re-learn the page
Proxies, retries, anti-bot	Built in	Your problem	Browser only
Output	Fixed JSON schema, CSV/Excel export	Whatever you build	Copy-paste
Cost	Pay per result	Engineering time	Analyst hours

Configure the run

Drive the Actor with a list of USGS site codes, a data service endpoint, and optional parameter codes and date range. Filters run as each record is read so only matching observations reach your dataset. The Input tab lists every parameter.

A first run with the defaults:

{
 "maxItems": 10,
 "endpoint": "iv",
 "sites": [
 "01646500"
 ],
 "parameterCodes": [
 "00060",
 "00065"
 ]
}

A larger pull:

{
 "maxItems": 200,
 "endpoint": "iv",
 "sites": [
 "01646500"
 ],
 "parameterCodes": [
 "00060",
 "00065"
 ]
}

Pricing

Pay-per-result: $0.01867 per result collected. You pay only for the results written to your dataset.

Results collected	Approximate cost
100 results	$1.87
1,000 results	$18.67
10,000 results	$186.70

New Apify accounts start with $5 in free credit.

Free users

Free-plan runs return up to 10 results as a preview. Upgrade your Apify plan to collect up to 1,000,000 results per run.

Run it

1. Create a free Apify account with $5 in credit.
2. Open the USGS Water Services Scraper.
3. Set your inputs and any filters, then click Start.
4. Export the results as CSV, Excel, JSON, or XML from the Dataset tab.

Run it programmatically through the Apify API (run-sync-get-dataset-items) or the ApifyClient for JavaScript and Python.

Use with AI agents (MCP)

Give an AI agent live access to USGS Water Services through the Model Context Protocol. Add the Actor to Claude, Cursor, or any MCP client:

$claude mcp add --transport http apify "https://mcp.apify.com?tools=parseforge/usgs-water-services-scraper"

Then prompt it in plain language to run the scraper and read back the results.

Troubleshooting

Why am I getting no results?

Double-check your site codes. They must be 8 to 15 digit numbers. Also verify that the parameter code you requested is measured at that site. Try leaving parameterCodes empty to see all available parameters.

Why is my date range returning an empty dataset?

The site may not have data for that period. Try a wider date range or check the site's period of record on the USGS water data portal. Ensure dates are in YYYY-MM-DD format.

The run is taking a long time.

Querying many sites with a wide date range and all parameters can produce a large volume of data. Reduce the number of sites, narrow the date window, or specify only the parameter codes you need.

I see a 'site not found' error.

The site code may be formatted incorrectly or the site may have been discontinued. Verify the code on the USGS NWIS mapper. Some older sites are archived and may require a different endpoint.

The data values look wrong or are missing.

USGS uses specific codes for missing or estimated data. Check the qualifier fields in your output. A blank value often means the sensor was offline during that time step.

FAQ

Question	Answer
How do I find USGS site codes?	Use the USGS National Water Information System Mapper at waterdata.usgs.gov/nwis/rt. Click on any monitoring point to see its 8 to 15 digit site number.
What parameter codes should I use?	Common codes are 00060 for discharge in cubic feet per second, 00065 for gauge height in feet, and 00010 for water temperature in Celsius. A full list is available on the USGS parameter code lookup page.
Can I scrape more than one site at a time?	Yes. Add as many site codes as you need to the sites array. The Actor queries each one and merges the results into a single dataset.
What is the difference between instantaneous and daily values?	Instantaneous values are the most recent sensor readings, typically updated every 15 to 60 minutes. Daily values are aggregated statistics like the mean, minimum, and maximum for each calendar day.
Does this Actor require an API key?	No. The USGS Water Services API is public and does not require authentication. You can start scraping immediately.
How far back can I pull data?	The date range depends on the site and parameter. Some sites have records going back over a century. Use the startDate and endDate fields to define your window.
What format is the output data?	The Actor returns data in a flat, tabular format. You can export it to CSV, JSON, Excel, or XML from the Apify dataset tab.
Can I get groundwater data with this?	Yes. Select the 'Groundwater Levels' endpoint and provide the site codes for your monitoring wells. The Actor returns depth-to-water measurements.
What happens if I leave the date fields empty?	The Actor returns only the most recent readings available for the selected sites and parameters.
Is there a limit to how many records I can scrape?	You can set the maxItems limit up to 1,000,000 records per run. The USGS API itself has no hard rate limit for this usage pattern.

Related actors

Browse the full ParseForge collection for more scrapers.

🆘 Need help? Email parseforge@protonmail.com with your run ID, your input, and what you expected.

⚠️ Disclaimer. This Actor is unofficial and is not affiliated with, endorsed by, or sponsored by U.S. Geological Survey. It collects only publicly available data. You are responsible for using the collected data in compliance with the source's terms of service and applicable data-protection laws, including GDPR, CCPA, and PIPL. Do not use it to collect personal data unlawfully.