Skip to content
SoCloseSocietyPublic

About

Tracker temps reel des seismes, tsunamis, volcans et catastrophes naturelles -- 33 sources officielles agregees, diffusion websocket a la seconde, interface en 5 langues

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

SOSForge

CI Live License MIT

Live at https://sosforge.soclose.co

Real-time tracker for earthquakes, tsunamis, volcanoes, cyclones and disaster alerts. Thirty-three official sources (plus one optional) merged into a single normalized feed and pushed to the browser over a websocket with a one-second heartbeat. Interface in five languages.

No API key is required: all of them are public and open.

screenshot

On a phone the map comes first, bounded to a third of the screen, and the feed runs below it: the map is always one flick away, the feed is never starved. Mobile screenshot.

The idea

"Live to the second" does not come from hammering one API. It comes from a fan-in of heterogeneous sources, normalized into one event model, and a fan-out over websocket to every client.

EMSC websocket (push)      \
USGS GeoJSON (5 s)          \
JMA early warning (5 s)      \
JMA / BMKG / GeoNet           \
INGV / AFAD / GEOFON / CENC    >-- normalize -- horizon -- dedupe -- ring -- hub -- /ws -- UI
NOAA tsunami.gov (30 s)       /
NWS + Meteoalarm + WMO CAP   /
NHC cyclones (300 s)        /
Volcanic-ash SIGMETs       /
GDACS / NASA EONET        /

                                              + one server tick every second

EMSC is the only push source: it emits an earthquake the moment it is located, without waiting for a cycle. The others are polled at a rate matched to how often they actually publish -- polling USGS faster than it regenerates would return nothing new.

The thirty-three sources (no API key required)

Worldwide

Source Endpoint Mode What it adds
EMSC seismicportal wss://www.seismicportal.eu/standing_order/websocket push worldwide earthquakes, within seconds
USGS earthquake.usgs.gov/.../all_hour.geojson poll 5 s earthquakes + tsunami flag + PAGER alert level
GEOFON (GFZ) geofon.gfz.de/eqinfo/list.php?fmt=geojson poll 60 s third global catalogue: dedup becomes a three-way vote
NOAA NTWC / PTWC tsunami.gov/events/xml/PAAQAtom.xml, PHEBAtom.xml poll 30 s tsunami bulletins (Information / Watch / Advisory / Warning)
GDACS gdacs.org/xml/rss.xml poll 120 s cyclones, floods, fires, volcanoes, droughts, with a green/orange/red level
Volcanic-ash SIGMETs aviationweather.gov/api/data/isigmet?hazard=VA poll 180 s structured volcanic ash, worldwide -- the only machine-readable equivalent to the VAACs
NHC nhc.noaa.gov/CurrentStorms.json poll 300 s Atlantic and Pacific tropical cyclones: position, winds, category, advisory
NASA EONET eonet.gsfc.nasa.gov/api/v3/events poll 600 s ongoing natural events seen from space: wildfires tracked as events
WMO CAP aggregate severeweather.wmo.int/json/wmo_all.json poll 300 s official alerts for the rest of the world in a single call
USGS aftershock forecasts earthquake.usgs.gov/fdsnws/event/1/query?producttype=oaf poll 600 s the official probability of a damaging aftershock, valid until its own expireTime
NOAA SWPC services.swpc.noaa.gov/products/noaa-scales.json + Kp + alerts poll 600 s geomagnetic storm outlook and watch/warning bulletins

National and regional -- they are not here for redundancy. Each one adds something EMSC does not have.

