# USGS earthquakes

> Every earthquake above the chosen magnitude threshold, worldwide, across the entire history of the U.S. Geological Survey’s ANSS Comprehensive Catalog — about 312,000 events at magnitude 4.5 and above, the oldest of them from 1568. One row per event, revised in place as USGS refines the numbers: magnitude, depth and location all move in the hours and days after an event, and historical entries are re-evaluated decades later, so this dataset follows them rather than freezing the first estimate. Each row also carries the uncertainties the catalogue publishes — horizontal and vertical location error, magnitude error, the station counts behind each — and the networks that actually computed the location and the magnitude.

- Dataset id: `usgs-earthquakes`
- Update cadence: daily
- Upstream source: https://earthquake.usgs.gov/fdsnws/event/1/
- Tags: earthquakes, seismology, geology, hazards, usgs, anss, events, geospatial, historical
- Current version: ingest `01M54Q0E1AYRZSGBX71TQ8RBGC`, snapshot 2026-10-17, generated 2026-10-17T10:50:49.931Z

## Licence and attribution

- Licence: U.S. Geological Survey — public domain (17 U.S.C. § 105) (`usgs-public-domain`)
- Licence text: https://www.usgs.gov/information-policies-and-instructions/copyrights-and-credits
- Required attribution: Earthquake data courtesy of the U.S. Geological Survey (USGS).
- Notes: USGS-authored content is in the public domain in the United States and may be reused freely with credit. Two caveats a reuser must read. First, the ANSS Comprehensive Catalog behind this web service aggregates contributions from regional and international seismic networks; an individual event may originate with a contributor whose own terms differ, and the `network`, `location_source` and `magnitude_source` columns name those contributors. Second, this is a living catalogue, not a frozen catalogue of record: recent events carry preliminary automatic solutions, historical events are re-evaluated, values are revised and events are occasionally withdrawn. Do not use it where life or property depends on the number.

Reproduce the attribution line verbatim anywhere you republish this data.

## Manifest

- Start here for how this directory works: https://data.bunnytech.app/llms.txt
- This dataset: https://data-directory.fsn1.your-objectstorage.com/public/usgs-earthquakes/manifest.json
- All datasets: https://data-directory.fsn1.your-objectstorage.com/public/index.json
- Human page: https://data.bunnytech.app/datasets/usgs-earthquakes

The manifest is the contract: file URLs, row counts, column types, min/max statistics and
example queries all live there. Re-read it to discover a new version.

## Fastest path — Parquet exports

Immutable, physically sorted snapshot exports. No catalog fetch, best row-group pruning,
safe to cache forever. Register one view per table:

```sql
INSTALL httpfs; LOAD httpfs;

CREATE OR REPLACE VIEW quakes AS
  SELECT * FROM read_parquet('https://data-directory.fsn1.your-objectstorage.com/public/usgs-earthquakes/v/01M54Q0E1AYRZSGBX71TQ8RBGC/quakes.parquet');
```

Example queries:

-- The ten largest earthquakes ever recorded in the catalogue: No time filter, so this reads the whole file — which is the one question that legitimately does.
```sql
ATTACH IF NOT EXISTS 'ducklake:https://data-directory.fsn1.your-objectstorage.com/catalog/catalog.ducklake' AS "datadirectory" (READ_ONLY);

SELECT event_time, magnitude, magnitude_type, place, depth_km
FROM datadirectory.usgs_earthquakes.quakes
ORDER BY magnitude DESC
LIMIT 10
```

-- How the annual count of M4.5+ events changes over a century: The rise through the 1960s is the World-Wide Standardized Seismograph Network coming online, not the Earth getting busier. Detection, not seismicity.
```sql
ATTACH IF NOT EXISTS 'ducklake:https://data-directory.fsn1.your-objectstorage.com/catalog/catalog.ducklake' AS "datadirectory" (READ_ONLY);

SELECT date_trunc('year', event_time) AS year,
       count(*) AS quakes,
       count(*) FILTER (WHERE magnitude >= 6) AS m6_plus
FROM datadirectory.usgs_earthquakes.quakes
WHERE event_time >= '1900-01-01'
GROUP BY 1
ORDER BY 1
```

## Live lake — DuckLake catalog with time travel

Attach the published catalog read-only over plain https. This works in native DuckDB AND in
duckdb-wasm in the browser — the reader catalog resolves its data files through public https
URLs, so no credentials and no backend are involved.

