← All docs

Heavens API

Global weather for any coordinate on Earth - land, sea, cities, mountains - out to 10 days. Served from Mareel's own pre-baked population-tiered grid: ~2 km cells over cities, ~4 km over towns and coasts, ~11 km everywhere else (10 million cells, no gaps). A region-aware blend of the best open models: convection-permitting regional models (2.2-6.5 km) win where they cover; the ECMWF + GFS global backbone carries the full horizon everywhere. Heavens is the atmosphere; the sea state is the separate Waters product.

Endpoint

GET /v1/heavens

The response resolves your coordinate to the nearest grid cell (resolved.nearest_cell_km tells you the snap distance - inside a city that is typically ~1 km). The grid covers land and sea alike, so virtually every coordinate resolves; a point more than 60 km from any cell returns 422 no_cell.

Response

{
  "query":    { "lat": 59.27, "lon": 15.21 },
  "resolved": { "nearest_cell_km": 0.9, "cell": [59.26, 15.20],
                "grid_cycle": "2026-07-15T00:00:00+00:00", "steps": 93 },
  "variables": ["temperature_2m", "wind_speed", "cloud_total", "precipitation", ...],
  "steps": [
    { "time": "2026-07-15T00:00:00+00:00",
      "values": { "temperature_2m": 13.8, "dewpoint_2m": 11.2, "relative_humidity_2m": 84.0,
                  "wind_speed": 6.1, "wind_gust": 11.0, "wind_direction": 232.0,
                  "cloud_total": 55.0, "precipitation": 0.0, "precip_type": 0,
                  "cape": 120.0, "mslp": 1013.2, "visibility": 24.1, ... } },
    ...
  ],
  "meta": { "model": "pre-baked region-aware grid", "cache": "static-grid",
            "took_ms": 1.6, "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. cloud_ceiling is null under a clear sky (no cloud base to report), and snow variables are null where snow is not modelled (tropical ocean).

Variables

Where several models cover a point, the finest genuinely-available source wins per variable and time step (a 2.2 km convection-permitting model beats the global one inside its footprint) - deterministic per cell, no averaging across resolutions. A handful of variables (cloud_ceiling, precip_type, swe, cin, visibility) are published only by the NOAA models, so they carry GFS/HRRR resolution everywhere.

Field invariants

The envelope is identical to Waters: a 200 body has exactly query, resolved, variables, steps and meta, passed through verbatim from the Heavens grid worker (the same serving code as Waters, a different bake). The full tapered 10-day horizon is always returned - there is no horizon param. Headers are the same everywhere: X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset (per key, per product) on responses that reach the handler and on 429 (the early auth gates 401/402/403 skip it), X-Quota-* when a quota is set, conditional gzip; keyed 200s carry no Cache-Control. Per field, this is what you may rely on:

In short: resolved.grid_cycle, resolved.steps and the time axis are properties of the loaded grid - identical for every point until the next bake swaps in - while nearest_cell_km, cell and the values are properties of your point. Anything not listed here is not part of the contract.

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). The regional models are deliberately short-range: beyond +48 h (Europe) / +18 h (US) every point hands over to the ~27 km global backbone. The grid's fine cells are real regional-model structure inside those footprints; elsewhere they are honest interpolation of the global models - Heavens aims to be the most detailed and most honest open-data forecast, not to invent resolution.

Errors & retries

All errors share the one envelope from the docs index: { "error": { "code": ..., "message": ... } }. The full Heavens catalog, including which responses carry a Retry-After header:

Only 429 rate_limited and 503 heavens_error carry Retry-After, and they are the only two worth retrying blindly. Honor the header: stalls clear in seconds to tens of seconds, and because the serving workers reload staggered during a publish, a 30 s retry lands on a worker that is serving. Everything else is deterministic - fix the request or the account, not the timing.

Try it without a key

/v1/demo/heavens?lat=..&lon=.. is the keyless showcase window (same grid, CDN-cached, no SLA) - fine for evaluation, not for production. Production traffic belongs on /v1/heavens with your key. Sun and moon times shown on the Heavens page are computed client-side (astronomy, not forecast data) and are not API variables.