Source Endpoint Mode What it adds
JMA early warning api.wolfx.jp/jma_eew.json poll 5 s the only feed issued WHILE the waves are still travelling
JMA (Japan) jma.go.jp/bosai/quake/data/list.json poll 45 s shindo, the intensity felt at ground level -- what matters in Japan, and it exists nowhere else
BMKG (Indonesia) data.bmkg.go.id/DataMKG/TEWS/ gempaterkini + autogempa + gempadirasakan poll 60 s the official Indonesian tsunami-potential flag, published before the PTWC bulletins, and every quake people felt, with its intensity
CENC (China) api.wolfx.jp/cenc_eqlist.json poll 120 s mainland China, with no other coverage here
GeoNet (New Zealand) api.geonet.org.nz/quake?MMI=3 poll 60 s very low local detection threshold on a very active zone
INGV (Italy) webservices.ingv.it/fdsnws/event/1/query poll 60 s same, in the standard FDSN format (the same contract as USGS)
AFAD (Turkey) deprem.afad.gov.tr/apiv2/event/filter poll 60 s fine coverage of the North Anatolian fault
NWS (USA) api.weather.gov/alerts/active poll 20 s floods, tornadoes, heat, tsunami on the American side
USGS HANS + Smithsonian volcanoes.usgs.gov/hans-public/api/... poll 300 s US volcanoes on alert (aviation colour code), located via the GVP catalogue
Meteoalarm (Europe) feeds.meteoalarm.org/api/v1/warnings/feeds-{country} poll 300 s national weather warnings across ten European countries
JMA tsunami (Japan) jma.go.jp/bosai/tsunami/data/list.json poll 30 s Japan's OWN tsunami advisories -- the two US centres do not cover its coasts
SSN UNAM (Mexico) ssn.unam.mx/rss/ultimos-sismos.xml poll 60 s the only national coverage for Mexico. Measured over three days on the whole Mexican box: USGS returned zero events, EMSC 52 above M3, SSN goes down to M1.4
NRCan (Canada) earthquakescanada.nrcan.gc.ca/fdsnws/event/1/query poll 60 s 87% of its events exist nowhere else in this feed (measured against USGS-week + EMSC)
NOA (Greece) eida.gein.noa.gr/fdsnws/event/1/query poll 60 s 96% exist nowhere else. The most seismically active country in Europe
GeoNet volcanoes (NZ) api.geonet.org.nz/volcano/val poll 300 s volcanic alert levels outside the US. Whakaari killed tourists in 2019 at level 2
EMSC felt reports seismicportal.eu/testimonies-ws/api/search poll 120 s how many people reported feeling it -- applied as a revision, not as a new event
PHIVOLCS (Philippines) earthquake.phivolcs.dost.gov.ph poll 120 s 84% of its events are in neither USGS nor EMSC
IGP (Peru) ultimosismo.igp.gob.pe/api/ultimo-sismo/ajaxb/{year} poll 60 s a subduction margin where depth decides everything; 88% exist nowhere else here
IMO (Iceland) api.vedur.is/quakes/events poll 120 s the swarms that precede Icelandic eruptions: over 80 h, 0 Icelandic events in EMSC, 31 at M1+ here
IMO volcanoes (Iceland) api.vedur.is/volcanoes/volcanoes poll 600 s ground alert level and aviation colour of every Icelandic volcano (Reykjanes orange)
JMA volcanoes (Japan) jma.go.jp/bosai/volcano/data/warning.json poll 300 s the five-level alert that orders evacuations in Japan; until now a Japanese volcano appeared only once its ash reached an aviation advisory
NCS (India) riseq.seismo.gov.in (event list in the page) poll 180 s the Himalaya, Hindu Kush and Indo-Burman ranges: 35% of its events are in neither USGS nor EMSC
Environment Agency (England), optional environment.data.gov.uk/flood-monitoring/id/floods poll 300 s off by default: Meteoalarm UK already relays its Flood Warnings word for word (5 of 5 measured). SOS_ENABLE_UKEA=true SOS_UKEA_MAX_LEVEL=3 adds the yellow-tier Flood Alerts only it publishes
US Drought Monitor droughtmonitor.unl.edu/data/json/usdm_current.json weekly map, checked every 6 h extreme and exceptional drought (D3/D4) regions: the product had no live drought at all

One source is of a different nature: early warning

The others publish after the fact: an earthquake happened, an agency located it, we display it. Japan's earthquake early warning is emitted while the waves are propagating, seconds after the nearest stations detect them. It is the only information in this product that can still be used to take cover.

Stated reserve. JMA and CENC do not expose an open API, so we go through the unofficial third-party relay Wolfx. It is a best-effort source: it enriches, it is authoritative over nothing, and its failure breaks nothing. Its websockets reject non-browser clients (403 Cloudflare), hence the polling. Turn it off with SOS_ENABLE_JMA_EEW=false.

Live climate indicators

GET /api/climate serves seven indicators, each read live from the agency that publishes it, each with its dataset's own date (as_of), its baseline computed from the same file, its previous value, and its own poll state and last error: global surface air temperature and sea surface temperature (Copernicus Climate Pulse, ERA5), daily CO2 at Mauna Loa (NOAA GML), Arctic and Antarctic sea ice extent (NSIDC Sea Ice Index), weekly Nino 3.4 and the ENSO alert status (NOAA CPC). A dataset late by its own standard is flagged stale; a failed poll says so with the real error. Nothing is hard-coded.

Getting started

