{"openapi":"3.1.0","info":{"title":"World Natural Disasters API","version":"1.0.0","summary":"Free JSON and GeoJSON feed of live natural disasters worldwide.","description":"Live natural disaster events aggregated from USGS, EMSC, GDACS (European Commission / UN), NASA EONET, NOAA/NWS and ReliefWeb (UN OCHA), re-synced every two minutes.\n\nNo key and no registration. CORS is enabled, so browser requests work from any origin. Rate limited to 120 requests per minute per IP.\n\n**This is not an official warning system.** It aggregates public feeds; national agencies issue warnings and they are the authority. Please say so in anything you build with it.\n\nAll timestamps are UTC.","termsOfService":"https://worldnaturaldisasters.com/terms","contact":{"name":"World Natural Disasters","url":"https://worldnaturaldisasters.com/contact"},"license":{"name":"Free to use with attribution","url":"https://worldnaturaldisasters.com/data-sources"}},"servers":[{"url":"https://worldnaturaldisasters.com/api/v1","description":"Production"}],"externalDocs":{"description":"Human-readable documentation","url":"https://worldnaturaldisasters.com/api"},"tags":[{"name":"Events","description":"Live and recent disaster events"},{"name":"Places","description":"Country profiles and official agencies"},{"name":"Statistics","description":"Global counts and yearly totals"}],"paths":{"/events":{"get":{"tags":["Events"],"summary":"Recent events, newest first","description":"Pass `balanced=1` for anything map-shaped. Ordering by recency is nearly useless at global scale: satellite fire detections and US county weather warnings arrive in the hundreds an hour, so the newest 100 rows are almost entirely those two and every earthquake is crowded out. Balanced mode deals the hazard buckets round-robin instead.","operationId":"listEvents","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":400,"default":30},"description":"1–100, or 1–400 when `balanced=1`."},{"name":"type","in":"query","schema":{"type":"string","example":"earthquake"},"description":"Hazard type slug."},{"name":"severity","in":"query","schema":{"type":"string","enum":["minor","moderate","severe","extreme"]},"description":"Minimum reported severity."},{"name":"country","in":"query","schema":{"type":"string","example":"PK","pattern":"^[A-Za-z]{2}$"},"description":"ISO 3166-1 alpha-2 code."},{"name":"balanced","in":"query","schema":{"type":"string","enum":["1"]},"description":"Set to `1` to spread results across every hazard. Ignored when `type` is set — a single-hazard query is balanced by definition."},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":30,"default":7},"description":"Look-back window for `balanced=1`."},{"name":"lite","in":"query","schema":{"type":"string","enum":["1"]},"description":"Set to `1` to omit `icon_svg` and `severity_html`. Roughly 45% smaller; use it unless you specifically want our markup."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventList"}}}},"429":{"description":"Rate limited — 120 requests per minute per IP. Carries `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events/geojson":{"get":{"tags":["Events"],"summary":"The same events as a GeoJSON FeatureCollection","description":"Ready to drop into Leaflet, Mapbox or QGIS. Hazard-balanced by construction.","operationId":"eventsGeoJson","parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":30,"default":7},"description":"Look-back window."}],"responses":{"200":{"description":"Success","content":{"application/geo+json":{"schema":{"$ref":"#/components/schemas/FeatureCollection"}}}},"429":{"description":"Rate limited — 120 requests per minute per IP. Carries `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events/{slug}":{"get":{"tags":["Events"],"summary":"One event, with its revision history","description":"Every event page on the site links here. `source_class` says what KIND of statement this is — `warning`, `measurement`, `detection` or `report` — and `severity_from_source` says whether that severity was rated by the agency or classified by this site. Only NWS and GDACS publish a severity we map; for USGS, EMSC, FIRMS, EONET and ReliefWeb the level is ours, and a consumer that ignores this field will present our classification as an agency grade. `revisions` lists changes to severity, status and magnitude since the event was first recorded, and exists nowhere else — it is usually empty.","operationId":"getEvent","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","example":"m6-2-earthquake-south-sandwich-islands-region-20260903"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventDetail"}}}},"429":{"description":"Rate limited — 120 requests per minute per IP. Carries `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/notable":{"get":{"tags":["Events"],"summary":"The few events worldwide that are actually notable","description":"Ranked by scale and capped at one per country. Use this, not `/events`, for \"what is happening in the world right now\": a sample of the 100 most recent `extreme` events came back as 98 US tornado warnings.","operationId":"notableEvents","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":6,"default":3}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedList"}}}},"429":{"description":"Rate limited — 120 requests per minute per IP. Carries `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/alerts/latest":{"get":{"tags":["Events"],"summary":"The homepage alert feed, hazard-diversified","operationId":"latestAlerts","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedList"}}}},"429":{"description":"Rate limited — 120 requests per minute per IP. Carries `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/search":{"get":{"tags":["Events"],"summary":"Free-text search across events","operationId":"searchEvents","parameters":[{"name":"q","in":"query","schema":{"type":"string","example":"flood"},"description":"Search term.","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedList"}}}},"429":{"description":"Rate limited — 120 requests per minute per IP. Carries `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stats":{"get":{"tags":["Statistics"],"summary":"Live global counts","operationId":"globalStats","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stats"}}}},"429":{"description":"Rate limited — 120 requests per minute per IP. Carries `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/year/{year}":{"get":{"tags":["Statistics"],"summary":"Year-to-date totals from the agencies’ own archives","operationId":"yearTotals","parameters":[{"name":"year","in":"path","required":true,"schema":{"type":"integer","example":2026}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YearTotals"}}}},"429":{"description":"Rate limited — 120 requests per minute per IP. Carries `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/countries":{"get":{"tags":["Places"],"summary":"Every country and territory","operationId":"listCountries","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountryList"}}}},"429":{"description":"Rate limited — 120 requests per minute per IP. Carries `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/country/{slug}":{"get":{"tags":["Places"],"summary":"One country profile with its official national agencies","description":"`emergency_links` is a JSON-encoded array of `{name, url}`. It is present for 145 of the 201 countries: every link was checked to return 200 **and** to name the agency on the page, and any that could not be verified was left out rather than guessed.","operationId":"getCountry","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","example":"pakistan"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountryProfile"}}}},"429":{"description":"Rate limited — 120 requests per minute per IP. Carries `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Event":{"type":"object","properties":{"slug":{"type":"string"},"url":{"type":"string","format":"uri","description":"The human-readable page for this event."},"title":{"type":"string"},"type":{"type":"string","example":"earthquake"},"type_name":{"type":"string","example":"Earthquake"},"severity":{"type":"string","enum":["minor","moderate","severe","extreme"]},"status":{"type":"string","example":"monitoring"},"country":{"type":["string","null"]},"country_slug":{"type":["string","null"]},"region":{"type":["string","null"]},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]},"magnitude":{"type":["number","null"],"description":"Earthquakes only."},"event_time":{"type":"string","format":"date-time","description":"ISO 8601 with offset, always UTC."},"time_ago":{"type":"string","example":"4 min ago"},"source":{"type":"string","description":"Originating agency key: usgs, emsc, gdacs, eonet, nws, reliefweb, firms."},"last_updated":{"type":"string","format":"date-time"}}},"FeedEvent":{"type":"object","description":"As Event, plus the two server-rendered fields. These endpoints do not support `lite`.","properties":{"slug":{"type":"string"},"url":{"type":"string","format":"uri","description":"The human-readable page for this event."},"title":{"type":"string"},"type":{"type":"string","example":"earthquake"},"type_name":{"type":"string","example":"Earthquake"},"severity":{"type":"string","enum":["minor","moderate","severe","extreme"]},"status":{"type":"string","example":"monitoring"},"country":{"type":["string","null"]},"country_slug":{"type":["string","null"]},"region":{"type":["string","null"]},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]},"magnitude":{"type":["number","null"],"description":"Earthquakes only."},"event_time":{"type":"string","format":"date-time","description":"ISO 8601 with offset, always UTC."},"time_ago":{"type":"string","example":"4 min ago"},"source":{"type":"string","description":"Originating agency key: usgs, emsc, gdacs, eonet, nws, reliefweb, firms."},"last_updated":{"type":"string","format":"date-time"},"icon_svg":{"type":"string","description":"Server-rendered SVG. Absent when `lite=1`."},"severity_html":{"type":"string","description":"Server-rendered badge. Absent when `lite=1`."}}},"Revision":{"type":"object","properties":{"field":{"type":"string","enum":["severity","status","magnitude"]},"from":{"type":"string","nullable":true},"to":{"type":"string","nullable":true},"described":{"type":"string","example":"Severity raised from Moderate to Severe"},"source":{"type":"string","description":"Which feed made the change."},"changed_at":{"type":"string","format":"date-time"}}},"EventDetail":{"type":"object","description":"As Event, plus provenance and history. Returned only by /events/{slug}.","properties":{"slug":{"type":"string"},"url":{"type":"string","format":"uri","description":"The human-readable page for this event."},"title":{"type":"string"},"type":{"type":"string","example":"earthquake"},"type_name":{"type":"string","example":"Earthquake"},"severity":{"type":"string","enum":["minor","moderate","severe","extreme"]},"status":{"type":"string","example":"monitoring"},"country":{"type":["string","null"]},"country_slug":{"type":["string","null"]},"region":{"type":["string","null"]},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]},"magnitude":{"type":["number","null"],"description":"Earthquakes only."},"event_time":{"type":"string","format":"date-time","description":"ISO 8601 with offset, always UTC."},"time_ago":{"type":"string","example":"4 min ago"},"source":{"type":"string","description":"Originating agency key: usgs, emsc, gdacs, eonet, nws, reliefweb, firms."},"last_updated":{"type":"string","format":"date-time"},"source_class":{"type":"string","enum":["warning","measurement","detection","report"],"description":"What KIND of statement this is. A `detection` is an instrument reading nobody has assessed; only a `warning` was issued to the public by an authority. Presenting the four alike is the misreading this field exists to prevent."},"source_name":{"type":"string","example":"US Geological Survey"},"severity_from_source":{"type":"boolean","description":"True when `severity` is the rating the agency published. False when it is this site classification, which is the case for USGS, EMSC, FIRMS, EONET and ReliefWeb."},"revisions":{"type":"array","description":"Changes since the event was first recorded, newest first. Usually empty.","items":{"$ref":"#/components/schemas/Revision"}}}},"EventList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"generated_at":{"type":"string","format":"date-time"}}},"FeedList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeedEvent"}},"generated_at":{"type":"string","format":"date-time"}}},"FeatureCollection":{"type":"object","properties":{"type":{"type":"string","const":"FeatureCollection"},"features":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"Feature"},"geometry":{"type":"object","properties":{"type":{"type":"string","const":"Point"},"coordinates":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"GeoJSON order: [longitude, latitude]."}}},"properties":{"type":"object"}}}},"generated_at":{"type":"string","format":"date-time"}}},"Stats":{"type":"object","properties":{"active":{"type":"integer"},"countries_affected":{"type":"integer"},"quakes_24h":{"type":"integer"},"fires_active":{"type":"integer"},"storms_active":{"type":"integer"},"severe_alerts":{"type":"integer"},"last_update":{"type":"string","example":"2026-08-09 12:34:56","description":"**UTC, with no offset in the string.** Every other timestamp in this API carries one. Parse this as UTC — reading it as local time is a bug we shipped in our own app."}}},"YearTotals":{"type":"object","properties":{"year":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"},"coverage_to":{"type":"string","format":"date"},"monitoring_since":{"type":["string","null"]},"url":{"type":"string","format":"uri"},"sources":{"type":"object","description":"Per-source totals, keyed by agency (usgs, eonet)."}}},"CountryList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"iso2":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"continent":{"type":"string"}}}}}},"CountryProfile":{"type":"object","properties":{"data":{"type":"object","properties":{"iso2":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"continent":{"type":"string"},"url":{"type":"string","format":"uri"},"overview":{"type":["string","null"],"description":"Written hazard profile for this country."},"risk_profile":{"type":["string","null"],"description":"Season-by-season summary of when each hazard is likely."},"emergency_links":{"type":["string","null"],"description":"JSON-encoded array of {name, url} for the official national agencies."}}}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}}}}}