← All docs

Waters API

The marine water-state forecast: waves (including resolved swell partitions), wind, surface currents, sea-surface temperature and depth for any ocean coordinate, out to 10 days. Served from Mareel's own pre-baked global grid - a region-aware blend of the best open models, finest near the coast (~2-3 km) and coarser offshore, with coastal wave physics (shoaling, refraction, depth-limited breaking) baked in nearshore. Waters is deliberately tide-free: tides are the separate Tides product; combine the two client-side.

Endpoint

GET /v1/waters

The response resolves your coordinate to the nearest grid cell (resolved.nearest_cell_km tells you the snap distance). Points more than 60 km from any ocean cell return 422 no_ocean_cell.

Response

{
  "query":    { "lat": 58.0, "lon": 11.0 },
  "resolved": { "nearest_cell_km": 1.2, "cell": [58.01, 11.02],
                "grid_cycle": "2026-07-12T06:00:00+00:00", "steps": 93 },
  "variables": ["wave_height", "wave_period_peak", "wind_speed", ...],
  "steps": [
    { "time": "2026-07-12T06:00:00+00:00",
      "values": { "wave_height": 1.4, "wave_direction": 245.0, "swell1_height": 1.1,
                  "wind_speed": 12.3, "sst": 16.8, "current_speed": 0.3,
                  "current_hazard": "calm", "depth_m": 42.5, ... } },
    ...
  ],
  "meta": { "model": "pre-baked region-aware grid", "cache": "static-grid",
            "took_ms": 1.8, "disclaimers": ["Not for navigation or safety-of-life decisions; ..."] }
}

A variable a source cannot reach at a given step is null - the series ends honestly where the underlying model runs out rather than padding stale values.

Variables

Where several models cover a point, the finest genuinely-available source wins (e.g. a 2 km regional model beats the global one inside its footprint) - deterministic per cell, no averaging across resolutions.

Field invariants

What a client may rely on, field by field. A 200 body has exactly five keys - query, resolved, variables, steps, meta - passed through verbatim from the grid; errors always use { "error": { "code", "message" } }. Responses that reach the handler (200/400/422 and handler 5xx) carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (the per-key, per-product bucket), as does 429 - the early auth gates (401/402/403) do not - plus X-Quota-Limit and X-Quota-Used when your plan has a quota; bodies over 1 KB are gzipped when you accept it, and keyed 200s carry no cache header. The keyless /v1/demo/waters mirror adds a _proxy_ms diagnostic - the keyed route never does.

The one honest wrinkle in resolved.grid_cycle: when a new bake is published, the serving workers hot-reload staggered (roughly 30 s apart) so the grid never stops serving. During that window two consecutive requests can land on different workers and see the new cycle then the old one - grid_cycle may regress by exactly one cycle for under a minute, then is monotone again. Key your caches by the cycle value, not by "latest ever seen".

How and when the data updates

The grid is re-baked whenever an upstream model publishes a new cycle, at most every ~2-3 hours, and swapped in atomically - you never read a half-written forecast. Read the data's age from resolved.grid_cycle (the forecast base time) and each step's time.

Horizon & time steps: 10 days (240 h) with a tapered axis - hourly to +48 h, 3-hourly to +120 h, 6-hourly to +240 h (~93 steps). Short-range regional detail hands over to the global backbone where a fine model's horizon ends.

Errors & retries

Every error uses the shared envelope from the docs index - { "error": { "code", "message" } }. The full catalog for /v1/waters, with the retry signal where one exists:

The one worth automating: on 503 waters_error, honor Retry-After: 30 and retry once - the serving workers reload staggered, so the retry usually lands on a worker that is serving. Do not retry 422 no_ocean_cell: the answer will not change.

Try it without a key

/v1/demo/waters?lat=..&lon=.. is the keyless showcase window (same grid, CDN-cached, no SLA) - fine for evaluation, not for production. Production traffic belongs on /v1/waters with your key.

Observations

GET /v1/observations

Live in-situ measurements (wave buoys, HF-radar) near a coordinate - the ground truth alongside the forecast. Same Waters entitlement.