# USGS Earthquakes: Search Quakes by Magnitude, Area and Date (`yadroo/usgs-earthquakes`) Actor

One row per earthquake from the official USGS catalog: time, place, magnitude, depth, coordinates, PAGER alert, tsunami flag, felt reports and the event page. Filter by magnitude, time window, named region, radius, depth, alert level or event type; look events up by USGS id. UTC times.

- **URL**: https://apify.com/yadroo/usgs-earthquakes.md
- **Developed by:** [Samat Makatov](https://apify.com/yadroo) (community)
- **Categories:** News, AI, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.70 / 1,000 earthquake records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## USGS Earthquakes: Search Quakes by Magnitude, Area and Date

Every earthquake the U.S. Geological Survey publishes, as one dataset row: origin time and last revision in UTC, place, magnitude and magnitude type, depth, coordinates, PAGER alert level, tsunami flag, significance score, public felt reports, reported and instrumental shaking, kind of event, review status and the event page. Search a rolling window or a fixed period, filter by magnitude, depth, named region, radius around a point, alert level, felt reports or kind of event — or hand over USGS event ids and get one row each. The source is the public, keyless event web service of the USGS Earthquake Hazards Program over the ANSS catalog: no API key, no account, no browser, no proxy.

### Use cases

- **A newsroom's earthquake desk**: the magnitude 4.5 and above events of the last seven days worldwide, newest first, with felt reports and the PAGER alert, ready for a table or a map.
- **Insurance and facility risk**: everything that shook within 300 km of a plant, a pipeline or a building site, each row carrying its `distanceKm` from the point you gave — the "how close was it" answer without a GIS step.
- **A region watch on a schedule**: set `region` (or a radius) with `onlyNew` and a schedule; each run writes only the quakes that appeared since the last one. Add `trackRevisions` to get an event again when USGS revises its magnitude or depth.
- **Catastrophe and humanitarian teams**: the short PAGER list — only the few dozen events a year USGS gives an alert level, with its estimated-impact fields (`alert`, `mmi`, `cdi`, `significance`).
- **Claims and local reporting by what people felt**: filter on `minFeltReports` instead of magnitude and you get the events a city noticed, whatever the number on the scale said.
- **Agents and pipelines resolving an identifier**: a link or an alert mail gives you `us6000u18k`; put up to 100 such ids in `eventIds` and every one comes back as a row (unknown ids as `found: false`).
- **Research and back-testing**: a fixed `startTime`/`endTime` window with a depth or magnitude band, up to 2 000 rows a run.

### Input

Every field is optional. With an empty input the run returns the magnitude 2.5 and above earthquakes of the last week, newest first.

| Field | Type | Default | Allowed values / notes |
|---|---|---|---|
| `sinceHours` | integer | 168 | 1–8760. Rolling window on the origin time, UTC. Ignored when `startTime` is set. |
| `startTime` | string | empty | `YYYY-MM-DD` or a full timestamp (`2026-10-09T18:00:00`), read as UTC. Earliest origin time, inclusive. |
| `endTime` | string | empty | Same format. Latest origin time; empty means now. Used together with `startTime` — on its own it is ignored and the run says so. |
| `eventIds` | string\[] | empty | Up to 100 USGS event ids (`us6000u18k`). **When set, every filter below is ignored.** An id the catalog does not know gets one row with `found: false`. |
| `minMagnitude` | number | empty (prefill 2.5) | −2 to 10. Empty means every magnitude. |
| `maxMagnitude` | number | empty | −2 to 10. Combined with `minMagnitude` as a range. |
| `minDepthKm` | number | empty | −100 to 1000. Depth of the hypocentre in km; negative above sea level. |
| `maxDepthKm` | number | empty | −100 to 1000. |
| `eventTypes` | string\[] | empty | Forgiving free text, OR-combined. Case, spaces and underscores are ignored, aliases are accepted, anything else is refused with the closest values named. Values: [Kinds of event](#kinds-of-event). |
| `reviewStatus` | string | `all` | **Strict dropdown**: `all`, `reviewed`, `automatic`. An off-list value is refused by the platform before the run starts, with the allowed values named. |
| `region` | string\[] | empty | Forgiving free text, OR-combined: 34 named areas, each a bounding box. Case, spaces, diacritics and aliases accepted; anything else refused with a suggestion. List: [Named regions](#named-regions). |
| `latitude` | number | empty | −90 to 90. Centre point of a circle; needs `longitude`. Every row then carries `distanceKm`. |
| `longitude` | number | empty | −180 to 180. Needs `latitude`. |
| `radiusKm` | number | empty | 1–20000. Radius around the centre point. Without it the point narrows nothing and only adds `distanceKm`; without `latitude`/`longitude` it is ignored. |
| `minLatitude` | number | empty | −90 to 90. Rectangle search: **all four edges** are needed. Ignored when `region` is set. |
| `maxLatitude` | number | empty | −90 to 90. |
| `minLongitude` | number | empty | −360 to 360. For a box across the date line raise the east edge past 180 (e.g. 170 to 190). |
| `maxLongitude` | number | empty | −360 to 360. |
| `minAlertLevel` | string | empty | **Strict dropdown**: `green`, `yellow`, `orange`, `red`. Keeps only events with a PAGER alert at or above that level. An off-list value is refused by the platform before the run. |
| `onlyTsunamiFlagged` | boolean | `false` | Keep only events the catalog marks with a tsunami message. |
| `minFeltReports` | integer | empty | 1–200000. Minimum Did You Feel It responses. |
| `minSignificance` | integer | empty | 0–5000. Minimum `sig` score. |
| `onlyNew` | boolean | `false` | Remember the event ids this run writes and skip them next time (per actor or task). Made for schedules. |
| `trackRevisions` | boolean | `false` | Only with `onlyNew`: remember the event together with its revision time, so a revised event comes through again as a new row (and is charged again). |
| `sortBy` | string | `time` | **Strict dropdown**: `time` (newest first), `time-asc`, `magnitude` (largest first), `magnitude-asc`. Decides what a small `maxItems` keeps. |
| `maxItems` | integer | 50 | 1–2000. Hard cap on the rows a run writes, and so on what it costs. |
| `fields` | string\[] | all | Keep only these columns, **in this order**. `eventId`, `time`, `place`, `url`, `fetchedAt` and `found` are always kept — they come first, unless you name one of them here, which puts it exactly where you put it. Names that are not columns are listed in the run's status instead of being dropped in silence. Column names: [Output](#output). |

### Reference

#### Named regions

Each region is a rectangle in decimal degrees (south / north / west / east), checked against the catalog on 2026-10-09. A rectangle always reaches a little past the border it is named after, so a quake just across the line is included — use `latitude`/`longitude`/`radiusKm` or your own four edges when you need an exact area.

| Region | South | North | West | East | Also accepted |
|---|---|---|---|---|---|
| California | 32.0 | 42.5 | −125.0 | −114.0 | `ca`, `calif` |
| Southern California | 32.0 | 36.0 | −121.0 | −114.0 | `socal`, `s california` |
| Pacific Northwest | 41.0 | 49.5 | −125.5 | −116.0 | `pnw`, `cascadia` |
| Alaska | 51.0 | 72.0 | −170.0 | −129.0 | `ak` |
| Hawaii | 18.5 | 22.5 | −161.0 | −154.5 | `hi`, `big island` |
| Yellowstone | 43.5 | 45.2 | −111.5 | −109.7 | `yellowstone caldera` |
| Oklahoma | 33.6 | 37.1 | −103.1 | −94.4 | `ok` |
| Puerto Rico | 17.0 | 19.5 | −68.0 | −64.5 | `pr` |
| Mexico | 14.0 | 33.0 | −118.5 | −86.0 | `mx` |
| Central America | 7.0 | 18.5 | −93.0 | −77.0 | |
| Panama | 7.0 | 9.8 | −83.1 | −77.1 | |
| Caribbean | 9.0 | 23.0 | −88.0 | −58.0 | `antilles` |
| Chile | −56.0 | −17.0 | −76.0 | −66.0 | |
| Peru | −18.5 | 0.0 | −82.0 | −68.5 | |
| Japan | 24.0 | 46.0 | 128.0 | 146.5 | `jp`, `japan islands`, `nippon` |
| Taiwan | 21.5 | 25.5 | 119.5 | 122.5 | `tw` |
| Philippines | 4.5 | 21.0 | 116.0 | 127.0 | `ph` |
| Indonesia | −11.0 | 6.5 | 95.0 | 141.0 | `id`, `java`, `sumatra` |
| Papua New Guinea | −11.5 | −1.0 | 140.0 | 156.0 | `png` |
| New Zealand | −48.0 | −33.0 | 165.0 | 179.5 | `nz`, `aotearoa` |
| China | 18.0 | 54.0 | 73.0 | 135.0 | `cn` |
| India | 6.0 | 36.0 | 68.0 | 97.5 | `in` |
| Nepal | 26.3 | 30.5 | 80.0 | 88.3 | `np` |
| Himalaya | 26.0 | 36.0 | 73.0 | 97.0 | `himalayas` |
| Kazakhstan | 40.5 | 55.5 | 46.5 | 87.5 | `kz`, `qazaqstan` |
| Central Asia | 35.0 | 45.0 | 55.0 | 80.0 | `tien shan`, `pamir` |
| Kyrgyzstan | 39.0 | 43.4 | 69.0 | 80.3 | `kg`, `kyrgyz republic`, `kirgizia` |
| Caucasus | 38.0 | 45.0 | 38.0 | 50.0 | `caucasia` |
| Iran | 25.0 | 40.0 | 44.0 | 63.5 | `ir` |
| Turkey | 35.5 | 42.5 | 25.5 | 45.0 | `tr`, `türkiye`, `turkiye`, `anatolia` |
| Greece | 34.0 | 42.0 | 19.0 | 29.5 | `gr`, `aegean` |
| Italy | 36.5 | 47.2 | 6.5 | 18.6 | `it`, `italia` |
| Mediterranean | 30.0 | 46.0 | −6.0 | 36.0 | `med` |
| Iceland | 62.5 | 67.5 | −25.5 | −13.0 | `is` |

`region` is free text, so the platform cannot pre-check it: the run resolves what you typed. `California`, `california`, ` CALIFORNIA`, `Turkiye` and `türkiye` all work. Anything else ends the run at once with the closest names named ("Unknown region "Californa" (did you mean "California"?)"), never with a wider search than you asked for.

#### Kinds of event

The catalog is not only earthquakes: mining districts produce quarry blasts, glaciers produce ice quakes. Leave `eventTypes` empty for everything, or name the kinds you want. The catalog spells several of them two ways (`quarry blast` and `quarry_blast`); the run sends every spelling it knows for the kind you picked, so you get them all either way.

`earthquake` (aliases `eq`, `quake`) · `quarry blast` (`quarry`, `blast`) · `mining explosion` · `explosion` · `chemical explosion` · `nuclear explosion` (`nuclear test`) · `industrial explosion` · `accidental explosion` · `experimental explosion` · `collapse` · `mine collapse` · `building collapse` · `rock burst` · `landslide` · `rockslide` (`rock slide`) · `debris avalanche` · `snow avalanche` (`avalanche`) · `ice quake` (`icequake`, `cryoseism`) · `volcanic eruption` (`eruption`) · `volcanic explosion` · `sonic boom` (`sonicboom`) · `acoustic noise` · `meteorite` (`meteor`, `bolide`) · `induced or triggered event` (`induced`) · `train crash` · `other event` (`other`) · `not reported`

#### PAGER alert levels

PAGER is the USGS estimate of how bad an event was for people, computed from the shaking and the exposed population: `green` no significant losses expected, `yellow` local impact, `orange` a regional disaster, `red` a national one. Only a few dozen events a year get any alert at all, so `minAlertLevel` is the short list of quakes that hurt somebody. `minAlertLevel: "yellow"` keeps yellow, orange and red.

#### Review status

`automatic` is the solution a computer published within minutes of the event; `reviewed` is the record after a seismologist checked it, which can move the epicentre and change the magnitude by a few tenths. `reviewStatus: "all"` (the default) gives both, and every row carries its own `status`.

#### Magnitude types

`magnitudeType` says which scale the number comes from: `mww` and `mw*` moment magnitude (the standard for large events), `mb` body wave, `ms_20` surface wave, `ml`/`md` local and duration magnitudes used for small regional quakes, `mi`/`mwp` rapid estimates, `uk`/`Unknown` where the contributing network did not say. Magnitudes from different scales are close but not identical, which is one reason a fresh event's number keeps moving.

#### Shaking: MMI and CDI

Both are Modified Mercalli intensities, 1 to 10+. `mmi` is what ShakeMap computes from instruments and models for the worst-shaken place; `cdi` is the strongest intensity the public reported through Did You Feel It. Either can be missing, and they often differ.

### Examples

**This week's significant earthquakes worldwide (M4.5+)**

```json
{ "sinceHours": 168, "minMagnitude": 4.5, "maxItems": 15 }
```

**Everything within 300 km of central Tokyo in the last 90 days, with the distance per row**

```json
{ "latitude": 35.68, "longitude": 139.69, "radiusKm": 300, "sinceHours": 2160, "minMagnitude": 3.5, "maxItems": 15 }
```

**California over the last 30 days, largest first, four columns only**

```json
{ "region": ["California"], "sinceHours": 720, "minMagnitude": 2.5, "sortBy": "magnitude", "fields": ["magnitude", "place", "depthKm", "time"], "maxItems": 15 }
```

**The quakes people reported feeling, whatever their magnitude**

```json
{ "minFeltReports": 50, "sinceHours": 4320, "maxItems": 10 }
```

**The PAGER alert list of 2026, biggest first**

```json
{ "startTime": "2026-01-01", "minAlertLevel": "yellow", "sortBy": "magnitude", "maxItems": 10 }
```

**Three USGS event ids, resolved to rows**

```json
{ "eventIds": ["us6000u18k", "ci38457511", "official20110311054624120_30"] }
```

**A scheduled watch on Kazakhstan and Central Asia that only reports what is new**

```json
{ "region": ["Kazakhstan", "Central Asia"], "sinceHours": 24, "onlyNew": true, "trackRevisions": true, "maxItems": 100 }
```

### Output

One row per event. A real row from the cloud run `Z5tKlj689yVfZ9rZa` (an `eventIds` lookup of the M7.7 Panama earthquake of 9 October 2026):

```json
{
  "eventId": "us6000u18k",
  "time": "2026-10-09T17:56:06.036Z",
  "place": "12 km WSW of Pitaloza Arriba, Panama",
  "url": "https://earthquake.usgs.gov/earthquakes/eventpage/us6000u18k",
  "fetchedAt": "2026-10-09T20:54:45.331Z",
  "found": true,
  "updatedAt": "2026-10-09T20:49:31.001Z",
  "magnitude": 7.7,
  "magnitudeType": "mww",
  "title": "M 7.7 - 12 km WSW of Pitaloza Arriba, Panama",
  "latitude": 7.5868,
  "longitude": -80.769,
  "depthKm": 12.647,
  "distanceKm": null,
  "alert": "red",
  "tsunamiFlag": false,
  "significance": 2483,
  "feltReports": 568,
  "cdi": 8.5,
  "mmi": 8.714,
  "eventType": "earthquake",
  "status": "reviewed",
  "network": "us",
  "detailUrl": "https://earthquake.usgs.gov/fdsnws/event/1/query?eventid=us6000u18k&format=geojson"
}
```

| Field | Type | Meaning |
|---|---|---|
| `eventId` | string | The catalog's id, the last part of an event page link. Always present. |
| `found` | boolean | True for an event read from the catalog, false only on the marker row of an unknown `eventIds` value. Always present. |
| `time` | string | Origin time, ISO 8601 UTC. Null only on a `found: false` row. |
| `updatedAt` | string | When the catalog last changed the record, UTC. |
| `magnitude` | number | Size on the scale in `magnitudeType`. Null for a few entries without one. |
| `magnitudeType` | string | `mww`, `mb`, `ml`, … — see [Magnitude types](#magnitude-types). |
| `place` | string | The catalog's own description of the epicentre's location. |
| `title` | string | Magnitude and place in one line, as USGS writes it. |
| `latitude`, `longitude` | number | Epicentre in decimal degrees (north/east positive). |
| `depthKm` | number | Depth below the surface in km; can be slightly negative. |
| `distanceKm` | number | Great-circle km from the `latitude`/`longitude` in the input to the epicentre. Null when the run had no centre point. |
| `alert` | string | PAGER level `green`/`yellow`/`orange`/`red`; null for the vast majority of events. |
| `tsunamiFlag` | boolean | True when a tsunami message was issued for the event. |
| `significance` | number | USGS `sig` score from magnitude, shaking, felt reports and impact. |
| `feltReports` | number | Did You Feel It responses so far; null where nobody reported. |
| `cdi` | number | Strongest shaking the public reported (MMI scale); null without felt reports. |
| `mmi` | number | Strongest shaking ShakeMap estimates; null without a ShakeMap. |
| `eventType` | string | `earthquake` or one of the other [kinds](#kinds-of-event). |
| `status` | string | `reviewed` or `automatic`. |
| `network` | string | Contributing seismic network code (`us`, `ci`, `ak`, …). |
| `url` | string | The USGS event page. Always present. |
| `detailUrl` | string | Event web service link returning this one event with all its products. |
| `fetchedAt` | string | When the run read the catalog, UTC. Always present. |

Dataset views: **Earthquakes** (time, magnitude, place, depth, coordinates, alert, tsunami, felt reports, kind, link), **Shaking and impact** (alert, MMI, CDI, felt reports, significance, tsunami, solution, fetched), **Epicentres** (ids, coordinates, depth, distance, magnitude type, revision time, found).

A run also writes a `SUMMARY` record to its key-value store: what was searched, how many events matched the filters, how many rows were written, which ids were unknown, how many requests were made and why the run stopped.

### Use it from code / agents

```bash
curl -X POST "https://api.apify.com/v2/acts/yadroo~usgs-earthquakes/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sinceHours":168,"minMagnitude":4.5,"maxItems":15}'
```

```js
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('yadroo/usgs-earthquakes').call({
    latitude: 35.68, longitude: 139.69, radiusKm: 300, sinceHours: 2160, minMagnitude: 3.5, maxItems: 15,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

```python
from apify_client import ApifyClient
client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("yadroo/usgs-earthquakes").call(run_input={
    "eventIds": ["us6000u18k", "ci38457511"], "fields": ["magnitude", "place", "alert", "mmi"]
})
items = client.dataset(run["defaultDatasetId"]).list_items().items
```

MCP: add `https://mcp.apify.com` to Claude, Cursor or any MCP client and call the `yadroo/usgs-earthquakes` tool with the same JSON input. Agents see the field descriptions of the input schema, so `region`, `eventIds` and `fields` are usable without reading this page — and `fields` keeps the payload small, which matters when the answer goes into a context window.

### Pricing

Pay per event: **$0.001 per run start + $0.001 per earthquake row**. Both are charged on the actor's free tier; Apify's plan discounts apply to the row event automatically (Bronze $0.0009, Silver $0.0008, Gold and above $0.0007).

| Run | Rows | Cost |
|---|---|---|
| This week's M4.5+ events | 15 | 0.001 + 15 × 0.001 = **$0.016** |
| The default run (M2.5+, last week) | 50 | 0.001 + 50 × 0.001 = **$0.051** |
| A 100-id lookup | 100 | 0.001 + 100 × 0.001 = **$0.101** |
| The largest run the schema allows | 2000 | 0.001 + 2000 × 0.001 = **$2.001** |

Every run is charged the start event, also a run that finds nothing. Every row written to the dataset is charged, including the `found: false` marker row of an `eventIds` value the catalog does not know — it is an answer, and the run says so in its status. `maxItems` is the hard cap on rows and so on cost; on top of it, Apify's **Maximum cost per run** stops the run when the budget is used up, keeping (and charging) only the rows already paid for and saying so in the run status: "Stopped at your spending limit: 3 rows delivered."

### Limits & FAQ

**Measured speed (2026-10-09, Apify cloud, 256 MB).** A search run makes one counting request per area plus one request per 1 000 events, paced one request per second. Measured: the default run (50 rows, magnitude 2.5+, last week) took 5 s with 2 requests; the widest search the schema allows returned **1 345 rows in 12 s with 3 requests** (magnitude 1+ worldwide for a week, `maxItems` 2000) — about 110 rows a second once a page arrives, and roughly 15 requests a minute at the actor's own pace. No HTTP 429 and no `Retry-After` was seen in any run. An `eventIds` lookup is the slow job, because each id is one request: about **1 id a second**, so 100 ids need around 100 s. Everything the schema allows fits comfortably into the default run timeout of 900 s.

**Rate limits.** USGS publishes no request limit and no quota for this service (checked 2026-10-09), so this actor sets its own polite pace: one request per second per host, retries included, with exponential backoff and `Retry-After` honoured on HTTP 429 and 5xx. There is no robots.txt on the host (it answers 404), so there is no `Crawl-delay` to follow. A bigger run does not go faster — it just uses more one-second-apart requests.

**The run stops before it is killed.** If the clock or your spending limit runs out, the run ends successfully with the rows it has and says so in its status ("Stopped before the run timeout: N rows saved", "Stopped at your spending limit: N rows delivered") instead of being cut off without a word.

**One query hands out at most 20 000 events.** That is the service's own limit. The actor's `maxItems` goes to 2 000, so it never runs into it; when your filters match more than 20 000 events the run says so in the status and returns the newest (or largest, with `sortBy: "magnitude"`) ones first. Narrow the window for the rest.

**Magnitudes and epicentres change.** A new event is published automatically within minutes and revised for hours or days: magnitude, depth, epicentre, alert level and felt count all move. `status` tells you whether a record is `reviewed` or still `automatic`, `updatedAt` when it last changed. A schedule with `onlyNew` alone delivers each event once, as first seen; add `trackRevisions` to receive it again with its corrected numbers (a new row, charged as a row).

**Impact fields are rare.** `alert` (PAGER) exists for a few dozen events a year. `mmi` needs a ShakeMap, `cdi` and `feltReports` need public reports, and almost no event before about 2010 has any of them. The tsunami flag means a message was issued, not that a wave arrived, and is empty for most older events.

**Felt reports are US-heavy and keep growing.** Did You Feel It is well known in the United States and little known elsewhere, so a Californian M3 can have more reports than a much larger quake abroad, and a count read an hour after an event is lower than the final one.

**Detection is not uniform.** The dense U.S. networks catalog quakes down to magnitude 0, while most of the world is complete only from about magnitude 4.5. Counting small quakes across regions therefore compares network density, not seismicity.

**It is a catalog, not a warning system.** No forecasts, no casualty figures, no building-level damage, no waveform data, and no alerting: a run reads what the catalog holds at that moment. For the non-earthquake entries (quarry blasts, explosions, ice quakes, landslides) use `eventTypes`; leave it empty and they are included.

**Empty is a valid answer.** Narrow filters — orange alerts in one month, M5+ in a quiet region — legitimately match nothing. The run then succeeds with zero rows and says "the filters matched nothing in that window", while a filter value it cannot resolve (a misspelled `region`) fails the run immediately with the closest values named.

**The service can be slow exactly when you need it.** USGS is busiest right after a large earthquake. The actor retries with backoff and, if it still cannot read, ends with a clear error instead of hammering the service.

**Questions or problems:** open an issue on the Issues tab of this actor.

***

Made by **Yadroo**. Sibling actors: [nasa-eonet-events](https://apify.com/yadroo/nasa-eonet-events), [nasa-asteroid-approaches](https://apify.com/yadroo/nasa-asteroid-approaches), [open-meteo-weather](https://apify.com/yadroo/open-meteo-weather), [osm-geocode](https://apify.com/yadroo/osm-geocode), [public-holidays](https://apify.com/yadroo/public-holidays).

# Actor input Schema

## `sinceHours` (type: `integer`):

Rolling window on the origin time of the earthquake, counted in UTC: 1 is the last hour, 24 a day, 168 a week, 720 roughly a month, 8760 a year. Ignored when `startTime` is set. Small quakes are added to the catalog within minutes and reviewed later, so a one-hour window holds mostly automatic solutions.

## `startTime` (type: `string`):

Earliest origin time, inclusive, UTC. Set it for a fixed historical window instead of the rolling `sinceHours`; a full timestamp such as `2026-10-09T18:00:00` is accepted too. The catalog reaches back to the 19th century for large events, but complete global coverage of moderate quakes starts in the 1970s.

## `endTime` (type: `string`):

Latest origin time, inclusive, UTC. Empty means now. Used together with `startTime`; on its own it is ignored.

## `eventIds` (type: `array`):

Look specific events up instead of searching, up to 100 per run: `us6000u18k`, `ci38457511`, `official20110311054624120_30`. The id is the last part of a USGS event page link (`/earthquakes/eventpage/<id>`), which is what a news story or an alert mail usually gives you. When this list is set, every filter below is ignored. An id the catalog does not know gets one row with `found: false` instead of failing the run.

## `minMagnitude` (type: `number`):

Keep quakes at or above this magnitude. Empty means every magnitude, including the thousands of tiny events the dense U.S. networks record every week - with a short `maxItems` that gives you the newest events of any size. Useful steps: 2.5 is what people in the area may notice, 4.5 the global reporting threshold outside the U.S., 6 damaging, 7 major.

## `maxMagnitude` (type: `number`):

Keep quakes at or below this magnitude, combined with `minMagnitude` as a range - for example 2.5 to 4 for events felt locally but harmless.

## `minDepthKm` (type: `number`):

Keep quakes whose hypocentre is at least this deep. Depth is measured in kilometres below the surface and can be slightly negative for events located above sea level. Deep events (over 300 km) sit inside subducting plates and are felt far away but rarely damaging.

## `maxDepthKm` (type: `number`):

Keep quakes no deeper than this, for example 30 for the shallow crustal events that do the damage. Many small catalog entries carry a fixed default depth (0, 5 or 10 km) because the networks could not resolve it.

## `eventTypes` (type: `array`):

Keep only these kinds of event, combined with OR. Empty means every kind, which is why a mining district can return blasts next to earthquakes. Case, spaces and underscores are ignored and a value the catalog does not use is refused with the closest ones named. Values in use: `earthquake`, `quarry blast`, `mining explosion`, `explosion`, `chemical explosion`, `nuclear explosion`, `collapse`, `mine collapse`, `rock burst`, `landslide`, `rockslide`, `debris avalanche`, `snow avalanche`, `ice quake`, `volcanic eruption`, `volcanic explosion`, `sonic boom`, `acoustic noise`, `meteorite`, `induced or triggered event`, `other event`. Full list in the README reference.

## `reviewStatus` (type: `string`):

A new event is published automatically within minutes and a seismologist revises it later, which can move the epicentre and change the magnitude by a few tenths. `reviewed` gives you the stable record and loses the newest events; `automatic` is the opposite. Every row carries its own `status` whichever you pick.

## `region` (type: `array`):

Search inside one or more named regions, combined with OR - no coordinates needed. Case, spaces and common spellings are accepted (`California`, `new zealand`, `Turkiye`) and anything else is refused with the closest names listed, so a typo never turns into a silently wider search. Known regions: California, Southern California, Pacific Northwest, Alaska, Hawaii, Yellowstone, Oklahoma, Puerto Rico, Mexico, Central America, Panama, Caribbean, Chile, Peru, Japan, Taiwan, Philippines, Indonesia, Papua New Guinea, New Zealand, China, India, Nepal, Himalaya, Kazakhstan, Central Asia, Kyrgyzstan, Caucasus, Iran, Turkey, Greece, Italy, Mediterranean, Iceland. Each one is a bounding box, listed with its corners in the README reference. For anything else use the box or radius fields below.

## `latitude` (type: `number`):

Latitude of the point to search around, in decimal degrees, north positive. Use it with `longitude` and `radiusKm` for a circle - for a city, a plant, a pipeline or a building site. Every row then also carries `distanceKm`, the great-circle distance from this point to the epicentre.

## `longitude` (type: `number`):

Longitude of the centre point, in decimal degrees, east positive (so -80.77 for Panama, 139.69 for Tokyo, 76.89 for Almaty).

## `radiusKm` (type: `number`):

Radius of the circle around the centre point, in kilometres. 100 to 300 is a city and its faults, 500 covers a region. Ignored without `latitude` and `longitude`.

## `minLatitude` (type: `number`):

Rectangle search instead of a circle: southern edge in decimal degrees. All four edges are needed; `region` is the ready-made version of this. A box that crosses the date line is passed to the source as given, which accepts longitudes beyond 180.

## `maxLatitude` (type: `number`):

Northern edge of the rectangle, in decimal degrees.

## `minLongitude` (type: `number`):

Western edge of the rectangle, in decimal degrees.

## `maxLongitude` (type: `number`):

Eastern edge of the rectangle, in decimal degrees.

## `minAlertLevel` (type: `string`):

Keep only quakes USGS gave a PAGER alert, which estimates deaths and economic loss from shaking and the exposed population. Only a few dozen events a year get one, so this is the short list of quakes that actually hurt somebody. Empty means no filter; rows carry the level in `alert`, null for the vast majority.

## `onlyTsunamiFlagged` (type: `boolean`):

Keep only events the catalog marks as having had a tsunami message from the regional warning centres. The flag is set for large quakes in oceanic regions and says a message went out, not that a wave was observed or that damage happened - and it is empty for most events older than about 2010.

## `minFeltReports` (type: `integer`):

Keep quakes with at least this many Did You Feel It responses from the public (`feltReports`). 10 means somebody noticed, several hundred means a city did. This is a crowd-sourced count that grows for hours after the event and is far higher in the U.S. than elsewhere, because that is where the form is known.

## `minSignificance` (type: `integer`):

Keep quakes with at least this significance (`sig`), the score USGS computes from magnitude, shaking, felt reports and estimated impact to decide what goes on its significant-events list. 600 and up is roughly that list; 1000 and up are the headline events of a year.

## `onlyNew` (type: `boolean`):

Remember every event id this run writes in the actor's key-value store and, next time the same actor or task runs, write only events that were not written before. Made for a schedule: each run then holds the quakes that appeared since the last one. The memory is kept per actor or task, so two tasks watching two regions do not interfere.

## `trackRevisions` (type: `boolean`):

Only matters with `onlyNew`. A fresh quake is published within minutes as an automatic solution and then revised - magnitude, depth, epicentre, alert level and felt count all move for hours or days. With this on, the memory remembers the event id together with its revision time, so a revised event comes through again as a new row with its current numbers (and is charged again); with it off, you get each event once, as it looked when first seen.

## `sortBy` (type: `string`):

How the source orders the events before `maxItems` cuts the list. With a small cap this decides what you get: `time` the newest quakes, `magnitude` the biggest ones of the window.

## `maxItems` (type: `integer`):

Hard cap on the rows this run writes, and so on what it costs. The source answers at most 20000 events per query, which the actor pages through 1000 at a time; a window wider than that is reported in the run status instead of being silently cut. The run also stops at the maximum cost per run you set on the platform.

## `fields` (type: `array`):

Keep only the named columns, in the order given - for example `magnitude, place, depthKm, alert`. Empty = every column. `eventId`, `time`, `place`, `url`, `fetchedAt` and `found` are always present; name one of them here and it moves to the position you gave it. Unknown names are reported in the run's status message instead of being dropped in silence.

## Actor input object example

```json
{
  "sinceHours": 168,
  "minMagnitude": 2.5,
  "reviewStatus": "all",
  "onlyTsunamiFlagged": false,
  "onlyNew": false,
  "trackRevisions": false,
  "sortBy": "time",
  "maxItems": 50
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "minMagnitude": 2.5
};

// Run the Actor and wait for it to finish
const run = await client.actor("yadroo/usgs-earthquakes").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "minMagnitude": 2.5 }

# Run the Actor and wait for it to finish
run = client.actor("yadroo/usgs-earthquakes").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "minMagnitude": 2.5
}' |
apify call yadroo/usgs-earthquakes --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,yadroo/usgs-earthquakes"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Cf0gbcKeTA5lFIPFt/builds/Ne9AnNVi21ypPvpeU/openapi.json