API

Read the data without a key

Live disaster data from 80 scientific monitoring sources, over REST. Reading needs no key and no registration.

Access

Every endpoint on this page answers without an Authorization header. Paste a request into a terminal and it answers:

Terminal

$ curl "https://calamity.live/api/v1/events?limit=1"

Base URL https://calamity.live/api/v1 (and /api/v2 for forecast, rating, bulk export and CAP). Keys prefixed cal_ exist only for deliveries agreed in writing (talk to us), and are never required to read.

Rate limits

Rate limits
Scope	Limit
Every endpoint, by default	60 requests a minute per IP and endpoint family (every /api/v1/archive/<id> is one family)
/api/all-events (the map payload)	15 a minute
/api/export	10 a minute
Headers on every answer	X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset; a 429 carries Retry-After

Live events (v1)

The events the collector currently holds, the same set the map draws. Rebuilt at most every two minutes.

GET/api/v1/events

List live events with filters

Parameters type, severity (critical|high|medium|low), bbox (minLat,minLon,maxLat,maxLon), minScore (0-100), limit (max 500), offset

Example

$ curl "https://calamity.live/api/v1/events?type=earthquake&limit=2"

Response shape

{
  "events": [{ "id": "us7000…", "type": "earthquake", "title": "M 5.8 Earthquake, …", "severity": "medium",
               "severityValue": 5.8, "latitude": 38.2, "longitude": 142.1, "timestamp": 1756800000000,
               "source": "usgs", "calamityScore": { "raw": 28, "confidence": 0.7 }, … }],
  "meta": { "total": 49, "limit": 2, "offset": 0, "lastUpdated": "2026-09-02T07:10:00.000Z", "version": "v1" }
}

GET/api/v1/events/:id

One live event by id

Parameters id (path)

Example

$ curl "https://calamity.live/api/v1/events/us7000abcd"

Response shape

{ "event": { "id": "us7000abcd", "type": "earthquake", … }, "meta": { "lastUpdated": "…", "version": "v1" } }
404 when the id is not in the live set, try /api/v1/archive/:id for older rows

Cascades (v1)

Hazard chains the engine flags for live events, grouped by trigger. No probability is published (D-23): the band is a ranking, not a frequency.

GET/api/v1/cascades

Active cascade chains

Parameters none

Example

$ curl "https://calamity.live/api/v1/cascades"

Response shape

{
  "ok": true,
  "data": [{ "triggerEventId": "us7000…", "triggerType": "earthquake",
             "chains": [{ "rule": "H1", "targetType": "tsunami", "band": "high", "depth": 1 }] }],
  "meta": { "total": 5, "totalChains": 12, "lastUpdated": "…", "version": "v1" }
}

Statistics (v1)

Aggregates over the live set and over the archive.

GET/api/v1/stats

Counts by type and severity, live set

Parameters none

Example

$ curl "https://calamity.live/api/v1/stats"

Response shape

{ "stats": { "totalEvents": 3594, "byType": { "fire": 2528, "earthquake": 49, … }, "bySeverity": { "critical": …, … },
             "cascadeAlertsActive": 200, "sources": 80 }, "lastUpdated": "…" }

GET/api/v1/stats/types

Public archive records per type, last 7 and 30 days by event time

Parameters none

Example

$ curl "https://calamity.live/api/v1/stats/types"

Response shape

{ "ok": true, "data": { "earthquake": { "7d": 342, "30d": 1580 }, "fire": { "7d": …, "30d": … } }, "meta": { "lastUpdated": "…", "window": { … }, "definition": "…" } }

GET/api/v1/stats/region/:code

One country (ISO 3166-1 alpha-2): archive records, last 7 and 30 days

Parameters code (path)

Example

$ curl "https://calamity.live/api/v1/stats/region/IT"

Response shape

{ "ok": true, "data": { "region": "IT", "events7d": 12, "events30d": 48, "topType": "earthquake", "avgCalamityScore": 23.4 } }

GET/api/v1/archive/stats

Archive totals over the last N UTC days, with the live-map snapshot of each day beside them (meta.definitions)

Parameters days (default 30)

Example

$ curl "https://calamity.live/api/v1/archive/stats?days=7"

Response shape

{ "stats": { "days": 7, "totalEvents": …, "totalCascades": null, "avgCalamityScore": …, "maxCalamityScore": …, "byType": { … }, "bySeverity": { … } } }

Archive (v1)

Every row the collector has kept since 8 March 2026, paginated. For bulk work use /api/v2/bulk-export (10,000 rows a call).

GET/api/v1/archive

Archived events, paginated