cp .env.example .env      # nothing to fill in: everything is public
make install              # backend venv + npm install
make dev-api              # terminal 1 -- API on :8300
make dev-web              # terminal 2 -- UI on :5380

With Docker: make up, then http://localhost:8380.

Deployment

The service runs on the SoClose helper VPS behind the host nginx, which carries TLS and the domain name; the container itself only listens on the loopback.

ssh helper-vps
cd /root/SAAS/SuiteForge/SOSForge && git pull && docker compose up -d --build
Path on the server /root/SAAS/SuiteForge/SOSForge
Internal port 127.0.0.1:8380 (host nginx proxies to it)
Vhost /etc/nginx/sites-available/sosforge.soclose.co
Certificate certbot certonly --webroot -w /var/www/html -d sosforge.soclose.co
Data docker volume sos-data (JSONL journal, purged after 7 days)

Security headers live on the host: a restrictive CSP (the site loads only its own code, OpenFreeMap tiles and its websocket), nosniff, HSTS, and a permanent redirect from HTTP to HTTPS.

API

Route What it returns
GET /healthz service state, connected clients, ingested events
GET /readyz ready once the sources are up: sources_up, sources_total, down
GET /api/version {api, features[]}: what this server supports, for clients to detect
GET /api/events recent feed. Filters: limit, kind, min_magnitude, hours, primary_only. Zone: lat + lon + radius_km, or the websocket scope parameters below. since=<cursor> returns only what changed (new, revised, removed), with ETag / 304
GET /api/events/{id} one event (the raw source payload is deliberately left out)
GET /api/events/{id}/nearby live views of the area: deep links + webcams
GET /api/geocode?q= area search (Nominatim proxy, rate-limited and cached)
GET /api/place?lat=&lon= place report for ONE searched or clicked point (never the device position): 22 blocks (weather now and ahead, wind, sea state, sea level, sea temperature, buoy, air, pollen, drought, fire, water risk, national risk, hazard history, alerts now), each with its dataset's own as_of, source and licence, or unavailable / not_applicable with the real reason. radius_km 10..300, lang en/fr/es/ja/id. Strict query, ETag / 304 (Server-Time on both: a revalidated body's server_time is old), per-address budget (429, an IPv6 client by its /64); complete: false + retry_after_s whenever a block will read differently in seconds
GET /api/stats counters for the last hour
GET /api/sources health of every source (connected, events seen, last error)
GET /api/guidance?lang= what to do before / during / after, per hazard, each line with its official source
WS /ws snapshot on connect, then event / update / purge / tick (1/s). Optional scope: zones=lat,lon,radius_km;..., min_severity, kinds, unplaced

Websocket messages:

{"type": "snapshot", "events": [...], "stats": {...}, "sources": [...]}
{"type": "event",    "event": {...}, "primary": true, "breaking": true,  "escalated": false} // new event
{"type": "update",   "event": {...}, "primary": true, "breaking": false, "escalated": true}  // revision; escalated = got worse inside the breaking window
{"type": "purge",    "ids": [...], "reason": "stale|cancelled|lifted|expired|out_of_scope"}  // gone: remove it
{"type": "tick",     "server_time": "...", "stats": {...}}                                  // heartbeat, every second
{"type": "error",    "code": "bad_zones", "reason": "..."}                                  // scope refused, then close 1008