```sql
INSTALL ducklake; LOAD ducklake;
ATTACH 'ducklake:https://data-directory.fsn1.your-objectstorage.com/catalog/usgs-earthquakes/catalog.ducklake' AS usgs_earthquakes (READ_ONLY); SELECT * FROM usgs_earthquakes.main.quakes LIMIT 5;
USE usgs_earthquakes;
```

- Latest catalog: https://data-directory.fsn1.your-objectstorage.com/catalog/usgs-earthquakes/catalog.ducklake
- This exact version: https://data-directory.fsn1.your-objectstorage.com/catalog/usgs-earthquakes/v/01M54Q0E1AYRZSGBX71TQ8RBGC/catalog.ducklake (sha256 3e777cdf2cef5092f3d9a65d0a6b8653c8674597022a349c22f72708e181c64e)
- Written by DuckDB v1.5.5
- Time travel: this ingest is snapshot 38 — e.g. `SELECT * FROM usgs_earthquakes.quakes AT (VERSION => 38)`

## Wholesale — S3 access

For bulk downloads, read the bucket prefix directly over S3 with httpfs:

```sql
INSTALL httpfs; LOAD httpfs;
CREATE SECRET hetzner (
  TYPE s3,
  ENDPOINT 'fsn1.your-objectstorage.com',
  URL_STYLE 'path',
  KEY_ID '<public-read-not-required>', SECRET ''
);
SELECT * FROM read_parquet('s3://data-directory/public/usgs-earthquakes/v/01M54Q0E1AYRZSGBX71TQ8RBGC/**/*.parquet');
```

## Schema

### quakes
One row per earthquake in the USGS ANSS Comprehensive Catalog above the run’s magnitude threshold, carrying the most recent values USGS has published for it — the whole catalogue, from the sixteenth century to this morning, not a rolling window. Events are revised after the fact — magnitude, depth and location all move as more stations report, and historical entries are re-evaluated decades later — so a row is a current best estimate, not an immutable observation. first_seen_date / last_seen_date record the window over which we observed it.
- 312.9K rows · 12 MB · write mode `upsert`
- Physically sorted by: `event_time`, `event_id`
- Primary key: `event_id`
- Text search columns: `place`
- Files: 1
  - https://data-directory.fsn1.your-objectstorage.com/public/usgs-earthquakes/v/01M54Q0E1AYRZSGBX71TQ8RBGC/quakes.parquet (312.9K rows)

