Response Fields

This page documents the fields returned by NOAA CO-OPS API responses. Field names are terse single-character codes inherited from the upstream API. Understanding them is essential for parsing tool responses.

---

Field Reference

Common fields

These fields appear across multiple response types.

Field	Context	Description	Format / Values
t	All responses	Timestamp	Local station time: YYYY-MM-DD HH:MM
f	All observations	Data quality flags	Comma-separated integers (e.g. "0,0,0,0")

Tide predictions

Fields returned by get_tide_predictions.

Field	Description	Format / Values
t	Timestamp	YYYY-MM-DD HH:MM
v	Predicted water level	String-encoded float, feet above datum
type	Tide type (hilo interval only)	"H" (high tide), "L" (low tide)

Note

The type field is only present when using the "hilo" interval. Hourly ("h") and 6-minute ("6") interval responses omit it.

Observed water levels

Fields returned by get_observed_water_levels.

Field	Description	Format / Values
t	Timestamp	YYYY-MM-DD HH:MM
v	Observed water level	String-encoded float, feet above datum
s	Sigma (standard deviation)	String-encoded float, feet
f	Data quality flags	Comma-separated integers
q	Quality assurance level	"p" (preliminary), "v" (verified)

Wind

Fields returned by get_meteorological_data with product="wind".

Field	Description	Format / Values
t	Timestamp	YYYY-MM-DD HH:MM
s	Wind speed	String-encoded float, knots
d	Wind direction	String-encoded float, degrees true (0-360)
dr	Compass direction	String abbreviation: N, NE, E, SE, S, SW, W, NW, etc.
g	Gust speed	String-encoded float, knots
f	Data quality flags	Comma-separated integers

Other meteorological products

Fields returned by get_meteorological_data for non-wind products (air_temperature, water_temperature, air_pressure, conductivity, visibility, humidity, salinity).

Field	Description	Format / Values
t	Timestamp	YYYY-MM-DD HH:MM
v	Measured value	String-encoded float, units depend on product
f	Data quality flags	Comma-separated integers

---

Value Units by Product

All values are returned as strings and must be parsed to numeric types. The NOAA API is configured with units=english by default.

Product	Field	Unit	Notes
predictions	v	feet	Height above the specified datum
water_level	v	feet	Height above the specified datum
water_level	s	feet	Standard deviation of 6-minute measurement
air_temperature	v	degrees Fahrenheit
water_temperature	v	degrees Fahrenheit
wind	s	knots	Sustained wind speed
wind	g	knots	Peak gust speed
wind	d	degrees true	0 = north, 90 = east, 180 = south, 270 = west
air_pressure	v	millibars (hPa)	Standard atmospheric pressure is ~1013.25 mb
conductivity	v	mS/cm	Millisiemens per centimeter
visibility	v	nautical miles
humidity	v	percent	Relative humidity (0-100)
salinity	v	PSU	Practical Salinity Units

Caution

All numeric values are returned as strings from the NOAA API (e.g. "4.521", "12.50"). Parse them to float before performing arithmetic.

---

Data Quality Flags

The f field contains comma-separated integer flags indicating data quality. A value of "0,0,0,0" indicates no quality issues.

Individual flag positions and values vary by product. Common flag values:

Value	Meaning
0	No quality issue detected
1	Data value exceeds sigma band

The exact flag schema is defined by NOAA CO-OPS and may vary between products and stations. For critical applications, treat any non-zero flag as a data quality advisory.

---

Quality Assurance Levels

The q field in water level observations indicates the verification status:

Value	Level	Description
"p"	Preliminary	Recent data, not yet reviewed by NOAA quality control
"v"	Verified	Reviewed and approved by NOAA QC processes

Preliminary data is typically available within minutes of observation. Verified data may lag by weeks or months. For real-time operational use, preliminary data is appropriate. For historical analysis, prefer verified data when available.

---

Datum Options

Water level values are relative to a vertical datum — a reference zero point. The datum parameter on tide and water level tools selects which reference is used.

Datum	Full Name	Description
MLLW	Mean Lower Low Water	Default. Average of the lower of the two daily low tides. Standard chart datum for U.S. nautical charts
MSL	Mean Sea Level	Average water level over the 19-year tidal epoch (currently 1983-2001)
NAVD	North American Vertical Datum (1988)	Fixed geodetic reference tied to the North American land survey network. Does not change with sea level
STND	Station Datum	The station’s internal reference zero. Unique to each station
MHW	Mean High Water	Average of all high tide levels
MHHW	Mean Higher High Water	Average of the higher of the two daily high tides
MLW	Mean Low Water	Average of all low tide levels
MTL	Mean Tide Level	Midpoint between MHW and MLW

Choosing a datum

Navigation

Use MLLW (the default). This matches NOAA nautical charts, where charted depths are referenced to MLLW. A prediction of v = "2.5" with datum = "MLLW" means the water is 2.5 feet above the chart datum — directly comparable to charted soundings.

Flood analysis

Use NAVD for comparing water levels to land elevations (flood maps, infrastructure heights). NAVD is a fixed geodetic reference, while tidal datums shift with sea level changes.

Anomaly detection

Use MLLW or STND for consistent station-level comparisons. The water_level_anomaly tool compares observed vs predicted levels using the same datum, so the choice does not affect the deviation calculation.

Cross-station

Use NAVD when comparing water levels between stations. Tidal datums (MLLW, MSL, etc.) are computed independently per station and are not directly comparable across stations. NAVD provides a common reference.

---

Timestamp Conventions

Timestamps follow the pattern YYYY-MM-DD HH:MM and are in local station time by default (lst_ldt — Local Standard Time / Local Daylight Time). The SmartPot tools (tidal_phase, deployment_briefing, catch_tidal_context, water_level_anomaly) request data in GMT for consistent cross-timezone comparison.

When calling tools directly, timestamps in the response match the NOAA API’s time_zone setting:

Tool category	Time zone	Format
Tides, Weather, Planning	lst_ldt (local)	2026-02-22 09:42
SmartPot tools	gmt (UTC)	2026-02-22 14:42

Tip

If you need UTC timestamps from the tides and weather tools, the underlying NOAA API supports a time_zone parameter. The MCP tools currently default to local station time for readability.