USGS Earthquake API: Watch & Export Earthquakes by Region

Returns earthquakes from the USGS earthquake catalog (the official FDSN event API) as flat rows by time window, magnitude and region, or in watch mode only the earthquakes that are new or changed since your last run. Never charged for failed or unchanged rows.

Choose a window (default: the last 7 days), a minimum magnitude (default 4.5) and optionally a rectangle or a point and radius; get one row per earthquake with its time, magnitude and magnitude type, place, latitude, longitude, depth, review status, tsunami flag, network and a link to the USGS event page. Built for dashboards, alerting, insurance and logistics teams, researchers and AI agents that need earthquake data without polling the USGS site. Not affiliated with or endorsed by the USGS.

What it does

• Export mode: every earthquake in the window, newest first, one flat row per earthquake.
• Watch mode (give a watch list name in stateName): remembers every earthquake and returns only:
  • baseline: the first run of the list;
  • new: an earthquake the list did not have;
  • changed: the USGS revised the magnitude, the magnitude type, the review status (automatic → reviewed) or the tsunami flag (changedFields and previousValues say what and from what);
  • deleted: the USGS deleted an earthquake on the list (one free no_data row; it leaves the list);
  • unchanged earthquakes are free and left out (includeUnchanged: true returns them as free rows).
  • A watch run with nothing new or changed returns exactly one free no_data row that says so.
• Event IDs: list USGS event IDs (eventIds) to look them up one by one besides the search. An ID the catalog doesn't have gives one free no_data row.
• You are never charged for failed results: failed, no_data and unchanged rows are free, and an earthquake is charged at most once per run.

Quick start

Earthquakes of magnitude 4.5 and above worldwide over the last 7 days:

{}

Watch for new and revised earthquakes (the first run is the baseline; later runs return only new and changed earthquakes; run it hourly or daily with an Apify schedule):

{ "stateName": "usgs-earthquakes" }

Magnitude 3 and above within 300 km of Tokyo over the last 30 days:

{ "latitude": 35.68, "longitude": 139.69, "radiusKm": 300, "minMagnitude": 3, "daysBack": 30 }

California (a rectangle) for September 2026:

{ "minLatitude": 32, "maxLatitude": 42, "minLongitude": -125, "maxLongitude": -114, "minMagnitude": 2.5, "dateFrom": "2026-09-01", "dateTo": "2026-10-01" }

Input

Field	Type	Default	Description
minMagnitude	number -1 to 10	4.5	Only earthquakes of at least this magnitude
daysBack	integer 1–3,650	7	The last N days (UTC dates); ignored when dateFrom is given
dateFrom	YYYY-MM-DD	—	Start date (UTC); overrides daysBack
dateTo	YYYY-MM-DD	—	End date (UTC); empty: up to now
minLatitude, maxLatitude, minLongitude, maxLongitude	numbers	—	A rectangle: give all four edges
latitude, longitude, radiusKm	numbers	—	A circle: give all three (radius up to 20,001.6 km). Not together with a rectangle
eventIds	list of strings	—	USGS event IDs to look up one by one, e.g. us6000tymj
mode	watch or export	—	Empty: watch when stateName is given, otherwise export. An explicit mode wins
stateName	string	— (prefilled usgs-earthquakes)	Watch list name. Watch mode without a name uses the list default
includeUnchanged	boolean	false	Watch: also return unchanged earthquakes (free)
maxItems	integer 1–1,000	100	Most charged earthquakes per run; in watch mode the rest come in the next run

Changing the window size, magnitude, region or event IDs of a watch list starts a new baseline; a rolling window (daysBack) moving forward each day does not.

Output

