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

Three requests, one key. Pick a language once; every example in the docs follows it.

# 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"

# Marine forecast at the same point: waves + wind 16 days, currents + SST ~7-8 (coverage = last valid step per variable)
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: it is billed in credits across the covered locations (see Plans & credits), but counts as one request against the per-minute rate limit. A batch stretches your rate, not your request count. How many batch calls a key may have in flight at once is the plan's In flight allowance (see Plans & credits).

# 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 (vars=, days=/hours=, interval=, 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.

Field slices for map overlays

For a heat-map or animated weather layer, do not sweep a point endpoint cell by cell. Waters and Heavens each have a /field variant that returns a whole raster tile of one variable over a bounding box in a single call: a uniform cols×rows grid (max 512²) at one time step. By default each pixel is IDW-interpolated from the nearest cells (the same spatial interpolation as the point endpoint, with a circular mean for directions and nearest for categorical fields); pass interp=nearest for raw cells to GPU-interpolate yourself. Each pixel is a delivered value, billed at the same per-value rate as a point (a 256×256 slice is ~66 credits) - the win is the single call, not a cheaper unit price, so it replaces tens of thousands of point calls without underpricing them. pack=int16 returns a compact base64 array (scale/offset/nodata). See the Waters and Heavens pages.

# One tile of significant wave height over the Bay of Biscay
curl -H "Authorization: Bearer mk_live_YOUR_KEY" \
  "https://mareelearth.com/v1/waters/field?var=wave_height&bbox=-6,43,-1,47&cols=256&rows=256&pack=int16"

Time window, resolution & fields

You ask for exactly what you want and pay for exactly that. Set the window with days= or hours=, the resolution with interval= (minutes, default hourly), and the fields with vars=. Waters and Heavens return a uniform series at your interval across the window - interpolated from the baked model steps (hourly near-term, coarsening to 3-hourly, 6-hourly and 12-hourly further out), so there are no gaps. Forecast confidence naturally decreases with range; the long-range hours are interpolated for a clean series, not extra model detail. Pass interval=native to skip that and get the raw baked steps at their native cadence. Tides synthesise the exact value at any interval, with no horizon limit.

Plans & credits

Every tier includes every product (Tides, Waters, Heavens - and Lands when it launches) on one key. Usage is billed in credits: a read is one value - one location × one timestep × one field - and credits ≈ (requests × base + reads) / 1000, with every request costing at least 1 credit. So your credits scale with the data you pull: more fields, a longer window or a finer interval cost proportionally more, fewer cost less, and late forecast hours cost less because there is less real data there (billed on native density, not the interpolated count). A full forecast (16 days on Waters, 10 on Heavens) is about 2 credits, a single tide about 1, a 100-location batch about 186. Only answers are billed in full: a request the API rejects (4xx, for example a point with no data) costs 1 credit, and a 5xx on our side costs nothing. A batch call answers 200 with an error per failed point; one in which no point was delivered because of a failure on our side costs nothing either.

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. Every response also carries X-Quota-Used: the credits this calendar month has cost, this call included. X-Quota-Limit accompanies it while your plan has a monthly cap; an account without one has no limit header, and the used header keeps counting.

In flight. The In flight column is how many field calls, and separately how many batch calls, one key may have running at the same time per product (Waters and Heavens count separately, as the rate limit does). A further call answers 429 concurrency_limited with Retry-After: 1. A call counts from the moment it is admitted (after the key, product, rate and quota checks) until its response is returned; closing the connection ends it at once. Field slices additionally run in a bounded pool on each grid worker, separate from the point pool, so a burst of large slices never slows point or batch calls; when a pool is full the call waits up to two seconds for a slot and then answers 503 busy with Retry-After: 2 - on point and batch calls as well as on field calls. Higher allowances are available on request.

Errors

All errors share one envelope:

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

Each product page lists its full catalog, including the codes only field slices use (unknown_var, landmask_unavailable). Retry on 429 and on a 5xx that carries Retry-After. A 4xx is your request, never a stall: it never carries Retry-After and retrying it unchanged cannot succeed. The message names what to fix, e.g. Invalid lon "undefined" (must be a number in -180..180).

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.

API changelog

Every change a client can observe on the keyed /v1 routes, newest first. Additive changes (new fields, new headers) need no client action; anything that alters an existing field, code or price is marked breaking and announced before it ships. Service state and incidents are on the status page.