# Earthquakes

*Every magnitude 4.5+ event since 2000, where and how deep.*

The USGS earthquake catalog for events of magnitude 4.5 and above since 2000: time, location, depth, magnitude and type, the reporting network and the review status. One row per event. The whole table is replaced daily because the USGS revises magnitudes and locations for weeks after an event.

## At a glance

| | |
|---|---|
| Table | `pubdata.environment.earthquakes` |
| Category | Environment · Environment, Spatial, Time series |
| Rows | 187,658 |
| Size | 8.1 MB in 1 data file(s) |
| Iceberg format | v2 |
| Last refreshed | 2026-10-13T04:23:19Z |
| Source version | usgs fdsn 2026-10-13 |
| Refresh cadence | daily (replace) |
| Coverage | worldwide; 2000-01-01 to yesterday |

## Origin

- **Source:** [USGS Earthquake Hazards Program (FDSN event service)](https://earthquake.usgs.gov/fdsnws/event/1/)
- **Licence:** Public domain (US government work)
- **Attribution:** Earthquake catalog from the U.S. Geological Survey, Earthquake Hazards Program; public domain.
- **Recipe:** `pubdata/recipes/earthquakes.py` in the LakehouseBox repository; registry entry `pubdata/registry/earthquakes.yaml`.

## Schema

| column | type | description |
|---|---|---|
| `event_id` | string | the USGS event id, e.g. us7000tdrv |
| `event_time` | timestamptz | origin time (UTC) |
| `latitude` | double | epicentre latitude (WGS84) |
| `longitude` | double | epicentre longitude (WGS84) |
| `depth_km` | double | hypocentre depth in km |
| `magnitude` | double | the preferred magnitude |
| `magnitude_type` | string | mww, mb, ms, ml, ... |
| `place` | string | the USGS place description |
| `event_type` | string | always earthquake here (other event types are excluded) |
| `status` | string | reviewed or automatic |
| `network` | string | the contributing network code |
| `updated_at` | timestamptz | when the USGS last revised the event |

**Join keys:** `event_time`, `latitude`, `longitude`.

## For agents

Magnitude 4.5 is the floor; smaller events are not here. `status = 'automatic'` rows are recent and may still change.
Times are UTC; a "day" in a local sense needs a time zone conversion first. For a spatial join without an extension,
a degree box around each point (as in the example) is enough at country scale.

## Example SQL (DuckDB)

```sql
-- the strongest earthquake per year
SELECT year(event_time) AS year, max(magnitude) AS max_magnitude
FROM pubdata.environment.earthquakes GROUP BY 1 ORDER BY 1;
-- events within ~300 km of your sites in the last year
SELECT s.site_id, count(*) AS quakes, max(e.magnitude) AS strongest
FROM my.sites AS s JOIN pubdata.environment.earthquakes AS e
  ON abs(e.latitude - s.lat) < 2.7 AND abs(e.longitude - s.lon) < 2.7 / cos(radians(s.lat))
WHERE e.event_time >= now() - INTERVAL 1 YEAR
GROUP BY 1;
```

## How to read it

Without an account, over HTTPS (the bucket is public):

```sql
INSTALL iceberg; LOAD iceberg; INSTALL httpfs; LOAD httpfs;
-- anonymous: the bucket is public, requests go unsigned, through the public-data cache
CREATE OR REPLACE SECRET pubdata (TYPE S3, ENDPOINT 'lakehousebox-public-data.b-cdn.net', URL_STYLE 'path', REGION 'us-east-1');
CREATE OR REPLACE VIEW earthquakes AS SELECT * FROM iceberg_scan('s3://commons--pubdata/environment/earthquakes');
SELECT * FROM earthquakes LIMIT 10;
```

With a LakehouseBox account:

```bash
# with a LakehouseBox account (any organisation): the public catalog by name, read-only
lhbox duckdb --catalog commons/pubdata     # opens DuckDB attached as `commons_pubdata`
SELECT * FROM commons_pubdata.environment.earthquakes LIMIT 10;
```

Public URL of the table's storage: `https://s3.lakehousebox.com/commons--pubdata/environment/earthquakes/`. This card: `https://lakehousebox.com/pubdata/cards/earthquakes.md`; the page: https://lakehousebox.com/public-data/earthquakes. Every dataset as a table: `commons_pubdata.meta.datasets`; as Markdown: https://lakehousebox.com/public-data.md.