{
    "status": "ok",
    "attempts": 1,
    "error": null,
    "input": "M4.5+ worldwide, 2026-09-24 to now",
    "mode": "export",
    "watchList": null,
    "eventId": "us6000tymj",
    "time": "2026-09-30T21:55:26.169Z",
    "updated": "2026-09-30T23:21:11.426Z",
    "magnitude": 5.6,
    "magnitudeType": "mww",
    "place": "94 km SW of Tamarindo, Costa Rica",
    "placeOmitted": false,
    "latitude": 9.7526,
    "longitude": -86.5063,
    "depthKm": 8,
    "eventStatus": "reviewed",
    "tsunami": false,
    "network": "us",
    "changeType": null,
    "changedFields": null,
    "previousValues": null,
    "url": "https://earthquake.usgs.gov/earthquakes/eventpage/us6000tymj",
    "source": "USGS earthquake catalog (FDSN event web service). Data: U.S. Geological Survey (USGS) earthquake catalog, U.S. Public Domain.",
    "license": "U.S. Public Domain (USGS-authored data)",
    "licenseUrl": "https://www.usgs.gov/information-policies-and-instructions/copyrights-and-credits",
    "scrapedAt": "2026-10-01T12:00:00.000Z"
}

Status	Meaning	Charged?
ok	An earthquake returned	Export: yes. Watch: baseline, new and changed yes; unchanged no
no_data	No earthquake matches, an event ID the catalog doesn't have, an earthquake already returned above, one the USGS deleted, or nothing new since the last run	No
failed	Invalid input (e.g. not an event ID), or no answer after retries (error says why)	No

The key-value store holds RUN_REPORT (counts, charged and free rows, stop reason), in export mode the resume list PROGRESS (so a run Apify moves to another server charges nothing twice) and, when something fails, the raw response (SNAPSHOT_*).

Use it from AI agents

One clear call: {} returns the last 7 days of magnitude 4.5+ earthquakes worldwide; {"stateName": "<list>"} returns only new and changed earthquakes on later calls. Every row has status, error, url and scrapedAt. Call it through the Apify API, the Apify MCP server (mouadapi/usgs-earthquakes) or x402 agentic payments. Copy-paste call (your Apify token in APIFY_TOKEN):

curl -s -X POST "https://api.apify.com/v2/acts/mouadapi~usgs-earthquakes/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"minMagnitude": 5, "daysBack": 3}'

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('mouadapi/usgs-earthquakes').call({ minMagnitude: 5, daysBack: 3 });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Pricing

Pay per event: one earthquake event per returned earthquake (export: every earthquake; watch: baseline, new and changed rows). no_data, failed and unchanged rows are free.

Plan	Price per 1,000 earthquakes
Free	$1.50
Bronze	$1.30
Silver	$1.15
Gold (and higher)	$1.00

Apify also charges its small per-run start event. There are no usage fees on top.

Limits

• One request at a time, at most one a second: the USGS publishes no rate limit, so this Actor keeps well under any reasonable use. If the service answers HTTP 429, the run pauses 60, 120 and 240 seconds on the same connection, then stops with free failed rows. No other IP or proxy is ever tried.
• At most 1,000 earthquakes per run (maxItems), read 200 at a time; the USGS service itself caps a query at 20,000 events. For a longer history, split the window with dateFrom and dateTo.
• Magnitudes and locations of recent earthquakes are often revised in the first hours and days (automatic → reviewed); watch mode returns those revisions as changed rows.

Known issues

• The people filter: no field holds a person, but the place text is checked with the same person-name test as every name field in this portfolio. A place that reads like a person's name (for example a seafloor ridge named after a person, such as "West Chile Rise") is left out: place is null and placeOmitted is true; latitude and longitude stay, and the earthquake is returned and charged like any other. RUN_REPORT counts these (placesOmitted).

FAQ

Is this the official USGS feed? It reads the official USGS FDSN event web service (earthquake.usgs.gov) and returns the events as published, with a link to each event page.

Why did a watch run return one no_data row? Nothing was new or changed since the last run of the watch list; the row says how many earthquakes were unchanged. It is free.

What does tsunami: true mean? The USGS sets this flag for large events in oceanic regions. It does not mean a tsunami happened; check the official tsunami warning centres.

Data and licence

• Source: the USGS earthquake catalog through the FDSN event web service, documented at https://earthquake.usgs.gov/fdsnws/event/1/.
• Licence: USGS-authored or produced data and information are in the U.S. Public Domain (https://www.usgs.gov/information-policies-and-instructions/copyrights-and-credits). Every row names the source.
• This Actor is not affiliated with, endorsed by or provided by the USGS. It returns the events as published; it is not a warning system.