API Documentation

Access real-time disaster data from 250 scientific monitoring sources via REST API.

Authentication

All API requests require a Bearer token. Include your API key in the Authorization header:

curl -H "Authorization: Bearer cal_YOUR_API_KEY" \
  "https://calamity.live/api/v1/events"

Get your API key from the pricing page. Keys are prefixed with cal_.

Base URL

https://calamity.live/api/v1

Rate Limits

Every response includes rate limit headers:

X-RateLimit-Limit: 60        # max requests per window
X-RateLimit-Remaining: 55   # remaining in current window
X-RateLimit-Reset: 1741512000  # Unix timestamp when window resets

When rate limited (429), check the Retry-After header for seconds until reset.

Events API

Query real-time and archived disaster events with filtering, pagination, and sorting.

GET/api/v1/eventsList events with filters

Parameters: type, severity, bbox, minScore, limit (max 500), offset

Example

curl -H "Authorization: Bearer cal_YOUR_KEY" \
  "https://calamity.live/api/v1/events?type=earthquake&severity=high&limit=10"

Response

{
  "events": [{ "id": "us7000...", "type": "earthquake", "title": "M6.2 Earthquake...", "severity": "high", "calamityScore": { "raw": 67, "confidence": 0.85 }, ... }],
  "meta": { "total": 342, "limit": 10, "offset": 0, "lastUpdated": "2026-03-09T12:00:00Z", "version": "v1" }
}

GET/api/v1/events/:idGet event by ID

Parameters: id (path)

Example

curl -H "Authorization: Bearer cal_YOUR_KEY" \
  "https://calamity.live/api/v1/events/us7000abcd"

Response

{ "id": "us7000abcd", "type": "earthquake", "title": "M5.8 ...", "severity": "high", "calamityScore": { "raw": 54 }, ... }

Cascades API

Access cascade risk predictions for active events, grouped by trigger.

GET/api/v1/cascadesList active cascades

Parameters: none

Example

curl -H "Authorization: Bearer cal_YOUR_KEY" \
  "https://calamity.live/api/v1/cascades"

Response

{
  "ok": true,
  "data": [{ "triggerEventId": "us7000...", "triggerType": "earthquake", "chains": [{ "rule": "H1", "targetType": "tsunami", "probability": 0.72, "depth": 1 }] }],
  "meta": { "total": 5, "totalChains": 12 }
}

Statistics API

Global and regional aggregate metrics.

GET/api/v1/statsGlobal statistics

Parameters: none

Example

curl -H "Authorization: Bearer cal_YOUR_KEY" \
  "https://calamity.live/api/v1/stats"

Response

{ "stats": { "totalEvents": 1850, "byType": { "earthquake": 342, ... }, "bySeverity": { "critical": 12, ... }, "sources": 218 } }

GET/api/v1/stats/typesEvent counts per type (7d/30d)

Parameters: none

Example

curl -H "Authorization: Bearer cal_YOUR_KEY" \
  "https://calamity.live/api/v1/stats/types"

Response

{ "ok": true, "data": { "earthquake": { "7d": 342, "30d": 1580 }, "fire": { "7d": 89, "30d": 412 } } }

GET/api/v1/stats/region/:codeRegion statistics

Parameters: code (path, ISO 3166-1 alpha-2)

Example

curl -H "Authorization: Bearer cal_YOUR_KEY" \
  "https://calamity.live/api/v1/stats/region/IT"

Response

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

Archive API

Paginated access to historically archived events stored in database.

GET/api/v1/archivePaginated archived events

Parameters: page, perPage (max 50), type, severity, countryCode

Example

curl -H "Authorization: Bearer cal_YOUR_KEY" \
  "https://calamity.live/api/v1/archive?page=1&perPage=20&type=earthquake"

Response

{ "events": [...], "meta": { "total": 7271, "page": 1, "perPage": 20, "pages": 364 } }

GET/api/v1/archive/:idSingle archived event

