API Reference

Liveness and configuration readout. Useful for status pages and uptime checks. Also carries the per-source cycle block — the upstream model cycle a downstream consumer keys its own cache on. Public and quota-free: polling it costs no calls.

The cycle block. Each enabled source reports the upstream cycle boundary currently in force, the next boundary, and seconds_to_next, so a consumer can schedule its own refresh instead of guessing. This is public and unauthenticated on purpose: polling it must not cost quota, and it is readable before your first keyed data call.

The block comes from the same function the point routes bucket their caches with, so it can never advertise a cycle the cache did not use. meta.cache_cycle on a point or batched-point response is the per-request equivalent — key your own artifacts on either; they agree.

Marine and weather values at a coordinate, returned as one value per source per timestamp plus a spread/agreement statistic. Sources are never averaged into a single number.

lat required

Latitude in [-90, 90].

lng required

Longitude in [-180, 180].

params

Comma-separated. Defaults to waveHeight,wavePeriod,windSpeed. Unknown ids are rejected with 400, never silently dropped.

hours

Forecast window, 1–240. Default 48.

units

metric (default) or imperial.

Available params: waveHeight, wavePeriod, waveDirection, swellHeight, swellPeriod, swellDirection, windSpeed, windDirection, windGust, airTemperature, waterTemperature, pressure, currentSpeed, currentDirection, visibility, precipitation, cloudCover.

Reading the data: spread.agree counts the sources inside an agreement band of max(param band, 10% of the median). A forecast's newest_valid is in the future by design — use newest_observation for how current the observations are. Read the spread where a spread exists: wind and atmospheric parameters are covered by two sources, so spread.n is 2 and agreement is meaningful. Wave parameters come from a single source (NDBC buoy observations), so spread.n is 1 — there is no consensus to read, and a short ladder delta sits inside one station's coverage rather than across several. Read meta.notices, meta.nearest_station and meta.spread.<param>.n before treating any wave value as more than one instrument's reading.

The same per-source values as /v2/marine/point, resolved for up to 24 coordinates in one call — a batched ladder. Every point shares one params, hours and units. Each point is resolved and reported independently, so one point failing never fails the batch.

points required

Semicolon-separated list of lat,lng pairs — a comma within a point, a semicolon between points. Maximum 24 entries; 25 is rejected with 400.

params

Comma-separated, shared by every point. Same ids, same default and same 400-on-unknown-id rule as /v2/marine/point.

hours

Shared forecast window, 1–240. Default 48.

units

metric (default) or imperial, shared.

Inline failure. A point that cannot be served appears in place in the points array as { request, error, message, failures }, with a per-source failures list, instead of failing the whole call. The HTTP status stays 200 and every other point is still returned. A point that resolves only some sources is a normal result — read meta.sources_ok / meta.sources_failed. Only when every source fails does the point become an inline error.

Each entry is the single-point shape. A successful entry is { request, hours, meta } — exactly what /v2/marine/point returns — so the same parsing code can read either route. A failed entry keeps the same request block and carries error instead of hours.

Which station answered. meta.nearest_station (and meta.stations.ndbc) names the instrument that produced the observation: id, name, distance_km, the params it actually reported, and missing_requested — the requested parameters this source could serve but that instrument does not measure. A non-empty missing_requested means no sensor, not no-data: e.g. a wind-only Gulf buoy asked for waveHeight reports missing_requested: ["waveHeight"] instead of an empty, undiagnosable result. When wave parameters are requested the resolver prefers a station that measures seas over a nearer one that does not, so read distance_km before assuming the closest station answered. Sources with no station concept (the NWS grid) contribute nothing here and leave nearest_station null.

meta.notices — stated limitations. An array of plain-language caveats that apply to this response, so a human or an agent can qualify the data instead of presenting thin coverage as solid. Two are generated today: a parameter that came from only one source (“… came from a single source — there is no cross-source spread to read…”, which is the normal case for wave parameters), and a station-based answer whose station is more than 50 km from the requested point. It is empty when nothing needs qualifying, and it is never used to soften a failure — a failure is an error, not a notice.

Billing. Only points that return fresh data are metered. A fresh point costs 1 call; a cache hit costs 0 and a failed point costs 0. batch.quota_consumed is the authoritative count for the call, and batch.cache reports miss, hit or mixed across the points. A batch of 24 fresh points is 24 calls, not 1. As with /v2/marine/point, key your own artifacts on meta.cache_cycle (see /health) — both come from the same function.

Planned (P1). High/low tide times and heights for a day, relative to MSL, units stated. Documented here so the surface is known; the MCP tide tool reports it as not-yet-available rather than inventing data.

The source catalog: id, dataset, resolution, cadence, area, licence, whether commercial use is permitted, and whether attribution is required. Use this to render correct attribution.

UK Met Office is deliberately excluded: its global wave product is CC-BY-SA (share-alike), which is incompatible with our terms through MVP.

Returns the current disclaimer and attribution strings. If you cache or re-serve our data, fetch these and attach them — they change when the source set changes.

Create an account and send an email verification link. The free tier is gated on a verified address. Request JSON: { "email": "[email protected]", "device_fp": "optional" }.

Note: outbound email delivery is deferred, so verification currently runs on a log transport and the response includes a dev_verify_url. That field disappears once a real mail provider is configured.

Consume a verification token and issue an API key. Tokens are single-use and expire after 24 hours (the optional query parameters token and web are accepted; web=1 renders a short HTML confirmation page instead of JSON).

Quota readout: used, limit, resets_at, plan, plus the definition of what counts as a call.

List your keys, or issue an additional one. A key's secret is returned only at creation.

Quota is per account: additional keys do not add allowance.

Revoke a key. Revocation is immediate and the key stops resolving on the next request.