API documentation

One API, four products. Every endpoint lives under https://mareelearth.com/v1 and is served from Mareel's own pre-computed data: tides are synthesized on demand from harmonic constants; the marine forecast and the global weather are read from pre-baked global grids. Responses are JSON.

Products

Coming-soon products return 503 coming_soon on their keyed endpoints until launch.

Authentication

Create an API key from your dashboard (sign in → API keys → Create key). Keys look like mk_live_… and are shown once at creation. Pass the key on every request, preferably as a Bearer token:

curl -H "Authorization: Bearer mk_live_YOUR_KEY" \
  "https://mareelearth.com/v1/tides/current?lat=58.0&lon=11.0"

Also accepted: an X-Api-Key header, or ?key= as a query parameter (avoid in logs). All endpoints are GET and CORS-open, so browser use works - but treat keys as secrets and prefer calling from your server.

Quickstart

# Current tide at a Swedish west-coast point
curl -H "Authorization: Bearer mk_live_YOUR_KEY" \
  "https://mareelearth.com/v1/tides/current?lat=58.0&lon=11.0"

# 10-day marine forecast (waves, wind, currents, SST) at the same point
curl -H "Authorization: Bearer mk_live_YOUR_KEY" \
  "https://mareelearth.com/v1/waters?lat=58.0&lon=11.0"

# 10-day weather (temperature, wind, clouds, precipitation) for a city
curl -H "Authorization: Bearer mk_live_YOUR_KEY" \
  "https://mareelearth.com/v1/heavens?lat=59.27&lon=15.21"

Batch requests

Every point product has a /batch variant that takes up to 100 coordinates in one call as equal-length comma lists, and returns a per-point results array in input order. A point with no data carries a per-point error and never fails the whole call. One 100-point sweep replaces 100 single calls: the monthly quota is metered in points (only points that return data are billed), while the per-minute rate limit counts the whole batch as one request.

# Marine forecast at three points in one call
curl -H "Authorization: Bearer mk_live_YOUR_KEY" \
  "https://mareelearth.com/v1/waters/batch?lat=59.3,58.9,57.7&lon=18.1,17.6,11.9"

# -> { "count": 3, "covered": 3, "results": [ {…}, {…}, {…} ] }

The same query params as the single-point routes (e.g. vars=, or the tide window + datum) apply to every point. Max 100 points per call; a transient point failure is retryable and sets a top-level Retry-After.

Plans & limits

Every tier includes every product (Tides, Waters, Heavens - and Lands when it launches) on one key. Tiers differ only by monthly quota (metered in points - one single-point call = 1 point, an N-point batch = N) and the per-minute rate limit.

The rate limit is per key, per product - a burst on one product never eats another's budget. Every response that reaches the handler (and every 429) carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds to a full bucket) so you can pace yourself before hitting a 429; a 429 also includes Retry-After. Metered plans additionally get X-Quota-Limit / X-Quota-Used.

Errors

All errors share one envelope:

{ "error": { "code": "unauthorized", "message": "Missing or invalid API key. ..." } }

Attribution & use

Tide data is derived from the FES2022 model (CNES/LEGOS/NOVELTIS/CLS, via AVISO); forecast data blends open model output from NOAA, ECMWF, DWD, ECCC and Copernicus. Keep the meta.attribution notices visible where you display the data - details on the attribution page. All values are modelled estimates provided as-is: not for navigation or safety-of-life decisions.