# `noaa_marine__noaa_marine_get_water_level`

**Get Water Level**

Observed water level, real-time or historical, for a CO-OPS water-level station, paired with tide predictions for the same period so the residual (observed − predicted) shows storm surge when positive and anomalous drawdown when negative. The interval selects the cadence: 6min (default) is the full curve, hourly and high_low cover months to a year of the same series at far fewer rows, and daily_mean serves Great Lakes stations only. Each interval carries its own CO-OPS range ceiling — 31 days for 6min, 365 for hourly and high_low, 3655 for daily_mean — rejected locally before the call, and only 6min and hourly report a residual. Observations and predictions are fetched independently, so when the prediction series is empty, predictions_status says whether CO-OPS has none for this station and range or the prediction fetch failed — the observed series returns either way, and residual_summary is present only when both series are and the cadence supports the join. A sensor outage leaves slots with no reading; those slots are dropped and counted in gaps_dropped, so the observed series is continuous across the range only when that count is absent. A range whose rows fit the response budget is returned whole; a longer one returns the leading rows, with rows_matched, rows_returned, and next_offset reporting how much matched and which offset reaches the rest. Use noaa_marine_find_stations first to resolve a station name or location to a valid station ID.

- Server: [NOAA Tides & Currents](https://gateway.mcpharbor.dev/docs/servers/noaa_marine) (`dev.mcpharbor.gateway/noaa_marine`)
- Price per call: $0.0001 (100 micro-USD); only tools/call is charged
- Endpoint: `https://gateway.mcpharbor.dev/mcp` or `https://gateway.mcpharbor.dev/mcp/noaa_marine`
- Upstream tool: exposed by the provider; called through this gateway as `noaa_marine__noaa_marine_get_water_level`
- Provider terms: <https://tidesandcurrents.noaa.gov/disclaimers.html> (verified 2026-09-19)
- Upstream API documentation: <https://api.tidesandcurrents.noaa.gov/api/prod/>
- Rate limit: 300 requests per minute
- Attribution required: NOS requests attribution whenever its material is reproduced and re-disseminated; content must not be modified and presented as official government material; predictions are forecast guidance, not for navigation reliance. The optional 'application' parameter should identify the gateway.

## Parameters

- `begin_date` (string, required): Start date in YYYYMMDD format, e.g. "20240601".
- `datum` (string, optional): Datum the observed heights are referenced to. MLLW (default) is the US nautical chart datum, and MHHW (mean higher high water) is the flooding reference; MHW, MTL, MSL, and MLW are the other tidal ... One of: `MLLW`, `MHHW`, `MHW`, `MTL`, `MSL`, `MLW`, `NAVD`, `STND`, `IGLD`, `LWD`, `CRD`, `LWI`, `HWI`. Default: `MLLW`.
- `end_date` (string, required): End date in YYYYMMDD format (inclusive), e.g. "20240601".
- `interval` (string, optional): Observed cadence. 6min (default) is the full curve, 31 days per request, the only one carrying a quality flag. hourly is hourly heights, 365 days per request, and reports a residual against the hou... One of: `6min`, `hourly`, `high_low`, `daily_mean`. Default: `6min`.
- `limit` (integer, optional): Maximum observation rows to return on this page, for a caller that wants fewer than the response budget allows. Omit for the largest page that fits; a value larger than the budget allows does not w...
- `offset` (integer, optional): Row offset into the matched observation series, for reading a range whose rows do not fit one response. 0 (default) starts at the first row; pass the next_offset from a previous call to continue. A... Default: `0`.
- `station_id` (string, required): CO-OPS water-level station ID (numeric, e.g. "9447130" for Seattle). Obtain from noaa_marine_find_stations with types=\["water_level"\].
- `time_zone` (string, optional): Time zone for returned timestamps. lst_ldt = local standard/daylight time (default); gmt = UTC; lst = local standard time year-round. Overridden to lst on interval="daily_mean", which CO-OPS serves... One of: `lst_ldt`, `gmt`, `lst`. Default: `lst_ldt`.
- `units` (string, optional): Unit system: english = feet; metric = meters. One of: `english`, `metric`. Default: `english`.

## Example call

Request headers and body:

```http
POST /mcp HTTP/1.1
Host: gateway.mcpharbor.dev
Authorization: Bearer <your gateway API key>
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: noaa_marine__noaa_marine_get_water_level
```

```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/clientCapabilities": {},
      "io.modelcontextprotocol/clientInfo": {
        "name": "example-agent",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/protocolVersion": "2026-07-28"
    },
    "arguments": {
      "begin_date": "example",
      "end_date": "example",
      "station_id": "example"
    },
    "name": "noaa_marine__noaa_marine_get_water_level"
  }
}
```

A successful response:

```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "_meta": {
      "dev.mcpharbor.gateway/call": {
        "chargedMicroUsd": 100,
        "id": "<the id of this charge>"
      }
    },
    "content": [
      {
        "text": "<whatever the upstream tool returned>",
        "type": "text"
      }
    ],
    "resultType": "complete"
  }
}
```

This call costs $0.0001 (100 micro-USD). Reading this page and listing the tool cost nothing.
The `dev.mcpharbor.gateway/call` record in the result is the receipt for that charge. Each
POST is metered separately, so sending the same call again buys another one: see
[agent.txt](https://gateway.mcpharbor.dev/agent.txt), section 7, before retrying.

## Attribution

This provider requires the attribution below wherever you use results from its tools.
Reproduce it verbatim:

> NOS requests attribution whenever its material is reproduced and re-disseminated; content must not be modified and presented as official government material; predictions are forecast guidance, not ...

## Tool definition

Exactly as `tools/list` returns it (free):

```json
{
  "_meta": {
    "dev.mcpharbor.gateway/pricing": {
      "currency": "USD",
      "pricePerCallMicroUsd": 100
    }
  },
  "annotations": {
    "idempotentHint": true,
    "openWorldHint": true,
    "readOnlyHint": true
  },
  "description": "Observed water level, real-time or historical, for a CO-OPS water-level station, paired with tide predictions for the same period so the residual (observed − predicted) shows storm surge when positive and anomalous drawdown when negative. The interval selects the cadence: 6min (default) is the full curve, hourly and high_low cover months to a year of the same series at far fewer rows, and daily_mean serves Great Lakes stations only. Each interval carries its own CO-OPS range ceiling — 31 days for 6min, 365 for hourly and high_low, 3655 for daily_mean — rejected locally before the call, and only 6min and hourly report a residual. Observations and predictions are fetched independently, so when the prediction series is empty, predictions_status says whether CO-OPS has none for this station and range or the prediction fetch failed — the observed series returns either way, and residual_summary is present only when both series are and the cadence supports the join. A sensor outage leaves slots with no reading; those slots are dropped and counted in gaps_dropped, so the observed series is continuous across the range only when that count is absent. A range whose rows fit the response budget is returned whole; a longer one returns the leading rows, with rows_matched, rows_returned, and next_offset reporting how much matched and which offset reaches the rest. Use noaa_marine_find_stations first to resolve a station name or location to a valid station ID.",
  "inputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "begin_date": {
        "description": "Start date in YYYYMMDD format, e.g. \"20240601\".",
        "pattern": "^\\d{8}$",
        "type": "string"
      },
      "datum": {
        "default": "MLLW",
        "description": "Datum the observed heights are referenced to. MLLW (default) is the US nautical chart datum, and MHHW (mean higher high water) is the flooding reference; MHW, MTL, MSL, and MLW are the other tidal planes. NAVD is NAVD88 and reads only where the station has an NAVD88 tie. STND is the station's own datum and is the plane that works where no tidal datum exists. IGLD and LWD apply at Great Lakes stations only, CRD at Columbia River stations only, and LWI and HWI are lunitidal intervals rather than heights. A datum this station does not carry comes back as datum_unavailable naming the ones it does.",
        "enum": [
          "MLLW",
          "MHHW",
          "MHW",
          "MTL",
          "MSL",
          "MLW",
          "NAVD",
          "STND",
          "IGLD",
          "LWD",
          "CRD",
          "LWI",
          "HWI"
        ],
        "type": "string"
      },
      "end_date": {
        "description": "End date in YYYYMMDD format (inclusive), e.g. \"20240601\".",
        "pattern": "^\\d{8}$",
        "type": "string"
      },
      "interval": {
        "default": "6min",
        "description": "Observed cadence. 6min (default) is the full curve, 31 days per request, the only one carrying a quality flag. hourly is hourly heights, 365 days per request, and reports a residual against the hourly prediction series. high_low is the observed high and low waters with their H/HH/L/LL classification, 365 days per request, and reports no residual because observed extremes do not fall on predicted extreme times. daily_mean is the daily mean water level, 3655 days per request, published at Great Lakes stations only and with no paired prediction series; a coastal station comes back as great_lakes_only.",
        "enum": [
          "6min",
          "hourly",
          "high_low",
          "daily_mean"
        ],
        "type": "string"
      },
      "limit": {
        "description": "Maximum observation rows to return on this page, for a caller that wants fewer than the response budget allows. Omit for the largest page that fits; a value larger than the budget allows does not widen the page.",
        "maximum": 9007199254740991,
        "minimum": 1,
        "type": "integer"
      },
      "offset": {
        "default": 0,
        "description": "Row offset into the matched observation series, for reading a range whose rows do not fit one response. 0 (default) starts at the first row; pass the next_offset from a previous call to continue. An offset past the last row returns an empty page rather than an error.",
        "maximum": 9007199254740991,
        "minimum": 0,
        "type": "integer"
      },
      "station_id": {
        "description": "CO-OPS water-level station ID (numeric, e.g. \"9447130\" for Seattle). Obtain from noaa_marine_find_stations with types=[\"water_level\"].",
        "pattern": "^[A-Za-z0-9_-]{1,20}$",
        "type": "string"
      },
      "time_zone": {
        "default": "lst_ldt",
        "description": "Time zone for returned timestamps. lst_ldt = local standard/daylight time (default); gmt = UTC; lst = local standard time year-round. Overridden to lst on interval=\"daily_mean\", which CO-OPS serves in local standard time only and otherwise stamps every row a day off.",
        "enum": [
          "lst_ldt",
          "gmt",
          "lst"
        ],
        "type": "string"
      },
      "units": {
        "default": "english",
        "description": "Unit system: english = feet; metric = meters.",
        "enum": [
          "english",
          "metric"
        ],
        "type": "string"
      }
    },
    "required": [
      "station_id",
      "begin_date",
      "end_date"
    ],
    "type": "object"
  },
  "name": "noaa_marine__noaa_marine_get_water_level",
  "outputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "anyOf": [
      {
        "not": {
          "required": [
            "error"
          ]
        },
        "required": [
          "station_id",
          "station_name",
          "datum",
          "units",
          "interval",
          "observations",
          "predictions"
        ]
      },
      {
        "required": [
          "error"
        ]
      }
    ],
    "properties": {
      "datum": {
        "description": "Tidal datum used — echoed for correct interpretation of water heights.",
        "type": "string"
      },
      "error": {
        "additionalProperties": {},
        "description": "Present when the call failed. Absent on success.",
        "properties": {
          "code": {
            "description": "JSON-RPC error code for this failure.",
            "maximum": 9007199254740991,
            "minimum": -9007199254740991,
            "type": "integer"
          },
          "data": {
            "additionalProperties": {},
            "properties": {
              "reason": {
                "description": "Machine-readable failure mode. Declared by this tool: `station_not_found`: CO-OPS returned an error for the station ID. `invalid_date_range`: begin_date/end_date is not a real calendar date or begin_date is after end_date. `date_range_exceeded`: Requested date range exceeds the selected interval's CO-OPS limit — 31 days for 6min, 365 for hourly and high_low, 3655 for daily_mean. `no_data`: Station exists but no observed water-level data for the date range. `great_lakes_only`: interval=\"daily_mean\" was requested for a coastal station — CO-OPS publishes water-level daily means at Great Lakes stations only. `verified_data_lag`: The hourly, high_low, or daily_mean product returned no rows for the window, which CO-OPS has not published yet. `datum_unavailable`: The station does not carry the requested datum — a Great Lakes station has no tidal datum, and NAVD reads only where the station has an NAVD88 tie. Other values are possible when a failure originates below the handler.",
                "examples": [
                  "station_not_found",
                  "invalid_date_range",
                  "date_range_exceeded",
                  "no_data",
                  "great_lakes_only",
                  "verified_data_lag",
                  "datum_unavailable"
                ],
                "type": "string"
              },
              "recovery": {
                "additionalProperties": {},
                "description": "Actionable next step for the caller.",
                "properties": {
                  "hint": {
                    "type": "string"
                  }
                },
                "required": [
                  "hint"
                ],
                "type": "object"
              },
              "retryable": {
                "description": "Whether retrying may succeed.",
                "type": "boolean"
              }
            },
            "type": "object"
          },
          "message": {
            "description": "Human-readable description of what went wrong.",
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "type": "object"
      },
      "gaps_dropped": {
        "description": "Number of sample slots CO-OPS sent with no reading, dropped from observations. Present only when there was at least one. The observed series is therefore not continuous across the requested range: it has this many missing slots, and rows_matched counts only the slots that carry a value.",
        "maximum": 9007199254740991,
        "minimum": -9007199254740991,
        "type": "integer"
      },
      "interval": {
        "description": "Observed cadence echoed from the request — the CO-OPS product these rows came from, and what decides whether quality, type, and residual_summary are populated.",
        "enum": [
          "6min",
          "hourly",
          "high_low",
          "daily_mean"
        ],
        "type": "string"
      },
      "next_offset": {
        "anyOf": [
          {
            "maximum": 9007199254740991,
            "minimum": -9007199254740991,
            "type": "integer"
          },
          {
            "type": "null"
          }
        ],
        "description": "Offset to pass as offset on the next call, or null when this page reaches the last matched observation. Absent when the whole matched series was returned."
      },
      "notice": {
        "description": "Why the paired prediction series is missing or carries no residual, how many sample slots were dropped, and what this page of the observed series covers — whichever of those apply, composed into one string.",
        "type": "string"
      },
      "observations": {
        "description": "Observed water level readings at the requested cadence — the whole matched series when it fits one response, otherwise the leading page starting at offset. rows_matched and next_offset report what a page left behind.",
        "items": {
          "additionalProperties": false,
          "description": "A single observed water level reading at the requested cadence.",
          "properties": {
            "quality": {
              "description": "Quality flag: p = preliminary, v = verified. Present on the 6min interval only — CO-OPS sends no flag with the hourly, high_low, or daily_mean products, which are verified data, so the field is absent rather than defaulted to preliminary.",
              "type": "string"
            },
            "sigma": {
              "description": "Standard deviation of the water level sensor reading. Present on the 6min and hourly intervals; CO-OPS sends none for high_low or daily_mean.",
              "type": "number"
            },
            "time": {
              "description": "Observation datetime in the requested time zone.",
              "type": "string"
            },
            "type": {
              "description": "Observed extreme classification on the high_low interval: H = high water, HH = higher high water, L = low water, LL = lower low water. Absent on every other interval.",
              "enum": [
                "H",
                "HH",
                "L",
                "LL"
              ],
              "type": "string"
            },
            "value": {
              "description": "Observed water height in the requested units relative to the datum.",
              "type": "number"
            }
          },
          "required": [
            "time",
            "value"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "page_offset": {
        "description": "Observation row offset this page starts at, echoed from the request. Absent when the whole matched series was returned.",
        "maximum": 9007199254740991,
        "minimum": -9007199254740991,
        "type": "integer"
      },
      "predictions": {
        "description": "Paired tide predictions covering the same period as the returned observations, at the interval matching the observed cadence. Always empty on the daily_mean interval, which has no paired series. Otherwise empty when CO-OPS returned no predictions for this station and range, or when the prediction fetch failed — predictions_status says which.",
        "items": {
          "additionalProperties": false,
          "description": "A single tide prediction.",
          "properties": {
            "time": {
              "description": "Prediction datetime in the requested time zone.",
              "type": "string"
            },
            "value": {
              "description": "Predicted water height in the requested units relative to the datum.",
              "type": "number"
            }
          },
          "required": [
            "time",
            "value"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "predictions_status": {
        "description": "Present only when predictions is empty on an interval that has a paired series. \"empty\" means CO-OPS returned no prediction rows for this station and date range; \"unavailable\" means the prediction fetch failed, so no comparison series could be retrieved and the absence says nothing about the station. Absent when predictions were returned, and on the daily_mean interval, which has no paired series to report on.",
        "enum": [
          "empty",
          "unavailable"
        ],
        "type": "string"
      },
      "residual_summary": {
        "additionalProperties": false,
        "description": "Summary of observed-minus-predicted residuals in the requested units, computed across the whole matched series rather than the returned page — so a paged response still reports the largest surge in the range. Present only on the 6min and hourly intervals, and only when both series are available; the notice says why it is absent on high_low and daily_mean.",
        "properties": {
          "max_drawdown": {
            "description": "Maximum negative residual magnitude in the requested units (feet for english, meters for metric) — anomalous drawdown indicator.",
            "type": "number"
          },
          "max_surge": {
            "description": "Maximum positive residual (observed − predicted) in the requested units (feet for english, meters for metric) — storm surge indicator.",
            "type": "number"
          }
        },
        "required": [
          "max_surge",
          "max_drawdown"
        ],
        "type": "object"
      },
      "rows_matched": {
        "description": "Observation rows the requested date range matched, before the page was cut. Absent when the whole matched series was returned.",
        "maximum": 9007199254740991,
        "minimum": -9007199254740991,
        "type": "integer"
      },
      "rows_returned": {
        "description": "Observation rows this page carries — the length of observations. Absent when the whole matched series was returned.",
        "maximum": 9007199254740991,
        "minimum": -9007199254740991,
        "type": "integer"
      },
      "station_id": {
        "description": "Station ID echoed from the request — for chaining.",
        "type": "string"
      },
      "station_name": {
        "description": "Station name as returned by CO-OPS.",
        "type": "string"
      },
      "truncated": {
        "description": "True when this page stops short of the last matched observation, so further rows remain at next_offset. False on the final page and on a page past the end. Absent when the whole matched series was returned.",
        "type": "boolean"
      },
      "units": {
        "description": "Height units: \"english\" (feet) or \"metric\" (meters).",
        "type": "string"
      }
    },
    "type": "object"
  },
  "title": "Get Water Level"
}
```