An earthquake pin appears on a live map because a global network of seismometers felt the ground move, the USGS computed a location and magnitude from those recordings, published the result as GeoJSON — and your map happened to poll the feed at the right moment. The whole journey, from rupture to rendered pin, usually takes one to five minutes. Here's each hop, and what can go wrong at every one of them.
I run WorldEye, where earthquakes are one layer on a real-time globe alongside live cameras, flights, satellites and weather. The earthquake layer looks like the simplest one we ship. It taught me the most about respecting upstream data.
It starts with a seismometer, not a satellite
Earthquakes are not observed from space. They're recorded by seismometers — extremely sensitive ground-motion sensors, thousands of them, run by the USGS, universities and geological agencies worldwide and shared through federated networks.
When a fault ruptures, it radiates two wave types that matter here:
- P-waves (primary) travel at roughly 6 km/s through the crust. They arrive first and are the network's early warning that something happened.
- S-waves (secondary) travel at roughly 3.5 km/s, arrive later, and usually carry the stronger shaking.
A single station can tell you that something shook and roughly how far away it was (the P–S arrival gap grows with distance). It cannot tell you where. Locating an epicentre takes at least three stations — each one contributes a distance, and the circles intersect at the source. More stations, better geometry, smaller error ellipse. This is why location quality is superb under dense networks like California or Japan and genuinely fuzzy in the mid-ocean: the nearest seismometer might be an island hundreds of kilometres away.
The feed: GeoJSON, refreshed every minute
Once the network computes a solution, the USGS publishes it to a family of public GeoJSON feeds. The summary feeds are the workhorses:
-
summary/4.5_day.geojson— magnitude 4.5+ events, past day -
summary/2.5_week.geojson— magnitude 2.5+, past week -
summary/significant_month.geojson— the ones that mattered, past month -
summary/all_hour.geojson— everything detected, past hour (noisier than it sounds)
Each feed is regenerated about once a minute. Consuming one is refreshingly boring:
const FEED = "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/2.5_day.geojson"; const res = await fetch(FEED); const geojson = await res.json(); const quakes = geojson.features.map((f) => { const [lon, lat, depthKm] = f.geometry.coordinates; // GeoJSON order: lon, lat, depth const p = f.properties; return { id: f.id, // stable event ID — dedupe and update on this mag: p.mag, // may be revised, may occasionally be null early on magType: p.magType, // "mww", "ml", "mb", … — not all magnitudes are equal place: p.place, // "74km NW of Kandrian, Papua New Guinea" time: new Date(p.time), // origin time (when it happened) updated: new Date(p.updated), // last revision — often later than you think tsunami: p.tsunami === 1, // 1 = tsunami information was issued for this event status: p.status, // "automatic" vs "reviewed" lat, lon, depthKm, }; }); Three details in that payload bite every first-time integrator:
- Coordinate order is
[lon, lat, depth], not the[lat, lon]your map library probably wants. Swap them and your earthquake lands in the wrong ocean, mirrored. - Events are revised, not final. The same event ID reappears with a shifted epicentre, a changed magnitude, or a new depth as more station data arrives and analysts review it. If you insert-once and never update, your map fossilises the least accurate version of every quake.
-
statustells you how much to trust it. Early solutions areautomatic; a human-reviewed event flips toreviewed. Rendering both identically is a choice — and usually the wrong one.
Magnitude is a logarithm wearing a trench coat
The number in the pin is the single most misunderstood part of the whole system.
Magnitude scales are logarithmic in energy: each whole step up releases roughly 32× more energy (10^1.5 ≈ 31.6). A magnitude 6 is not "a bit worse" than a 5 — it's about 32 magnitude-5s worth of energy, and a 7 is about 1,000. This is why the difference between the ~13,000 magnitude-4 events the planet produces each year and the ~15 magnitude-7s is not a rounding error; it's the whole story.
A few more things the single number hides:
- There are several scales. Local magnitude (
ml), body-wave (mb) and moment magnitude (mww/mw) measure different things and can disagree by a few tenths for the same event. The feed'smagTypefield tells you which one you're looking at. Moment magnitude is the reference standard for large events because it doesn't saturate the way older scales do. - Depth changes everything. A magnitude 6 at 10 km depth under a city is a disaster; the same magnitude at 500 km depth is a trivia question. Depth is the third coordinate in the geometry — use it in your UI, even if it's just a label.
- Magnitude is not intensity. Magnitude is one number for the source. Intensity (the Modified Mercalli scale) describes shaking at a place, and varies with distance, depth and soil. The USGS also publishes "Did You Feel It?" crowd reports and ShakeMap intensity grids — different products, different questions.
The latency budget: where the minutes go
Why does a pin take one to five minutes — and why do some take twenty?
| Stage | Typical cost |
|---|---|
| Waves reach the nearest stations | seconds to ~2 min (distance-dependent) |
| Automatic detection + first location | ~30 s to a few minutes |
| Feed regeneration + your poll interval | up to ~2 min |
| Human review (revised solution) | minutes to hours later |
Two consequences follow. First, the first solution is the roughest one — the system is optimised to say something fast and correct it as data arrives. Second, your own polling interval is part of the budget: poll a one-minute feed every five minutes and you are the latency. Poll it every five seconds and you're just hammering a public service to render identical bytes. Match the feed's cadence, cache aggressively, and treat updated as a first-class field: when it changes, re-render the pin, don't just append a new one.
Offshore events deserve a special mention: with stations on one side only, early locations can be off by tens of kilometres, and the tsunami flag may flip as ocean-bottom pressure sensors (the DART buoy network) confirm or rule out a wave. A responsible map shows the flag; it doesn't editorialize it into a warning the issuing agencies haven't made.
Rendering it honestly
Everything above collapses into a handful of display rules we follow on the WorldEye earthquake layer:
- Update in place by event ID. A revised magnitude should visibly be a revision, not a second earthquake.
- Age and status are visual information. Colour or fade by recency; don't give an automatic solution the same authority as a reviewed one.
- Never imply prediction. A map of detected earthquakes is a record of the past minutes to days. The moment a UI makes it look like foresight, it has stopped being a data product and started being a rumour engine.
- Label the source and the timestamp. "USGS, updated 14:32 UTC" on the layer is worth more than any animation we could add.
You can see the result on the live globe — earthquakes sit next to 74,229 live public cameras, flights, satellites, weather radar and fire data, all from feeds with their own quirks like the ones above. Browsing is free; the engineering respect for upstream data, unfortunately, you have to build yourself.
Next in this series: rendering a planet in the browser — MapLibre, WebGL, and keeping a globe at 60fps on a phone.