Parameters type, severity, countryCode, from, to, minScore, sort (newest or score); limit (max 500) and offset, or page and perPage. Every filter applies to the whole archive and meta.total counts the whole filtered set; source, bbox and q are refused with a 400

Example

$ curl "https://calamity.live/api/v1/archive?type=earthquake&limit=20"

Response shape

{ "events": [ … ], "meta": { "total": 10519, "limit": 20, "offset": 0, "queryTimeMs": 41, "version": "v1" } }

GET/api/v1/archive/:id

One archived row

Parameters id (path)

Example

$ curl "https://calamity.live/api/v1/archive/us7000abcd"

Response shape

{ "event": { "id": "us7000abcd", "type": "earthquake", "title": "…", "score_version": 4, … }, "meta": { … } }

Health (v1)

The collector and the source census, three definitions, each named next to its number.

GET/api/v1/health

Health and census

Parameters none

Example

$ curl "https://calamity.live/api/v1/health"

Response shape

{ "status": "operational",
  "sources": { "registered": 233, "enabled": 80, "fetchedToday": …, "archived24h": …, "definitions": { … } },
  "archive": { "since": "2026-03-08T18:25:04.006+00:00", "rows": … },
  "collector": { "reachable": true, "snapshotAgeMs": …, "cycle": { … } }, "timestamp": "…" }

Forecast and rating (v2)

The 7-day risk index and the A–E country rating, as the /forecast and /rating pages show them.

GET/api/v2/forecast

All forecast scores

Parameters type (optional hazard filter)

Example

$ curl "https://calamity.live/api/v2/forecast?type=earthquake"

Response shape

{ "scores": [{ "country_code": "JP", "hazard_type": "earthquake", "score": 67, "level": "elevated", … }], "updatedAt": … }

GET/api/v2/forecast/:countryCode

One country

Parameters countryCode (path)

Example

$ curl "https://calamity.live/api/v2/forecast/JP"

Response shape

[{ "country_code": "JP", "hazard_type": "earthquake", "score": 67, "level": "elevated", … }, …]

GET/api/v2/rating

All country ratings

Parameters none

Example

$ curl "https://calamity.live/api/v2/rating"

Response shape

{ "ratings": [{ "country_code": "JP", "grade": "C", "status": "yellow", … }], "updatedAt": … }

GET/api/v2/rating/:countryCode

One country with its delta history

Parameters countryCode (path)

Example

$ curl "https://calamity.live/api/v2/rating/US"

Response shape

{ "rating": { "country_code": "US", "grade": "B", … }, "deltas": [{ "from_rating": "A", "to_rating": "B", … }], "updatedAt": … }

Bulk and feeds (v2)

The open endpoints that were always open.

GET/api/v2/bulk-export

The archive in bulk, CC BY 4.0

Parameters format (json|csv|geojson), type, severity, from, to (ISO dates), min_score, verification_level, min_source_count, country, lat + lng + radius_km, exclude_withdrawn, include_cascades, include_historical (GLIDE fields; none recorded yet, so null), limit (default 500, max 10,000), offset; the next page is in the Link header. To download the whole archive use cursor=start and follow the Link header: it walks the rows in the order they were first written, up to a horizon fixed on the first page, so every row arrives once while the archive keeps being written (offset pages can repeat or miss rows). With cursor only type and exclude_withdrawn apply

Example

$ curl "https://calamity.live/api/v2/bulk-export?format=csv&limit=10000&cursor=start"

Response shape

CSV rows; for json { "metadata": { … }, "events": [ … ] }; for geojson a FeatureCollection

GET/api/v2/cap

The live feed as CAP 1.2 XML

Parameters min_score, type, hours

Example

$ curl "https://calamity.live/api/v2/cap?min_score=60&hours=24"

Response shape

<alert xmlns="urn:oasis:names:tc:emergency:cap:1.2"> … </alert>

GET/api/v2/risk-score

Risk score for a point

Parameters lat, lng (both required), radius (km, default 50; radius_km is read the same); a request without coordinates answers 400

Example

$ curl "https://calamity.live/api/v2/risk-score?lat=40.85&lng=14.27"

Response shape

{ "location": { "lat": 40.85, "lng": 14.27, "radius_km": 50 }, "risk_score": …, "risk_level": "…", "breakdown": { … }, "data_quality": { … } }

Error codes

Error codes
Status	Meaning	Description
400	Bad Request	Invalid parameters (type, severity, bbox, missing coordinates…)
403	Forbidden	A key was sent and it is invalid or inactive, send none
404	Not Found	Resource not found
429	Rate Limited	Too many requests. Check Retry-After
503	Unavailable	The archive or the collector did not answer; retry after Retry-After

OpenAPI spec (JSON)Methodology llms.txt Licence and limits