mcnoaa-tides is a wrapper around NOAA’s public tide and current data. Understanding what that data represents, where it comes from, and what its limitations are will help you interpret results correctly and avoid common pitfalls.
The Center for Operational Oceanographic Products and Services (CO-OPS) is a division of NOAA’s National Ocean Service. It maintains the National Water Level Observation Network (NWLON) — a collection of roughly 301 active coastal tide stations distributed across the United States and its territories.
These stations measure water levels, and many also record meteorological conditions: wind, air temperature, water temperature, barometric pressure, conductivity, visibility, humidity, and salinity. Some stations have been operating continuously for over a century — Seattle’s station (9447130) has records dating to 1899.
CO-OPS provides two things that mcnoaa-tides consumes:
The API is public and requires no authentication.
Every CO-OPS station has a 7-digit numeric identifier. mcnoaa-tides validates this format before making any API request.
| Station ID | Name | State | Notes |
|---|---|---|---|
| 9447130 | Seattle | WA | Operating since 1899 |
| 8454000 | Providence | RI | Narragansett Bay reference station |
| 8723214 | Virginia Key | FL | Biscayne Bay |
| 9414290 | San Francisco | CA | Golden Gate reference station |
Not all stations are tidal. Great Lakes stations measure water levels that fluctuate with wind and barometric pressure rather than gravitational tides. The tidal field in station metadata distinguishes these. The greatlakes field explicitly flags Great Lakes stations.
This is the most important distinction in the dataset.
Predictions
Computed from harmonic analysis of decades of historical water level data. They represent what the tide should be doing based on the gravitational pull of the moon and sun, the shape of the coastline, and the bathymetry of the local basin. Predictions are deterministic — they can be calculated years in advance.
Observations
Actual sensor readings from the station’s instruments, recorded every 6 minutes. They show what the water is actually doing. Observations reflect everything predictions capture plus everything they do not: wind setup, storm surge, barometric pressure effects, river discharge, and seiches.
The gap between predicted and observed water levels is the core of the water_level_anomaly tool. A large positive anomaly (observed well above predicted) can indicate storm surge or sustained onshore wind. A large negative anomaly can indicate offshore wind holding water back. Either way, the deviation from prediction tells you something about non-tidal forces acting on the water.
Under calm conditions with stable barometric pressure, observations and predictions typically agree within a few inches. The divergence grows with:
Water level values are meaningless without a vertical reference. Every water level reading — predicted or observed — is relative to a datum, a fixed reference elevation at the station.
| Datum | Full Name | Description |
|---|---|---|
| MLLW | Mean Lower Low Water | Average of the lower of the two daily low tides over a 19-year epoch. The default datum for navigation charts and mcnoaa-tides. |
| MSL | Mean Sea Level | Average water level over a 19-year epoch. |
| NAVD | North American Vertical Datum (1988) | A geodetic datum tied to the continental land survey network. Used for surveying and flood maps. |
| STND | Station Datum | An arbitrary local reference unique to each station. The most stable reference but not comparable between stations. |
mcnoaa-tides defaults to MLLW because it is the standard for U.S. nautical charts and the most intuitive for marine use: a value of 0.0 ft MLLW means the water is at the average low-tide mark, and negative values mean the water is below average low tide.
NOAA returns timestamps in the time zone you request. mcnoaa-tides defaults vary by context:
| Context | Default | Reason |
|---|---|---|
| User-facing tools (tides, meteorological, conditions) | lst_ldt (local standard/daylight time at the station) | Most intuitive for users planning activities at the station’s location |
| SmartPot tools (tidal_phase, deployment_briefing, etc.) | gmt (UTC) | GPS coordinates and deployment systems work in UTC |
The timestamp appears in the "t" field of each data record, formatted as "YYYY-MM-DD HH:MM". There is no timezone indicator in the timestamp string itself — you need to know which time zone you requested to interpret it correctly.
Observations include quality metadata in two fields:
q field — QA level:
p = preliminary — real-time data that has not been reviewed. This is what you get for recent observations (last few days to weeks). It may be revised later.v = verified — post-processed data that has been reviewed for quality. Typically available weeks to months after collection.f field — quality flags:
A comma-separated string of flag codes. 0 means no quality issues detected. Other values indicate specific conditions:
For real-time marine planning, preliminary data is perfectly usable — the revisions during QA are typically small corrections. The flags are more relevant: if you see non-zero flags, the reading may be unreliable.
Not every station has every sensor. A station might have a tide gauge but no wind anemometer, or measure water temperature but not air pressure. The get_station_info tool returns the full list of available sensors and products for any station.
The parallel-fetch tools (marine_conditions_snapshot, visualize_conditions) handle missing sensors gracefully — they report unavailable products in the response rather than failing the entire request.
The NOAA CO-OPS API is public and does not require authentication, but it does have practical constraints:
| Constraint | Value |
|---|---|
| Maximum date range per request | 720 hours (30 days) |
| Authentication | None required |
| Application identifier | mcnoaa-tides-mcp (sent with every request) |
| Rate limiting | Not formally documented; mcnoaa-tides uses a single httpx.AsyncClient with connection pooling to avoid hammering the API |
| Response format | JSON (mcnoaa-tides always requests format=json) |
The 720-hour (30-day) limit is enforced by the API. Requesting a longer range returns an error. For longer time series, you would need to make multiple requests with consecutive date ranges — mcnoaa-tides does not do this automatically.