# USGS Earthquake Data Scraper (`crawlerbros/usgs-earthquake-scraper`) Actor Fetch real-time and historical earthquake data from the USGS Earthquake Hazards Program. Filter by magnitude, date range, depth, geographic bounding box, or radius. No API key required. - **URL**: https://apify.com/crawlerbros/usgs-earthquake-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Automation, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. Actors are written with capital "A". ## 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. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## USGS Earthquake Data Scraper Fetch real-time and historical earthquake and seismic event data from the **USGS Earthquake Hazards Program** — the authoritative public source for global earthquake data. No API key or subscription required. ### What you get Each record represents one earthquake event and includes: | Field | Description | |---|---| | `event_id` | USGS event ID (e.g. `us6000m1n2`) | | `magnitude` | Richter/moment magnitude | | `magnitude_type` | Scale used: `mw`, `ml`, `mb`, `ms`, etc. | | `place` | Human-readable location description | | `time` | ISO 8601 UTC datetime of the event | | `updated` | ISO 8601 UTC datetime of last catalog update | | `latitude` | Epicenter latitude | | `longitude` | Epicenter longitude | | `depth_km` | Depth below surface in kilometres | | `alert` | PAGER alert level: `green`, `yellow`, `orange`, or `red` | | `tsunami` | `1` if a tsunami message was issued, `0` otherwise | | `significance` | USGS significance score 0–1000 | | `felt_reports` | Number of "Did You Feel It?" reports submitted | | `url` | USGS event detail page URL | | `status` | `automatic`, `reviewed`, or `deleted` | | `network` | Reporting seismic network code (e.g. `us`, `ci`, `nc`) | | `scraped_at` | ISO 8601 UTC datetime this record was scraped | ### Modes #### `recentEarthquakes` (default) Returns earthquakes filtered by magnitude and date range. Ideal for monitoring ongoing seismic activity globally. **Example use case:** Get all magnitude 5.0+ earthquakes since the start of 2024. #### `searchEarthquakes` Same as `recentEarthquakes` but with full support for geographic bounding boxes and depth filters. Use this when you need earthquakes in a specific region. **Example use case:** Get all earthquakes in the contiguous US (lat 24–49, lon –125 to –66) at shallow depth (0–70 km) in the last 6 months. ### Input parameters | Parameter | Type | Default | Description | |---|---|---|---| | `mode` | select | `recentEarthquakes` | Fetch mode | | `minMagnitude` | number | `4.5` | Minimum Richter magnitude | | `maxMagnitude` | number | — | Maximum magnitude (optional upper bound) | | `startTime` | string | `2024-01-01` | Start date (ISO 8601, e.g. `2024-01-01`) | | `endTime` | string | today | End date (leave blank for today) | | `minDepth` | number | — | Minimum depth in km (can be negative) | | `maxDepth` | number | — | Maximum depth in km | | `minLatitude` | number | — | Southern bounding box limit (–90 to 90) | | `maxLatitude` | number | — | Northern bounding box limit (–90 to 90) | | `minLongitude` | number | — | Western bounding box limit (–360 to 360) | | `maxLongitude` | number | — | Eastern bounding box limit (–360 to 360) | | `orderBy` | select | `time` | Sort order: newest/oldest/largest/smallest first | | `maxItems` | integer | `100` | Maximum records to return (up to 20 000) | ### Example inputs #### Global M4.5+ earthquakes in 2024 ```json { "mode": "recentEarthquakes", "minMagnitude": 4.5, "startTime": "2024-01-01", "maxItems": 500 } ```` #### Significant earthquakes in Japan ```json { "mode": "searchEarthquakes", "minMagnitude": 3.0, "startTime": "2024-01-01", "minLatitude": 30, "maxLatitude": 46, "minLongitude": 129, "maxLongitude": 146, "orderBy": "magnitude", "maxItems": 200 } ``` #### All deep-focus earthquakes globally ```json { "mode": "searchEarthquakes", "minMagnitude": 4.0, "startTime": "2023-01-01", "minDepth": 300, "maxItems": 1000 } ``` #### Recent shallow California earthquakes ```json { "mode": "searchEarthquakes", "minMagnitude": 2.0, "startTime": "2024-06-01", "minLatitude": 32, "maxLatitude": 42, "minLongitude": -124, "maxLongitude": -114, "maxDepth": 30, "orderBy": "time", "maxItems": 500 } ``` ### Data source All data comes from the **USGS Earthquake Hazards Program** public API at `https://earthquake.usgs.gov/fdsnws/event/1/`. This is a free, open government data source — no API key, account, or payment required. Data is updated in real time as seismic events are recorded and reviewed by USGS seismologists worldwide. ### Use cases - **Natural disaster monitoring** — track earthquake activity in specific regions - **Research & analysis** — build datasets of historical seismic events for academic study - **Alerting systems** — feed earthquake data into notification pipelines - **GIS mapping** — plot epicenters and depths on maps using latitude/longitude fields - **Insurance & risk modeling** — assess seismic risk for geographic regions ### Frequently asked questions **How fresh is the data?** The USGS API returns near-real-time data. Automatic (unreviewed) detections appear within minutes; reviewed records may lag by hours to days. **What is the maximum number of results?** The USGS API supports up to 20 000 records per query. Set `maxItems` up to `20000`. For larger datasets, run multiple queries with different date ranges. **What does the `significance` field mean?** Significance is a USGS-computed score (0–1000) that combines magnitude, number of felt reports, and estimated impact. Higher = more significant to people. **What does the `alert` field mean?** The PAGER alert level estimates potential casualties and economic losses: `green` (little/no impact), `yellow` (some impact), `orange` (significant), `red` (catastrophic). **Can I filter by a circular area around a point?** The underlying USGS API supports radius-based queries, but this actor uses the geographic bounding-box approach for simplicity. Use `minLatitude`/`maxLatitude`/`minLongitude`/`maxLongitude` to define your area. **Are tsunami events included?** Yes. The `tsunami` field is `1` whenever USGS issued a tsunami message for that event. **Do I need an API key?** No. The USGS Earthquake Hazards API is completely free and open — no registration or API key required. # Actor input Schema ## `mode` (type: `string`): Choose what to fetch. recentEarthquakes uses your magnitude/limit filters. searchEarthquakes adds explicit date range and geographic filters. ## `minMagnitude` (type: `number`): Only return earthquakes at or above this Richter magnitude. Default is 4.5. ## `maxMagnitude` (type: `number`): Only return earthquakes at or below this magnitude. Leave blank for no upper limit. ## `startTime` (type: `string`): Return earthquakes on or after this date/time. Format: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS. Default: 2024-01-01. ## `endTime` (type: `string`): Return earthquakes on or before this date/time. Format: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS. Leave blank to use today. ## `minDepth` (type: `number`): Only return earthquakes deeper than this depth in kilometres. Can be negative. ## `maxDepth` (type: `number`): Only return earthquakes shallower than this depth in kilometres. ## `minLatitude` (type: `number`): Southern boundary of geographic bounding box. Range: -90 to 90. ## `maxLatitude` (type: `number`): Northern boundary of geographic bounding box. Range: -90 to 90. ## `minLongitude` (type: `number`): Western boundary of geographic bounding box. Range: -360 to 360. ## `maxLongitude` (type: `number`): Eastern boundary of geographic bounding box. Range: -360 to 360. ## `orderBy` (type: `string`): Sort order for returned earthquakes. ## `maxItems` (type: `integer`): Maximum number of earthquake records to return. USGS API hard limit is 20000. ## Actor input object example ```json { "mode": "recentEarthquakes", "minMagnitude": 4.5, "startTime": "2024-01-01", "orderBy": "time", "maxItems": 100 } ``` # Actor output Schema ## `earthquakes` (type: `string`): Dataset containing all scraped USGS earthquake records. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "recentEarthquakes", "minMagnitude": 4.5, "startTime": "2024-01-01", "orderBy": "time", "maxItems": 100 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/usgs-earthquake-scraper").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "recentEarthquakes", "minMagnitude": 4.5, "startTime": "2024-01-01", "orderBy": "time", "maxItems": 100, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/usgs-earthquake-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "mode": "recentEarthquakes", "minMagnitude": 4.5, "startTime": "2024-01-01", "orderBy": "time", "maxItems": 100 }' | apify call crawlerbros/usgs-earthquake-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/usgs-earthquake-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "USGS Earthquake Data Scraper", "description": "Fetch real-time and historical earthquake data from the USGS Earthquake Hazards Program. Filter by magnitude, date range, depth, geographic bounding box, or radius. No API key required.", "version": "1.0", "x-build-id": "jXhsTKKqPzbin5CxD" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~usgs-earthquake-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-usgs-earthquake-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/crawlerbros~usgs-earthquake-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-usgs-earthquake-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/crawlerbros~usgs-earthquake-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-usgs-earthquake-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "recentEarthquakes", "searchEarthquakes" ], "type": "string", "description": "Choose what to fetch. recentEarthquakes uses your magnitude/limit filters. searchEarthquakes adds explicit date range and geographic filters.", "default": "recentEarthquakes" }, "minMagnitude": { "title": "Minimum Magnitude", "minimum": -1, "maximum": 10, "type": "number", "description": "Only return earthquakes at or above this Richter magnitude. Default is 4.5.", "default": 4.5 }, "maxMagnitude": { "title": "Maximum Magnitude", "minimum": -1, "maximum": 10, "type": "number", "description": "Only return earthquakes at or below this magnitude. Leave blank for no upper limit." }, "startTime": { "title": "Start Time (ISO date)", "type": "string", "description": "Return earthquakes on or after this date/time. Format: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS. Default: 2024-01-01.", "default": "2024-01-01" }, "endTime": { "title": "End Time (ISO date)", "type": "string", "description": "Return earthquakes on or before this date/time. Format: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS. Leave blank to use today." }, "minDepth": { "title": "Minimum Depth (km)", "minimum": -100, "maximum": 1000, "type": "number", "description": "Only return earthquakes deeper than this depth in kilometres. Can be negative." }, "maxDepth": { "title": "Maximum Depth (km)", "minimum": -100, "maximum": 1000, "type": "number", "description": "Only return earthquakes shallower than this depth in kilometres." }, "minLatitude": { "title": "Min Latitude (bounding box)", "minimum": -90, "maximum": 90, "type": "number", "description": "Southern boundary of geographic bounding box. Range: -90 to 90." }, "maxLatitude": { "title": "Max Latitude (bounding box)", "minimum": -90, "maximum": 90, "type": "number", "description": "Northern boundary of geographic bounding box. Range: -90 to 90." }, "minLongitude": { "title": "Min Longitude (bounding box)", "minimum": -360, "maximum": 360, "type": "number", "description": "Western boundary of geographic bounding box. Range: -360 to 360." }, "maxLongitude": { "title": "Max Longitude (bounding box)", "minimum": -360, "maximum": 360, "type": "number", "description": "Eastern boundary of geographic bounding box. Range: -360 to 360." }, "orderBy": { "title": "Order By", "enum": [ "time", "time-asc", "magnitude", "magnitude-asc" ], "type": "string", "description": "Sort order for returned earthquakes.", "default": "time" }, "maxItems": { "title": "Max Items", "minimum": 1, "maximum": 20000, "type": "integer", "description": "Maximum number of earthquake records to return. USGS API hard limit is 20000.", "default": 100 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```