Columns:
- `event_id` VARCHAR NOT NULL — USGS event id, e.g. "us6000tmtu". Stable across revisions and unique across networks; the primary key. Append it to the event page URL to see the source record. (range: "aacse0198bme8d8" … "wes19050715101000000") (~357921 distinct)
- `event_time` TIMESTAMPTZ NOT NULL — When the earthquake occurred (origin time, UTC). Not when it was reported. (range: "1568-01-01 00:00:00+00" … "2026-10-17 09:07:40.745+00")
- `updated_at` TIMESTAMPTZ — When USGS last revised this event (UTC). A recent value on an old event means the numbers moved — historical events are re-evaluated too, so this is often centuries after event_time.
- `magnitude` DECIMAL(4,2) — Magnitude on the scale named by magnitude_type.
- `magnitude_type` VARCHAR — Which magnitude scale produced the value: mb, ml, mw, mww, ms_20, mint (an intensity-derived magnitude, common on pre-instrumental events) … They are NOT interchangeable; comparing magnitudes across types is a mistake.
- `place` VARCHAR — Human-readable location as written by the catalogue.
- `place_lc` VARCHAR — place, lowercased and accent-folded, for case- and accent-insensitive search. Query this, not lower(place) — a function on a column cannot use parquet statistics.
- `latitude` DOUBLE [degrees] — Epicentre latitude (WGS 84).
- `longitude` DOUBLE [degrees] — Epicentre longitude (WGS 84).
- `depth_km` DOUBLE [km] — Depth below the surface. Can be slightly negative for shallow events — that is the solver, not bad data. Null on most historical events, which have no depth solution.
- `felt_reports` INTEGER [reports] — How many people filed a "Did You Feel It?" report.
- `community_intensity` DOUBLE — Reported intensity from those reports (CDI), on the MMI scale.
- `instrumental_intensity` DOUBLE — Estimated instrumental intensity (MMI) from ShakeMap.
- `alert_level` VARCHAR — PAGER alert: green, yellow, orange or red — an estimate of expected impact, not of size.
- `tsunami_flag` BOOLEAN — True when the event lies in a region with an active tsunami notification. It does NOT mean a wave was observed.
- `significance` INTEGER — USGS significance score (0-1000), combining magnitude, felt reports and estimated impact.
- `review_status` VARCHAR — "automatic" (machine-picked, still moving) or "reviewed" (a seismologist has checked it).
- `network` VARCHAR — The network whose id namespace this event lives in — the prefix of event_id, e.g. us, ak, ci, hv, official, ushis. Compare location_source and magnitude_source, which name who actually computed each number and are often different.
- `station_count` INTEGER [stations] — Number of stations used to compute the location.
- `azimuthal_gap` DOUBLE [degrees] — Largest azimuthal gap between stations. Above ~180° the location is poorly constrained.
- `horizontal_error_km` DOUBLE [km] — Horizontal (epicentral) location uncertainty, as the radius of the 68% confidence circle. Use it to decide whether two epicentres are actually distinguishable before you map or cluster them.
- `depth_error_km` DOUBLE [km] — Vertical location uncertainty: the largest projection of the 68% confidence ellipsoid onto the vertical. Frequently far larger than horizontal_error_km — a depth of "10 km" with a 10 km error is the solver’s default, not a measurement.
- `magnitude_error` DOUBLE — Uncertainty of the reported magnitude, as the estimated standard error. Compare it against the difference before calling one event bigger than another.
- `magnitude_station_count` INTEGER [stations] — How many stations contributed amplitude readings to the MAGNITUDE. Distinct from station_count, which counts the stations used for the LOCATION — the two are computed from different picks and routinely differ by a factor of several.
- `rms` DOUBLE [s] — Root-mean-square residual of the travel-time fit: how well the observed arrival times match the ones the solution predicts. Smaller is better, but it is only comparable between events located by the same network with the same velocity model.
- `min_distance_deg` DOUBLE [degrees] — Angular distance from the epicentre to the nearest station that reported (the FDSN "dmin" field). One degree is about 111 km. A large value means the nearest instrument was far away, which is the other half of the story azimuthal_gap tells.
- `location_source` VARCHAR — The network that produced the LOCATION for this event, e.g. us, ak, official, ushis. Often not the same as network, and not the same as magnitude_source.
- `magnitude_source` VARCHAR — The network that produced the MAGNITUDE for this event. A row can carry a location from one network and a magnitude from another — filter on this when comparing magnitudes.
- `event_type` VARCHAR — What the catalogue says this was: earthquake, quarry blast, explosion, ice quake … Filter on it — the catalogue is not all earthquakes.
- `event_url` VARCHAR — USGS event page for this earthquake.
- `first_seen_date` DATE NOT NULL — The first run day (UTC) on which we saw this event. Maintained automatically by the upsert loader — never overwritten, only widened. It says when this dataset first ingested the event, never when the event happened: that is event_time.
- `last_seen_date` DATE NOT NULL — The most recent run day (UTC) on which the catalogue still carried this event within the window that run asked for.


## Performance notes

- There are no indexes in a lakehouse. The physical sort order plus Parquet row-group min/max
  statistics ARE the index. Predicates on the leading sort columns prune whole row groups;
  everything else is a full column scan.
- `quakes` prunes on `event_time` → `event_id`.
- `ILIKE '%needle%'` cannot prune: it decompresses that whole column. Prefer prefix predicates
  on the lowercased search companion columns where they exist.
- Every file URL under `/v/<ingestId>/` is immutable. Cache it as aggressively as you like.
- Files are never rewritten in place — a new ingest writes a new version path. Re-read the
  manifest to pick up updates rather than polling the file URLs.
- Pull only the columns you need. Parquet is columnar and the reader range-GETs what it reads.

## Do not

- Do not scrape https://data.bunnytech.app HTML. Every number on those pages comes from the manifest above.
- Do not hit the upstream source (https://earthquake.usgs.gov/fdsnws/event/1/) in bulk. This mirror exists so you do not have to.
- Do not read DuckLake internal data files with a plain Parquet reader. They come with
  positional delete files, and ignoring those silently returns deleted rows. Use the ducklake
  extension, or use the published exports above.
- Do not republish without the attribution line, and do not imply endorsement.