The interface

  • Time window: Live (15 min), 1 h, 6 h, 24 h, All. It is the first question anyone asks in front of a tracker, so it is the first control on the page.
  • Five languages (English, French, Spanish, Japanese, Indonesian), detected from the browser. The last two are not decorative: they are the populations most exposed to earthquakes and tsunamis, and exactly the ones the JMA and BMKG sources serve.
  • Every hazard type is always listed, even at zero. Showing only the types with current events made it look like the product did not cover tsunamis on the days there were none -- on an emergency tracker, "0 tsunami alerts" is information, not an absence of information.
  • Country flag on every event, resolved server-side. No identifiable country (open sea)? A globe, never an approximate flag.
  • Area search: typing a name filters the feed instantly (place, title, country) and offers to fly the map to that area even if nothing is happening there -- the most useful case in practice. Geocoding goes through the backend, which honours the one-request-per-second rate Nominatim requires.
  • Shareable link: every event has its own URL (#e/<id>). Without it you could not say "look at THIS earthquake" -- the recipient landed on a feed that had already moved on.
  • Filters are remembered: window, types and magnitude survive a reload. The text search is not: finding an invisible filter hiding the whole feed would be disorienting.
  • Click an event: the map dives close to the area, and a card opens live views -- Windy webcams, YouTube live search, today's NASA Worldview imagery, satellite view. Those links work with no key at all; with a Windy key (SOS_WINDY_API_KEY), the real list of nearby public webcams appears with thumbnails.

What the system handles explicitly

  • Revisions. EMSC and USGS revise their solutions within minutes. A known event whose fingerprint changes becomes an update, not a duplicate. The UI marks the row "revised".
  • Cross-source dedup. The same earthquake arrives under several identifiers (EMSC, USGS, GEOFON...). They are grouped into a cluster: 90 s, 250 km and 1.2 magnitude points apart at most. Nothing is deleted, one representative is shown.
  • Wave propagation. For a magnitude 4+ earthquake less than six minutes old, the map draws both wave fronts live: P at 6 km/s (first shaking) and S at 3.5 km/s (the damaging one). This is the only thing in the interface that shows where the shaking is arriving right now. Average crustal speeds, so accurate near the epicenter and approximate far away -- the circles stop at 1200 km, before they would start lying.
  • GDACS noise. The full feed is ~400 entries, of which ~344 are green wildfires and droughts open for a year. Filter: orange and red always, green only if freshly published (SOS_GDACS_MAX_AGE_DAYS).
  • Alert volume. Meteoalarm and the WMO aggregate together emit ~4300 bulletins per cycle, mostly routine rain and heat. Severity thresholds keep orange-and-above for Europe and the top tier for the WMO. Measured reserve: the WMO scale is not consistent between countries.
  • "No danger" bulletins. A tsunami bulletin of category Information usually says "there is NO tsunami danger": it is displayed, but it does not raise the tsunami flag and does not trigger the sound.
  • A warning's advance notice. A weather warning is published BEFORE it starts -- that is its whole point. Its timestamp is legitimately in the future, so the future-timestamp filter exempts it when the source declares it ongoing. An earthquake cannot be dated in advance.
  • Timestamps in the future. A source with a drifting clock produced events of negative age: past the horizon, permanently announced as "live", and pinned at the top of a date-sorted feed. Beyond two minutes of lead, rejected.
  • Archives versus current events. Several sources serve a catalogue, not a feed: the JMA list goes back more than nine months. An ingestion horizon (SOS_MAX_EVENT_AGE_DAYS) discards them, with one nuance that matters: a severe and ongoing alert (a red cyclone) survives, a past earthquake does not -- an earthquake is instantaneous, it does not "last".
  • Finished alerts. An ongoing alert (EONET fire, NHC cyclone, current GDACS alert) escapes the horizon as long as its source publishes it. A sweep removes the ones no source has mentioned for six hours: a source going silent has implicitly said it is over.
  • Journal retention. The JSONL journal grows by about 5 MB per day. A sweep deletes those older than SOS_JOURNAL_KEEP_DAYS: on a service that runs continuously, nobody watches a disk filling up.
  • Background tasks that die. The one-second heartbeat and the sweep catch their exceptions. A single uncaught error killed the task for good: no more ticks, every client reconnecting, and /healthz answering "ok" throughout.
  • A dead connection. A websocket can stay "open" and deliver nothing. The one-second server tick is the proof of life: 15 s of silence and the client reconnects instead of showing a frozen feed while claiming it is live. A server that accepts the connection and then says nothing is closed too -- otherwise the very first connection could hang forever, announcing "LIVE".
  • A slow client. Its queue is bounded; if it cannot keep up it is dropped rather than slowing down ingestion, and its socket is closed rather than left silently open.
  • A failing source. A source whose every feed fails cannot show as green. The footer shows the real state of every one of them, and a source with one dead feed out of several (one tsunami centre, one Meteoalarm country) is shown degraded, naming the feed, rather than green.
  • No WebGL. The map degrades cleanly and the alert feed keeps running.

Verification

make test        # 95 backend tests + 77 frontend tests
make lint
make typecheck   # tsc + mypy
make smoke       # live state of every source

Backend fixtures are verbatim excerpts of real responses. A unit test on an invented payload proves nothing here: this project has been bitten by hand-written fixtures that made a working parser look broken.

Design decisions

No database in v1. A live tracker needs the last hour, not a warehouse: an in-memory ring buffer (5000 events) plus a daily JSONL journal for audit and replay. EventStore is the single storage point -- Postgres can be plugged in behind the same interface the day history becomes a product requirement.

Severity is a "status" palette, not a series palette. Five levels, reserved colours, and never colour alone: every level also carries a glyph and a label, so it stays readable with colour-vision deficiency and in black and white.

Deliberately left out, after checking. FIRMS and EFFIS (fires): about 3 h of NRT latency and no event identifier -- "fire to the second" does not exist anywhere. SeedLink and Raspberry Shake: waveforms, not events. GloFAS and Copernicus EMS: key required, and GDACS already republishes the essentials. The BOM (Australia) API works but its own payload forbids reuse. Checked on 2026-10-26 and left out: Chile CSN (HTML only, fully relayed by EMSC, reuse limited to academic use), KOERI (non-commercial clause; AFAD covers Turkey), Geoscience Australia (every event already in EMSC), IGEPN (page frozen since June), MAGMA Indonesia (API answering 500), ReliefWeb (approved appname now required), Taiwan CWA and Korea KMA (key required), Colombia SGC (403).

Sources and attribution

Data: EMSC/CSEM, USGS, NOAA (NWS, NTWC, PTWC, NHC, SWPC, Aviation Weather Center), GDACS (European Commission and UN), Smithsonian Institution Global Volcanism Program, JMA (Japan; 出典:気象庁ホームページ), BMKG (Indonesia), CENC (China), GNS Science / GeoNet (New Zealand), INGV (Italy), AFAD (Turkey), GFZ GEOFON, NASA EONET, Meteoalarm, WMO, SSN UNAM (Mexico), NRCan (Canada), NOA (Greece), PHIVOLCS (Philippines), IGP (Peru), the Icelandic Meteorological Office (CC BY 4.0), the National Center for Seismology (India), the Environment Agency (this uses Environment Agency flood and river level data from the real-time data API (Beta), OGL v3), the U.S. Drought Monitor (jointly produced by the National Drought Mitigation Center at the University of Nebraska-Lincoln, the USDA, NOAA and NASA; map courtesy of NDMC). Climate: Copernicus Climate Change Service / ECMWF (generated using Copernicus Climate Change Service information), NOAA GML, NSIDC (Sea Ice Index v4), NOAA CPC. Basemap by OpenStreetMap, OpenMapTiles and OpenFreeMap. These feeds are public; they belong to their producers.

Place report (/api/place): METAR reports via NOAA Aviation Weather Center; forecasts from The Norwegian Meteorological Institute (MET Norway, CC BY 4.0 and NLOD 2.0) and NOAA/National Weather Service; weather, marine and air quality data by Open-Meteo.com from its open-data bucket (CC BY 4.0), from Meteo-France MFWAM and SMOC (generated using E.U. Copernicus Marine Service information) and the Copernicus Atmosphere Monitoring Service (generated using Copernicus Atmosphere Monitoring Service information; neither the European Commission nor ECMWF is responsible for any use made of it); NOAA CoastWatch Geo-Polar Blended SST; NOAA National Data Buoy Center (each station's owner, from NDBC's station owners file, named in the block); Copernicus Emergency Management Service (Global Drought Observatory; Global Wildfire Information System, ECMWF fire danger forecast); NASA FIRMS (VIIRS NOAA-20 and NOAA-21); World Resources Institute Aqueduct 4.0 (CC BY 4.0); INFORM Risk Index (European Commission Joint Research Centre, CC BY 4.0); USGS ANSS ComCat; NOAA NCEI/WDS Global Significant Earthquake, Historical Tsunami and Significant Volcanic Eruptions databases; Global Volcanism Program, Volcanoes of the World, distributed by Smithsonian Institution, compiled by Venzke, E. (a work of US Government employees, cited with the day its web service was read: the version number is published only on a page closed to non-browser clients); IBTrACS v04r01 (Knapp et al., NOAA NCEI). The European and US air quality indices, distances, rings, decade counts, model tide extremes and the sea level's window mean are computed by SOSForge from those data (modified). Model sea level is referenced to the GLOBAL mean sea level, not to the local mean nor chart datum. Countries and coastline: Natural Earth (public domain).

ISC-GEM, shared alike. The USGS catalogue relays rows of the ISC-GEM Global Instrumental Earthquake Catalogue (International Seismological Centre, CC BY-SA 3.0). When a place's history.earthquakes block contains such rows (net iscgem), the block names ISC-GEM in source.also and that block's data is shared under CC BY-SA 3.0.

SOSForge is not an official warning service. In a real emergency, your local civil protection authority is the reference.

About

Tracker temps reel des seismes, tsunamis, volcans et catastrophes naturelles -- 33 sources officielles agregees, diffusion websocket a la seconde, interface en 5 langues

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages