USGS Earthquakes
Earthquakes worldwide with location, depth and magnitude, from the USGS.
usgs_earthquakes — the dataset name to pass to the Obscura API.
What one row means
One row per distinct earthquake (or other seismic-network detection: quake, quarry blast, etc.) returned by USGS's FDSN GeoJSON event feed at or above the collector's configured minimum magnitude (default M4.5), holding that event's origin time, location, magnitude, and impact-assessment fields as of the most recent sync/upsert.
One row per (id).
Point-in-time availability
Every Obscura dataset carries available_date: the calendar day the publisher made the row
available, day-of, with no session rounding. It is the one column a backtest filters on, and it means the
same thing on every dataset in the catalog.
For usgs_earthquakes: published: available_date = detection date (event_time's UTC calendar date, first posted within minutes-to-an-hour of origin); magnitude/alert/felt may still revise on the same row afterward without advancing available_date.
Refresh cadence
Obscura refreshes usgs_earthquakes daily — the most frequent scheduled job that re-collects or re-exports it. This is Obscura's own pipeline cadence, not the upstream publisher's release schedule; when a row became public is recorded per row in available_date.
Schema — 24 columns
The full public column list for usgs_earthquakes, with the meaning of every field. The same
schema is served unauthenticated at https://api.obscura.trade/v1/catalog/usgs_earthquakes.
| Column | Type | Description |
|---|---|---|
| id | text · not null | USGS/ANSS unique event identifier and primary key, e.g. "us6000t9p3". The anti-join/upsert key that makes overlapping fetch windows idempotent instead of duplicating rows. |
| event_time | timestamp with time zone · not null | Earthquake origin time in UTC, parsed from GeoJSON properties.time (epoch millis). The actual seismic event moment, not when USGS published or last revised the row. |
| magnitude | double precision | Earthquake magnitude value on the scale named by mag_type. USGS revises this in place as review proceeds (preliminary -> reviewed -> final); no column records when a revision happened. |
| mag_type | text | Magnitude scale code for the magnitude value (e.g. "mb", "mww", "ml", "md"). Different scales are not directly comparable to each other. |
| place | text | USGS's auto-generated human-readable location description (e.g. "southeast of the Loyalty Islands"). A Flinn-Engdahl region name or distance/bearing offset; free text, not geocoded. |
| longitude | double precision | Epicenter longitude in decimal degrees (WGS84). |
| latitude | double precision | Epicenter latitude in decimal degrees (WGS84). |
| depth_km | double precision | Hypocenter (focal) depth below the surface in kilometers. Shallow vs. intermediate/deep events produce very different surface-shaking profiles at the same magnitude. |
| tsunami | boolean · not null | Tsunami-potential flag mapped from GeoJSON properties.tsunami (1/0). Indicates the event's location/magnitude fall in a class that COULD generate a tsunami, not a confirmation one occurred. |
| alert | text | PAGER alert level (green/yellow/orange/red), assigned from estimated fatalities/economic loss. Routinely null immediately after an event and populated/upgraded over the following minutes to hours. |
| felt | bigint | Cumulative count of "Did You Feel It?" (DYFI) citizen self-reports. Null/absent at first and climbs for days to weeks after the event as reports are submitted. |
| event_type | text | USGS event classification (observed value "earthquake" in this feed's queries; the underlying ANSS ComCat feed can also surface "quarry blast", "explosion", "ice quake", etc.). |
| url | text | Canonical USGS event page URL; the durable, human-navigable source reference for the row. |
| revised_at | timestamp with time zone | Source's own last-revision time in UTC, parsed from GeoJSON properties.updated (epoch millis). The moment USGS last modified this row (magnitude/alert/felt/status review); distinct from synced_at (our fetch time) and from event_time (the origin moment). |
| status | text | Solution review state from GeoJSON properties.status ("automatic" = preliminary auto-solution, "reviewed" = human-finalized). Distinguishes a machine-generated preliminary location from a seismologist-reviewed one. |
| mmi | double precision | Maximum estimated ShakeMap instrumental shaking intensity (Modified Mercalli), from GeoJSON properties.mmi. An impact/shaking measure at the epicenter distinct from magnitude and depth. |
| cdi | double precision | Maximum reported "Did You Feel It?" (DYFI) community-determined intensity (Modified Mercalli), from GeoJSON properties.cdi. A felt-shaking intensity measure distinct from felt (which is only a report count). |
| sig | bigint | USGS composite event significance score 0-1000 (blends magnitude, felt reports, and estimated impact), from GeoJSON properties.sig. A ready-made severity/ranking measure not derivable from our other columns. |
| nst | bigint | Number of seismic stations used in the location solution, from GeoJSON properties.nst. A solution-quality metric (more stations = better-constrained). |
| gap | double precision | Largest azimuthal gap between adjacent stations in degrees, from GeoJSON properties.gap. Epicenter-reliability measure: a gap > 180deg means the location is poorly constrained. |
| dmin | double precision | Horizontal distance from the epicenter to the nearest station in degrees, from GeoJSON properties.dmin. A location-quality metric (smaller = better-constrained depth/location). |
| rms | double precision | Root-mean-square travel-time residual in seconds, from GeoJSON properties.rms. Solution goodness-of-fit metric (lower = the observed arrival times fit the computed location better). |
| ids | text | Comma-delimited list of all contributing event ids across networks, from GeoJSON properties.ids (e.g. ",usauto7000t0u6,us7000t0u6,"). Cross-network identifier linkage for de-duping the same quake reported by multiple agencies. |
| available_date | date · not null | STORED generated column, event_time's UTC calendar date. PUBLIC-availability date for the row's existence — the day the earthquake occurred and was first posted to the feed; NOT bumped when magnitude/alert/felt are later revised. |
Access usgs_earthquakes
Two delivery paths, one identifier. Both require an Obscura account and an active subscription; the catalog entry and the schema above are public.
import obscura
client = obscura.Client("obs_live_…")
df = client.query(
dataset="usgs_earthquakes",
start="2024-01-01",
)Create a free account Browse all 95 datasets
Frequently asked questions
What is in the usgs_earthquakes dataset?
Earthquakes worldwide with location, depth and magnitude, from the USGS. One row per distinct earthquake (or other seismic-network detection: quake, quarry blast, etc.) returned by USGS's FDSN GeoJSON event feed at or above the collector's configured minimum magnitude (default M4.5), holding that event's origin time, location, magnitude, and impact-assessment fields as of the most recent sync/upsert.
How do I avoid look-ahead bias with usgs_earthquakes?
Filter on usgs_earthquakes.available_date, the day the publisher made the row public. For this dataset that date is derived as follows — published: available_date = detection date (event_time's UTC calendar date, first posted within minutes-to-an-hour of origin); magnitude/alert/felt may still revise on the same row afterward without advancing available_date. A query of the form WHERE available_date <= '<as-of date>' never sees a row before it existed.
In what formats can I get usgs_earthquakes?
As a Parquet bulk export (POST https://api.obscura.trade/v1/download) or as JSON from the typed query API (POST https://api.obscura.trade/v1/query), both with dataset="usgs_earthquakes". The column schema is public at https://api.obscura.trade/v1/catalog/usgs_earthquakes.
How often is usgs_earthquakes updated?
Obscura refreshes usgs_earthquakes on a daily schedule — that is the most frequent scheduled job that re-collects or re-exports the table. It is Obscura's own pipeline cadence, not the upstream publisher's release schedule; when the publisher makes a row available is described by the availability rule above, and is recorded per row in available_date.