The licensed API
GlobeWarn has two APIs, and the difference is a promise, not a
paywall. The open one at /api/alerts answers everyone,
with no key and no limit; the page itself uses it, and it stays open.
What a licence buys is the stable one at
/v1: versioned paths that will not change shape, filters
worth building a system on, the record, each source's raw answer, and
an allowance that matches the licence. Anything that would change
/v1 becomes /v2, and both run.
The key
Every /v1 path except nothing at all — the whole
surface is keyed. Send the key either way:
Authorization: Bearer <your key>
…or, where a header is awkward:
https://globewarn.com/v1/alerts?key=<your key>
Three outcomes, not two. A valid key is answered. A key billing
refuses is refused, with billing's reason. And when our own billing
service does not answer at all, that is not a no: a key seen
in the last hour keeps working, and a key never seen gets
503, which says plainly the fault is ours. An API that
fails closed on its paying customers when its own machinery hiccups
would be worse than no API.
The paths
| Path | What it answers |
|---|---|
/v1/me |
Your licence, spelled out: tier, seats, watch areas, days of
record, calls allowed and used, and where this page lives.
/v1 alone answers the same. |
/v1/alerts |
Every current warning, filtered by the query below. The picture refreshes every 15 minutes. |
/v1/alerts/<id> |
One event, whole. |
/v1/history |
The record: what was known, and when. Takes
since, until, id and
limit (up to 5000, default 1000). |
/v1/index |
The Impact Index, stated: the bands, the exposure points, the agreement points, and the two rules — it never sits below the highest band an agency gave, and an event no agency graded carries no Index. |
/v1/health |
Which of the sources are fresh, right now. |
/v1/sources |
The same answer under the name most clients guess first. |
/v1/raw/<source> |
One source's own answer, untouched, as it arrived. Full-access licences only. |
Filtering /v1/alerts
Each filter answers a question a desk actually asks. They combine.
| Parameter | Narrows to |
|---|---|
country=chile |
Warnings naming that country or place. |
kind=flood |
One kind of disaster — matched against each warning's own labels. |
source=GDACS |
One agency's warnings, exactly. |
from=severe |
At or above an Impact Index band:
moderate (15), serious (40),
severe (70), extreme (90). |
since=2026-08-30T00:00:00Z |
Warnings that began after that moment. A warning with no stated onset is kept, never silently dropped. |
limit=50 |
At most that many, after the other filters. |
The allowance
Every answer carries it in headers —
X-RateLimit-Used and X-RateLimit-Window
— so a client never has to guess where it stands. Licences with
an unlimited allowance simply never hit one.
When something is wrong
Errors arrive as JSON with two fields: error, which says
what happened, and what_to_do, which says whose move it
is. A 502 means our data service did not answer —
that is ours, retry shortly. A 404 under /v1
lists every path that exists.
Keys come with a licence — the tiers are on the front page. Anything unclear here is a fault in this page: tell us and we will fix the page, not the explanation.