# USGS Earthquake Delta Monitor (`apex-nexus/usgs-earthquake-delta-monitor`) Actor

- **URL**: https://apify.com/apex-nexus/usgs-earthquake-delta-monitor.md
- **Developed by:** [Valunex](https://apify.com/apex-nexus) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 earthquake alerts

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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 Earthquake Delta Monitor

Watchlist-based delta monitor of the USGS FDSN Earthquake Event Service: get
alerted only when *new* earthquakes matching your magnitude / place / region
watchlist occur since the last run — "free when nothing changes", pay only on
signal. Built on public USGS data (no API key, no signup, no credentials, no
proxies).

### What it does

The Actor polls the official, public USGS FDSN Earthquake Event Service
(https://earthquake.usgs.gov/fdsnws/event/1/query) for earthquakes in a date
window you choose (default: the last 7 days, magnitude >= 2.5, worldwide) and
emits one dataset item per newly observed earthquake matching your watchlist:

- New earthquakes matching a watchlist entry (min magnitude / place / region)
  → one dataset item per event, tagged `newSinceLastRun: true`
- Nothing changed since the last run → no dataset items at all (free when nothing changes)

State is checkpointed per watchlist item in the Actor default key-value store,
so repeat runs only surface genuinely new earthquakes.

### Search terms this Actor answers

- USGS earthquake monitor
- earthquake alert watchlist
- seismic activity tracker
- USGS FDSN earthquake API
- earthquake delta monitor
- recent earthquakes watchlist

### Who it is for

Property insurers and cat-risk desks, emergency-management contractors,
commercial property and asset owners, and news desks covering natural disasters.
Early earthquake signal has direct loss-mitigation value and is typically bought
from insurance risk and operations budgets or emergency-management service
contracts.

### Data source

Public US government data, keyless, no login, no proxies:

https://earthquake.usgs.gov/fdsnws/event/1/

This Actor queries
`https://earthquake.usgs.gov/fdsnws/event/1/query?format=geojson&starttime=...&endtime=...&minmagnitude=...&limit=...`
(server-side min magnitude, optional place / regioncode filters) with
deterministic client-side re-checking of the magnitude / place / region filters.
No LLMs, no commercial inference, no credentials, no proxies inside the product.

### Input

See `actor/.actor/input_schema.json`.

- `watchlist` (array of objects, optional, default `[]`): each entry is
  `{minMag, place, region}`. `place` is a case-insensitive substring matched
  against the USGS place description; `region` is either a numeric
  Flinn-Engdahl region code (sent to USGS server-side) or a substring matched
  against the place description. Leave empty to monitor every earthquake
  worldwide at the top-level min magnitude. One checkpoint is kept per entry.
- `sinceDays` (integer, 1-365, default 7): how far back to look on the first
  run; repeat runs only emit events newer than the last checked state.
- `minMag` (number, >= 0, default 2.5): default minimum magnitude applied to
  watchlist entries that do not set their own.
- `maxResults` (integer, 1-200, default 25): cap of new earthquake alerts per run.

Example input:

```json
{
  "watchlist": [
    { "minMag": 4.5, "place": "California" },
    { "minMag": 5.0, "region": "51" }
  ],
  "sinceDays": 7,
  "maxResults": 25
}
```

### Output

One dataset item per newly observed earthquake matching a watchlist entry since
the last run (see `actor/.actor/dataset_schema.json`), including event id,
time, magnitude, place, coordinates, depth, alert level, significance, network,
matched watchlist entry, and the USGS source link.

### Pricing

Published as a pay-per-event Apify Store listing: $0.0001 per Actor start +
$0.005 per alert (earthquake-change event). Unchanged replays emit nothing, so
runs with no new earthquakes are free.

### Verification

- `pytest actor/tests` — deterministic tests, no network (fakes httpx responses
  and the Apify default key-value store)
- `ruff check actor/` — 0 errors
- Default input returns >0 dataset items against the live USGS FDSN API in
  under 5 minutes (evidenced by a real Apify run of the pushed build)

### Distinctness

USGS seismic-events delta monitoring — distinct from the other apex-nexus
Actors (SEC filings, FDA/NHTSA/FSIS/CPSC recalls, CFPB complaints, state
campaign finance, USDA/BLS economic reports, NWS weather alerts, Federal
Register). No Apify Store listing is a USGS earthquake delta watchlist monitor;
incumbents are one-shot pay-per-event search scrapers with no checkpoint and no
"free when nothing changes" behavior.

# Actor input Schema

## `watchlist` (type: `array`):

Each entry filters new earthquakes by min magnitude, place (substring) and/or region. An entry is an object { "minMag": <number>, "place": <string>, "region": <string> }; place is matched case-insensitively against the USGS place description, region is either a numeric Flinn-Engdahl code (sent server-side) or a place substring. Leave empty to monitor every earthquake worldwide at the top-level min magnitude. One checkpoint is kept per entry so repeat runs emit only new events.

## `sinceDays` (type: `integer`):

How far back to look for earthquakes on the first run; repeat runs only emit events newer than the last checked state.

## `minMag` (type: `number`):

Default minimum magnitude applied to watchlist entries that do not set their own minMag.

## `maxResults` (type: `integer`):

Cap the number of new earthquake alerts emitted in a single run.

## Actor input object example

```json
{
  "watchlist": [],
  "sinceDays": 7,
  "minMag": 2.5,
  "maxResults": 25
}
```

# Actor output Schema

## `overview` (type: `string`):

Dataset items filtered by the overview view defined in the dataset schema.

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

All dataset items emitted by the Actor run (newly detected earthquakes).

# 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 = {
    "watchlist": [],
    "sinceDays": 7,
    "minMag": 2.5,
    "maxResults": 25
};

// Run the Actor and wait for it to finish
const run = await client.actor("apex-nexus/usgs-earthquake-delta-monitor").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 = {
    "watchlist": [],
    "sinceDays": 7,
    "minMag": 2.5,
    "maxResults": 25,
}

# Run the Actor and wait for it to finish
run = client.actor("apex-nexus/usgs-earthquake-delta-monitor").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 '{
  "watchlist": [],
  "sinceDays": 7,
  "minMag": 2.5,
  "maxResults": 25
}' |
apify call apex-nexus/usgs-earthquake-delta-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,apex-nexus/usgs-earthquake-delta-monitor"
        }
    }
}
```

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/7Hr4ALP256S2lZZXA/builds/YYQMUrOd1NXqqsepe/openapi.json