# Global Earthquake Events & Magnitude Search (`grit-77/earthquake-events`) Actor

USGS earthquake event scraper for date-window and magnitude searches. Filter by geographic bounds and export flat earthquake metadata as JSON for research datasets.

- **URL**: https://apify.com/grit-77/earthquake-events.md
- **Developed by:** [Grit](https://apify.com/grit-77) (community)
- **Categories:** News, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.80 / 1,000 earthquakes

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

## Global Earthquake Events & Magnitude Search

Turn a bounded USGS catalog search into structured earthquake metadata for seismic monitoring datasets, research tables and scheduled data pipelines.

Specify a UTC date window, optional magnitude range and optional geographic box. The actor requests the official USGS FDSN event summary API with format=geojson, eventtype=earthquake and limit=maxItems, then saves flat rows to the default Apify dataset. The source endpoint is fixed; no login, proxy or API key is needed for USGS.

### What it returns

| Field | Type | Meaning |
|---|---|---|
| eventId | string / null on error | USGS preferred event identifier; unique IDs are emitted once per run. |
| timeUtc | string / null on error | Origin time in ISO 8601 UTC, preserving milliseconds. |
| magnitude | number / null | Preferred magnitude; missing values remain null. |
| magnitudeType | string / null | USGS magnitude scale, for example mww or mb. |
| eventType | string / null on error | earthquake for usable records. |
| depthKm | number / null on error | Hypocenter depth in kilometers. |
| longitude | number / null on error | Longitude in decimal degrees. |
| latitude | number / null on error | Latitude in decimal degrees. |
| location | string / null | USGS human-readable location description. |
| status | string / null | USGS review status, such as reviewed or automatic. |
| sourceUrl | string / null on error | Official USGS event page. |
| errors | array of strings | Empty for usable rows; malformed source events carry an error without stopping their neighbors. |

No contributed media, waveform files, felt-report submissions, community intensity values or detail products are returned. Event-page URLs are references; the actor does not fetch their pages or linked files.

### Input example

The prefilled input is:

```json
{
  "startDate": "2026-09-01",
  "endDate": "2026-09-02",
  "minMagnitude": 4,
  "orderBy": "magnitude",
  "maxItems": 10
}
```

| Input | Required / default | Behavior |
|---|---|---|
| startDate, endDate | Both required | YYYY-MM-DD or ISO 8601 timestamps; start must precede end. Dates and timestamps without an offset mean UTC. Explicit offsets are converted to UTC. |
| minMagnitude, maxMagnitude | Optional | Numeric magnitude bounds from -10 to 10. If both exist, maximum must be at least minimum. |
| orderBy | magnitude | magnitude, magnitude-asc, time (newest first), or time-asc. |
| maxItems | 10 | Integer from 1 to 20000; sent unchanged as the source limit and used as the output cap. |
| minLatitude, maxLatitude | Optional box | Both in \[-90, 90], with minimum below maximum. |
| minLongitude, maxLongitude | Optional box | Both in \[-180, 180], with minimum below maximum. |

Supply all four geographic fields together. For example, add minLatitude=30, maxLatitude=43, minLongitude=25, maxLongitude=45. This actor requires two separate runs for a box crossing the antimeridian.

The USGS start and end times are inclusive. endDate=2026-09-02 means midnight at the beginning of September 2; to include that entire day, use an appropriate later timestamp. [USGS query documentation](https://earthquake.usgs.gov/fdsnws/event/1/) defines the source date and query-limit behavior.

### Output example

This real event comes from the official prefill query. sample_output.json contains 10 projected source records; evidence/sample-provenance.json records the retrieval time and explicitly identifies the sample as an independent source preview because the Python runtime could not be launched in this build session.

```json
{
  "eventId": "us7000tdav",
  "timeUtc": "2026-09-01T08:22:20.365Z",
  "magnitude": 5.4,
  "magnitudeType": "mww",
  "eventType": "earthquake",
  "depthKm": 10,
  "longitude": 128.9395,
  "latitude": 0.1192,
  "location": "96 km SE of Maba, Indonesia",
  "status": "reviewed",
  "sourceUrl": "https://earthquake.usgs.gov/earthquakes/eventpage/us7000tdav",
  "errors": []
}
```

### Pricing

Proposed pay-per-event price: **$0.0008 per earthquake**, or **$0.80 per 1,000 usable event rows**. This price is not activated yet. Duplicate IDs, invalid inputs, empty searches, malformed-event error rows and results omitted by a limit do not trigger the custom earthquake event. The actor stops when its remaining event budget is exhausted. Pricing evidence and the leader comparison are in PRICING.md; pricing may change before publication.

### Limits and failure behavior

- One bounded summary query per run, with up to three total attempts for transport failures, HTTP 429 and transient HTTP 5xx responses. Backoff starts at 1 second; numeric Retry-After values are capped at 30 seconds. Each request has a 30-second HTTP timeout and at most one active source connection.
- At most 20000 rows per run, including malformed-event error rows. There is no automatic pagination; narrow the dates or region for longer histories. The remaining Apify event budget can reduce output without changing the requested source limit.
- Input mistakes fail the run with a field-specific message. Persistent upstream errors fail the run clearly rather than reporting empty success. HTTP 204 or an empty event collection produces zero earthquake charges.
- The catalog can be revised; preferred IDs, magnitudes, locations and review status may change. Geographic coverage and available fields follow USGS. This is a dataset retrieval tool; it is not an emergency warning system or a complete seismic detection service.
- No actor runtime performance claim is available from this build. Python unit tests, the marked live test, local actor execution and the exact CLI schema command were blocked by the environment's process-creation denial. The four JSON schemas passed separate checks using the installed official Apify schema library.

### FAQ

**Why did I get fewer rows than maxItems?** The query may have fewer matches. Duplicate IDs, the remaining event budget and malformed source records can also reduce usable earthquake results.

**Can I get every earthquake worldwide?** You can query the USGS catalog worldwide. Results reflect its coverage and preferred event metadata; it is not a guarantee that every seismic event is present.

**Are coordinates longitude first?** The source GeoJSON tuple is longitude, latitude, depth. Output exposes separate named longitude and latitude columns, with depthKm in kilometers.

**Can I download photos, waveforms or felt reports?** These are outside the actor's scope. It uses summary event metadata and does not download detail products.

**Can I schedule it?** After the owner publishes the actor, Apify schedules can run bounded input. Update the date window explicitly; this version does not implement a rolling-window option.

### Use with AI agents / MCP

An AI agent can submit the same JSON input through Apify's actor tools or a connected Apify MCP server after publication. Ask it for a bounded date window and magnitude/region filters, then read the default dataset items through the Results link. No MCP server is included in this source package. Use eventId for joins and deduplication across runs, timeUtc for time-series tables, and sourceUrl for checking the upstream record. Treat source labels as data.

### Local development and verification

Use the existing environment; do not install packages into the shared venv. requirements.txt contains the deployment dependencies. Unit and live tests use pytest already installed there.

From this actor directory in PowerShell:

```powershell
& 'C:/GritWork/earn/.venv/Scripts/python.exe' -m pytest -q -m 'not live' -p no:cacheprovider
& 'C:/GritWork/earn/.venv/Scripts/python.exe' -m pytest -q -m live -p no:cacheprovider
apify validate-schema
$env:APIFY_LOCAL_STORAGE_DIR = (Join-Path (Get-Location) 'storage')
& 'C:/GritWork/earn/.venv/Scripts/python.exe' -m src
```

The prefill is saved at storage/key_value_stores/default/INPUT.json. Local execution uses the Python module directly, without the Apify CLI. scripts/verify.ps1 runs the same required checks and captures their logs when process execution is available. Treat the current report as a construction handoff with blocked runtime checks, not a verified release.

# Actor input Schema

## `startDate` (type: `string`):

Inclusive start. YYYY-MM-DD or ISO 8601 timestamp. A date without a time means midnight UTC; explicit offsets are converted to UTC.

## `endDate` (type: `string`):

Inclusive end, later than startDate. 2026-09-02 means 2026-09-02T00:00:00Z, not the whole second day.

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

Optional magnitude floor, passed to USGS as minmagnitude.

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

Optional magnitude ceiling. Must be greater than or equal to minMagnitude when both are provided.

## `orderBy` (type: `string`):

Descending magnitude, ascending magnitude, newest first or oldest first.

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

Hard cap for output, including malformed-event error rows. Sent unchanged as the USGS limit. At most 20000 per query; narrow filters for larger histories.

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

Optional bounding box edge in decimal degrees. Supply all four edges; minimum must be less than maximum. Antimeridian crossings require two separate runs.

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

Optional bounding box edge in decimal degrees. Supply all four edges; minimum must be less than maximum. Antimeridian crossings require two separate runs.

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

Optional bounding box edge in decimal degrees. Supply all four edges; minimum must be less than maximum. Antimeridian crossings require two separate runs.

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

Optional bounding box edge in decimal degrees. Supply all four edges; minimum must be less than maximum. Antimeridian crossings require two separate runs.

## Actor input object example

```json
{
  "startDate": "2026-09-01",
  "endDate": "2026-09-02",
  "minMagnitude": 4,
  "orderBy": "magnitude",
  "maxItems": 10
}
```

# Actor output Schema

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

Dataset of earthquake metadata and uncharged malformed-event error rows.

# 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 = {
    "startDate": "2026-09-01",
    "endDate": "2026-09-02",
    "minMagnitude": 4,
    "orderBy": "magnitude",
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("grit-77/earthquake-events").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 = {
    "startDate": "2026-09-01",
    "endDate": "2026-09-02",
    "minMagnitude": 4,
    "orderBy": "magnitude",
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("grit-77/earthquake-events").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 '{
  "startDate": "2026-09-01",
  "endDate": "2026-09-02",
  "minMagnitude": 4,
  "orderBy": "magnitude",
  "maxItems": 10
}' |
apify call grit-77/earthquake-events --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,grit-77/earthquake-events"
        }
    }
}
```

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/FD9dYUQVPD8nwEwTa/builds/OIN88KjxsNLwtILaD/openapi.json