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:

{
  "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 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.

{
  "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:

& '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.