# Usgs Water Levels Scraper (`b2b_lead_generation/usgs-water-levels-scraper`) Actor Extract USGS streamflow and gage height data by entering a site number or state code. Automatically archives river discharge and stage readings into structured datasets ready for export as JSON, CSV, or Excel for easy water monitoring and analysis. - **URL**: https://apify.com/b2b_lead_generation/usgs-water-levels-scraper.md - **Developed by:** [B2B Lead Generation](https://apify.com/b2b_lead_generation) (community) - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.99 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ## USGS Water Data Scraper: Streamflow & Gage Height

USGS Water Data Scraper

Effortlessly pull instantaneous USGS water monitoring data, including streamflow and gage height, for specific tracking sites or entire U.S. states. Export structured hydrological readings directly into JSON, CSV, or Excel for analysis and archiving. Instead of manually copying tables from web pages, this tool collects standardized time-series records in bulk, keeping your environmental workflows organized and up-to-date. ### Use Cases - **Streamflow tracking:** Archive discharge data for specific monitoring gages on a consistent schedule. - **Statewide sweeps:** List active stream sites across any state to pull the latest instantaneous measurements in bulk. - **Gage height monitoring:** Quickly switch parameter codes to track water stage instead of volume. - **Operations & reporting:** Streamline data pipelines by exporting structured records directly into spreadsheets or data warehouses. ### Extracted Data Points Each record captures complete time-series metadata, including: - Site name, network identifiers, and agency codes - Variable descriptions, parameters, and measurement units - Timestamped readings and quality qualifiers ### Input Parameters | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `mode` | string | `iv` | Instantaneous values mode (one row per site and parameter series). | | `stateCd` | string | empty | Two-letter state code. When specified, lists active stream sites in that state automatically. | | `sites` | array | `["11447650"]` | Specific USGS site numbers to query (used when `stateCd` is empty). | | `parameterCd` | string | `00060` | Parameter code (`00060` for discharge in cubic feet per second, `00065` for gage height in feet). | | `period` | string | `PT2H` | ISO-8601 duration window (e.g., the last two hours). | | `maxItems` | integer | `100` | Maximum dataset rows limit (hard cap at 1000). | | `timeoutSecs` | integer | `300` | Wall-clock limit for the run in seconds. | #### Example Input ```json { "mode": "iv", "sites": ["11447650"], "parameterCd": "00060", "period": "PT2H", "maxItems": 100, "timeoutSecs": 300 } ``` ### Output Format ```json { "sourceInfo": { "siteName": "SACRAMENTO R A FREEPORT CA", "siteCode": [ { "value": "11447650", "network": "NWIS", "agencyCode": "USGS" } ] }, "variable": { "variableName": "Streamflow, ft3/s", "variableDescription": "Discharge, cubic feet per second" }, "values": [ { "value": [ { "value": "14100", "qualifiers": ["P"], "dateTime": "2026-10-11T12:30:00.000-07:00" } ] } ], "name": "USGS:11447650:00060:00000" } ``` ### How It Works 1. Reads configuration parameters and applies row limits and timeouts. 2. Retrieves site lists or queries instantaneous values efficiently in structured batches. 3. Handles temporary network interruptions smoothly with built-in retry intervals. 4. Logs empty series and records errors cleanly without interrupting the overall execution flow. 5. Generates an export-ready dataset available in JSON, CSV, or Excel formats. ### Frequently Asked Questions **How do I export data for an entire state?** Set the `stateCd` parameter to a target state abbreviation (such as `ri`) and leave the `sites` array empty. **What is the difference between parameter codes 00060 and 00065?** `00060` measures discharge in cubic feet per second, while `00065` measures gage height in feet. **Can I export to Excel or CSV?** Yes. Datasets can be downloaded instantly in JSON, CSV, or Excel formats from your run overview. *** ### Legal & Compliance #### Trademark Notice USGS Water Levels and related names, logos, and trademarks belong to their respective owners. Their use in this documentation is solely to identify data compatibility and does not imply affiliation, sponsorship, or endorsement. #### Disclaimer This tool is an independent utility and is not affiliated with, endorsed by, or officially connected to third-party data providers. Users are responsible for ensuring their usage complies with relevant terms of service and usage guidelines. #### Is web scraping legal? This tool collects publicly available hydrological data without bypassing access controls. Collecting public data is standard practice, but proper compliance requires considering how the data is used: - **Personal data:** Ensure dataset usage respects regional privacy regulations when combining outputs with personal records. - **Copyright & Terms:** Respect the terms of use, usage limits, and licensing terms set by data providers. - **Legal advice:** This summary is provided for general informational purposes and does not constitute formal legal counsel. # Actor input Schema ## `mode` (type: `string`): Instantaneous values (iv) reads the USGS NWIS instant-values service. Each row is one time series for a site and parameter. ## `stateCd` (type: `string`): Two-letter state code such as ri. When this is set, the actor lists active stream sites in that state and reads their instantaneous values. Leave blank to use the sites list instead. ## `sites` (type: `array`): USGS site numbers, one per line. Used when state code is empty. The default is Sacramento River at Freeport, site 11447650. ## `parameterCd` (type: `string`): NWIS parameter code. 00060 is discharge in cubic feet per second. 00065 is gage height in feet. ## `period` (type: `string`): ISO-8601 duration of history to request, such as PT2H for the last two hours. Sent as the period parameter on the instant-values service. ## `maxItems` (type: `integer`): Maximum dataset rows for this run, including error rows. Values above 1000 are clamped to 1000. ## `timeoutSecs` (type: `integer`): Stop starting new USGS requests after this many seconds. This does not replace the Apify run timeout. ## `requestTimeoutSecs` (type: `integer`): Seconds to wait for a single USGS HTTP response before retrying. ## `proxyConfiguration` (type: `object`): Optional proxy for USGS requests. The default sends traffic directly, with no Apify Proxy. Do not use proxies to get around USGS rate limits. ## Actor input object example ```json { "mode": "iv", "stateCd": "ri", "sites": [ "11447650" ], "parameterCd": "00060", "period": "PT2H", "maxItems": 100, "timeoutSecs": 300, "requestTimeoutSecs": 30, "proxyConfiguration": { "useApifyProxy": false } } ``` # Actor output Schema ## `datasetUrl` (type: `string`): API URL for the default dataset of this run. ## `datasetItemsUrl` (type: `string`): Item list for the default dataset. ## `overviewUrl` (type: `string`): Overview table of instantaneous value series. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "iv", "stateCd": "", "sites": [ "11447650" ], "parameterCd": "00060", "period": "PT2H", "maxItems": 100, "timeoutSecs": 300, "requestTimeoutSecs": 30, "proxyConfiguration": { "useApifyProxy": false } }; // Run the Actor and wait for it to finish const run = await client.actor("b2b_lead_generation/usgs-water-levels-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "iv", "stateCd": "", "sites": ["11447650"], "parameterCd": "00060", "period": "PT2H", "maxItems": 100, "timeoutSecs": 300, "requestTimeoutSecs": 30, "proxyConfiguration": { "useApifyProxy": False }, } # Run the Actor and wait for it to finish run = client.actor("b2b_lead_generation/usgs-water-levels-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "mode": "iv", "stateCd": "", "sites": [ "11447650" ], "parameterCd": "00060", "period": "PT2H", "maxItems": 100, "timeoutSecs": 300, "requestTimeoutSecs": 30, "proxyConfiguration": { "useApifyProxy": false } }' | apify call b2b_lead_generation/usgs-water-levels-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,b2b_lead_generation/usgs-water-levels-scraper" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/FTChLWjzuBWHZ4DOd/builds/9Ld9URCZLXZ4VjBe1/openapi.json