Parameters: id (path)

Example

curl -H "Authorization: Bearer cal_YOUR_KEY" \
  "https://calamity.live/api/v1/archive/abc123"

Response

{ "id": "abc123", "type": "earthquake", "title": "M6.2 ...", ... }

Health API

System health check. Public endpoint (no auth required for basic check).

GET/api/v1/healthHealth check

Parameters: none (add Bearer token for detailed status)

Example

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

Response

{ "status": "ok", "lastUpdated": "2026-03-09T12:00:00Z", "events": 1850, "sources": 218 }

Forecast API (v2)

Multi-hazard forecast scores per country, updated every 5 minutes. See CFI methodology for scoring details.

GET/api/v2/forecastList all forecast scores

Parameters: type (optional, hazard type filter)

Example

curl -H "Authorization: Bearer cal_YOUR_KEY" \
  "https://calamity.live/api/v2/forecast?type=earthquake"

Response

{ "scores": [{ "country": "JP", "hazardType": "earthquake", "cfi": 72, "level": "high", "drivers": "..." }] }

GET/api/v2/forecast/:countryCodeForecast for one country

Parameters: countryCode (path, ISO 3166-1 alpha-2)

Response

{ "scores": [{ "country": "JP", "hazardType": "earthquake", "cfi": 72, "level": "high" }, { "country": "JP", "hazardType": "tsunami", "cfi": 45, "level": "elevated" }] }

Rating API (v2)

Continuous country risk ratings with structural grade (A–E) and operational status. See rating methodology.

GET/api/v2/ratingList all country ratings

Parameters: status, minGrade (optional filters)

Response

{ "ratings": [{ "country": "JP", "grade": "C", "status": "yellow", "drivers": "..." }] }

GET/api/v2/rating/:countryCodeRating for one country with delta history

Parameters: countryCode (path, ISO 3166-1 alpha-2)

Response

{ "rating": { "country": "JP", "grade": "C", "status": "yellow" }, "deltas": [{ "from": "B", "to": "C", "briefText": "...", "timestamp": "..." }] }

GET/api/v2/rating/deltasRecent rating changes

Parameters: limit (optional, default 20)

Response

{ "deltas": [{ "country": "TR", "from": "B", "to": "D", "briefText": "M7.1 earthquake triggered cascade", "timestamp": "..." }] }

Oracle API (v2)

Parametric trigger contracts for automated enterprise workflows. Define conditions (geo, hazard type, severity, cascade, rating, forecast) and receive HMAC-signed webhook callbacks when they match.

POST/api/v2/oracle/contractsCreate a trigger contract

Body: { name, conditions, webhook_url, webhook_secret?, cooldown_minutes?, daily_cap? }

Example

curl -X POST -H "Authorization: Bearer cal_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"JP earthquake alert","conditions":{"country":"JP","hazardType":"earthquake","minSeverity":"high"},"webhook_url":"https://example.com/hook"}' \
  "https://calamity.live/api/v2/oracle/contracts"

Response

{ "id": "abc123", "hmac_secret": "hex-encoded-secret-shown-only-once" }

GET/api/v2/oracle/contractsList your contracts

Response

{ "contracts": [{ "id": "abc123", "name": "JP earthquake alert", "conditions": {...}, "enabled": true }] }

Webhook signature verification: Each webhook request includes an X-Calamity-Signature header containing an HMAC-SHA256 digest (hex-encoded) of the request body, signed with the shared secret returned at contract creation. Verify this signature server-side before processing the payload.

Error Codes

Status	Meaning	Description
400	Bad Request	Invalid parameters (type, severity, bbox, etc.)
401	Unauthorized	Missing or invalid API key
403	Forbidden	Key valid but insufficient permissions
404	Not Found	Resource not found
429	Rate Limited	Too many requests. Check Retry-After header
500	Server Error	Internal server error

Get API Key OpenAPI Spec (JSON)Methodology