# USGS Earthquake API: Watch & Export Earthquakes by Region (`mouadapi/usgs-earthquakes`) Actor

Earthquakes from the USGS earthquake catalog (FDSN event API) by time window, magnitude and region, or only new and changed earthquakes since your last run. Never charged for failed or unchanged rows. Not affiliated with or endorsed by the USGS.

- **URL**: https://apify.com/mouadapi/usgs-earthquakes.md
- **Developed by:** [COMPASS DEV](https://apify.com/mouadapi) (community)
- **Categories:** News, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 earthquake returneds

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

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:

```json
{}
```

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):

```json
{ "stateName": "usgs-earthquakes" }
```

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

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

California (a rectangle) for September 2026:

```json
{ "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

```json
{
    "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`):

```bash
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}'
```

```javascript
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.

# Actor input Schema

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

Only earthquakes of at least this magnitude (USGS minmagnitude).

## `daysBack` (type: `integer`):

Earthquakes from the last N days (UTC dates). Ignored when a start date is given. Watch mode reads the same window and returns only new and changed earthquakes.

## `dateFrom` (type: `string`):

Optional start date, YYYY-MM-DD (UTC), e.g. 2026-09-01. Overrides the window.

## `dateTo` (type: `string`):

Optional end date, YYYY-MM-DD (UTC). Empty: up to now.

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

Rectangle: give all four edges (minLatitude, maxLatitude, minLongitude, maxLongitude). Not together with a circle.

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

Rectangle: northern edge, -90 to 90.

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

Rectangle: western edge, -360 to 360 (a rectangle may cross the date line).

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

Rectangle: eastern edge, -360 to 360.

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

Circle: give latitude, longitude and radius together. Not together with a rectangle.

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

Circle: centre longitude, -180 to 180.

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

Circle: radius in kilometres, up to 20001.6.

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

Optional: USGS event IDs to look up one by one (e.g. us6000tymj), besides the search. An ID the catalog doesn't have gives one free no\_data row.

## `mode` (type: `string`):

Empty: watch when a watch list name is given, otherwise export. "watch" returns only earthquakes that are new or changed since the last run of the watch list; "export" returns every earthquake. An explicit mode wins.

## `stateName` (type: `string`):

Name of your watch list (kept in your own storage between runs). Giving a name turns on watch mode. Watch mode without a name uses the list "default".

## `includeUnchanged` (type: `boolean`):

Watch mode: also return earthquakes that did not change, as free rows.

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

Most earthquakes returned and charged per run (at most 1,000). In watch mode the rest come in the next run.

## Actor input object example

```json
{
  "minMagnitude": 4.5,
  "daysBack": 7,
  "stateName": "usgs-earthquakes",
  "includeUnchanged": false,
  "maxItems": 100
}
```

# Actor output Schema

## `dataset` (type: `string`):

Dataset with one row per earthquake, or per entry when nothing is returned

## `runReport` (type: `string`):

Summary of the run (counts, charged and free rows, stop reason)

# 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 = {
    "stateName": "usgs-earthquakes"
};

// Run the Actor and wait for it to finish
const run = await client.actor("mouadapi/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 = { "stateName": "usgs-earthquakes" }

# Run the Actor and wait for it to finish
run = client.actor("mouadapi/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 '{
  "stateName": "usgs-earthquakes"
}' |
apify call mouadapi/usgs-earthquakes --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,mouadapi/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/36Y7pYfdlTVgen0Dq/builds/bNCxonOWyjXoznWE0/openapi.json