Skip to content

CO-OPS observed water levels

Available since v0.10.0 as noaa:coops-water-levels. The initial adapter fetches six-minute observed water levels for one explicit station. NOAA returns preliminary or verified observations according to availability. Predictions, currents, station discovery, and automatic request chunking are not included.

Require a seven-digit string station, an explicit uppercase datum, and both timestamps. units is metric (default, meters) or english (feet). Supported datum codes follow the Data API documentation: CRD, IGLD, LWD, MHHW, MHW, MTL, MSL, MLW, MLLW, NAVD, and STND. Availability of a datum depends on the station; the service rejects unsupported combinations. Unknown parameters, geographic/text selectors, and variables are rejected.

Offsets are normalized to UTC and the API request fixes time_zone=gmt. Bounds are inclusive, must have zero seconds/microseconds, and span at most 28 days, conservatively within NOAA's one-month limit. A date alone as the end means 23:59 on that day. The adapter constructs one stable CSV request; it checks availability on fetch.

uv run usdata fetch noaa:coops-water-levels \
  --start 2024-05-06T00:00Z --end 2024-05-06T00:12Z \
  -p station=8518750 -p datum=MLLW -p units=metric

The raw CSV retains original header spacing, observations, and quality flags. Use the ordinary CSV reader and rename columns locally if desired. The CSV states none of station, datum, units, or time zone, so the frame carries them in attrs["usdata"]["properties"], and the lockfile keeps them. The small manifest example shows this. Quality p and v mean preliminary and verified; preserve the quality field alongside the flags because their interpretation changes. See the response definitions.

See the service research notes for dated upstream probes.

Metadata sources

Every value in the catalog entry's resolution, cadence, citation, terms, variables, and limits comes from one of these pages. A field the agency does not publish is left empty rather than estimated.

  • Resolution, updates, and the longest window: the Data API documentation, which describes six-minute water levels, monthly verification of the past month, and a one-month retrieval limit; the adapter's MAX_INTERVAL in usdata.providers.noaa.coops sets the declared 28 days inside it.
  • Variables: the CSV header this adapter requests and the response definitions.
  • Terms: the CO-OPS disclaimer, which asks that NOS be acknowledged as the source.
  • Citation: CO-OPS publishes no citation form, so the entry uses the agency, product, and access form.
  • Latency is empty: the API documentation states no lag between observation and availability.

All NOAA datasets.

Reference

noaa:coops-water-levels · Released · Included since usdata 0.10. CO-OPS Observed Water Levels.

At a glance

Parameters

Pass these as --param name=value to the CLI, as params: entries in a manifest, or as keyword arguments to build_query.

Parameter Meaning
datum Required vertical datum: CRD, IGLD, LWD, MHHW, MHW, MLLW, MLW, MSL, MTL, NAVD, STND.
station Required seven-digit CO-OPS station id, for example '8518750'.
units metric (default) or english.

Variables

Variable Units Meaning
Date Time UTC Observation time, requested with time_zone=gmt
Water Level meters Observed water level on the requested datum (metric units)
Sigma meters Standard deviation of the one-second samples in the interval
O or I (for verified) — Count of outliers, or the inference flag on verified data
F — Flat-tolerance limit flag
R — Rate-of-change limit flag
L — Expected-height limit flag: 1 when the value passed the maximum or minimum expected water level
Quality — p for preliminary or v for verified

Catalog facts

  • Availability: since 0.10
  • Domain: Sea level and tides
  • Spatial resolution: One National Water Level Observation Network station per request
  • Temporal resolution: Six minutes
  • Updates: Six-minute observations as the station reports; NOAA verifies the past month's data monthly
  • Longest query window: 28 days
  • Terms of use: https://tidesandcurrents.noaa.gov/disclaimers.html
  • Citation: NOAA National Ocean Service, Center for Operational Oceanographic Products and Services, observed water levels, accessed via usdata
  • Coverage: not specified in the catalog
  • Coverage varies by station, product, and date; the range above does not guarantee observations.
  • Upstream documentation
  • License: US Government Work (public domain)
  • Transport: http
  • Adapter: usdata.providers.noaa.coops:CoopsWaterLevels