RainbowStats™ · Command reference

USGS Water Data

Find a river station, discover what it measures, and bring daily water observations into your analysis.

The U.S. Geological Survey collects water observations at monitoring locations across the United States. RainbowStats connects this information to its time-series tools, making it possible to examine river flow, water temperature, gauge height, and other available daily measurements.

Three commands, from discovery to analysis
Command	Purpose	Returns
`USGS`	Retrieve a station’s daily mean observations.	Daily data series
`USGS_SEARCH`	Find stations by state and station-name text.	Station information as text
`USGS_META`	Inspect measurements and periods of record.	Series metadata as text

Quick start: search, inspect, retrieve

stations = USGS_SEARCH("53", "Green River")
details = USGS_META("12113000")
flow = USGS("12113000", "FLOW")

Here, "53" is Washington’s state FIPS code. The search finds station names containing “Green River.” Metadata identifies the measurements available at station 12113000; the final line retrieves its daily mean discharge.

The resulting series can be used with RainbowStats charts, aggregation, regressions, and other time-series operations.

USGS — Retrieve daily observations

USGS("station", "parameter")

Retrieves daily mean observations for one measurement at one USGS station. The default requested period begins January 1, 2000 and runs through the current date. Actual coverage depends on the station and measurement; the latest available observation may lag the current date.

Argument	Description
`station`	USGS station number, supplied as a quoted string. For example, `"12113000"`. The prefixed form `"USGS-12113000"` is also accepted.
`parameter`	A supported measurement alias or a five-digit USGS parameter code, supplied as a quoted string.

Common measurements

Measurement	Accepted aliases	Parameter code
Discharge / streamflow	`FLOW`, `STREAMFLOW`, `DISCHARGE`	`00060`
Water temperature	`TEMPERATURE`, `WATER_TEMPERATURE`	`00010`
Gauge height	`STAGE`, `GAGE_HEIGHT`, `GAUGE_HEIGHT`	`00065`

Other five-digit parameter codes may be used when the station provides a daily mean series for that parameter. Check USGS_META before requesting an unfamiliar measurement.

Examples

flow = USGS("12113000", "FLOW")
flow_by_code = USGS("12113000", "00060")
stage = USGS("12113000", "GAGE_HEIGHT")

The first two expressions request the same discharge series. The third requests daily mean gauge height at the same station.

Keep the leading zeros. Station numbers and parameter codes are identifiers. Always place them in quotation marks: "00060", not 60.

USGS_SEARCH — Find monitoring stations

USGS_SEARCH("state_fips", "search_text")

Searches USGS station names within a state. Supply a two-digit state FIPS code and a nonempty name fragment, such as a river, town, or other text appearing in the station name. Matching is performed at the data source to keep the search focused.

Argument	Description
`state_fips`	Two-digit state FIPS code, such as `"53"` for Washington. Supply the code rather than a postal abbreviation.
`search_text`	Station-name text to match. The current search normalizes this text to uppercase.

stations = USGS_SEARCH("53", "Green River")

Results include station identifiers, names, location information, and other station attributes. Copy the desired station number into USGS_META to inspect its measurements.

A station-name match does not guarantee that flow, temperature, or another particular daily series is available. Discovery and measurement availability are separate steps.

USGS_META — Discover available measurements

USGS_META("station")

Returns metadata for the time series associated with a monitoring station. Use it to identify parameter codes, units, statistics, and the beginning and end of each record.

details = USGS_META("12113000")

Metadata field	What it tells you
`parameter_name` / `parameter_code`	The measurement and its five-digit identifier.
`unit_of_measure`	The reported units, such as `ft^3/s`, `ft`, or `degC`.
`computation_period_identifier`	The observation period, such as `Daily` or `Points`.
`computation_identifier` / `statistic_id`	The statistic or computation, such as `Mean` / `00003`.
`begin` / `end`	The reported period of record for that particular series.
`id`	The unique time-series identifier.

Look for Daily + Mean. Metadata may also list instantaneous measurements, daily maxima or minima, and annual records. The two-argument USGS command retrieves daily means: look for Daily with statistic 00003. Metadata can describe a longer history than the command’s default requested range.

Working with the data

Units are preserved. Values remain in the units supplied by USGS. Check units before comparing stations or combining USGS observations with another source.
Missing is not zero. Missing observations are omitted; reported zeros and valid negative values are retained. Gaps are not automatically interpolated.
Recent observations can change. USGS distinguishes approved and provisional observations. Provisional data are subject to revision.
Daily series contain numeric observations. Per-observation approval and qualifier fields are retained by the data-source layer but are not carried into the returned numeric data series.
Availability varies. A station may have daily flow but no daily temperature, or different coverage for each measurement. An empty result can mean that no matching daily mean observations exist in the requested period.
Downloads are cached. Historical retrieval may take longer on the first request. Later requests can reuse cached responses.

For ecological studies, USGS water observations can complement fish-passage and river-environment data from DART. Align observation dates and check station locations, units, and coverage before estimating a relationship.

Data source and further reading

Source: U.S. Geological Survey, Water Data for the Nation. RainbowStats uses the modern USGS Water Data API.