USGS Earthquake Search

What does USGS Earthquake Search do?

USGS Earthquake Search queries the United States Geological Survey (USGS) FDSN Event Web Service to retrieve structured earthquake data from the world's most comprehensive seismic event database. The USGS records thousands of earthquakes daily from seismograph networks around the globe, and this actor provides clean, programmatic access to that data.

The actor transforms raw GeoJSON responses into flat, easy-to-use JSON records and pushes them to an Apify dataset. Each record includes magnitude, precise geographic coordinates (latitude, longitude, depth), tsunami warning status, community felt reports, Modified Mercalli Intensity (MMI) shake intensity, PAGER alert level, significance score, and a direct link to the USGS event detail page.

Why use USGS Earthquake Search on Apify?

• No query building required -- The USGS API has many parameters. This actor translates a simple form into the correct API query.
• Structured output -- Raw USGS GeoJSON is converted into clean, flat JSON records ideal for spreadsheets, databases, and downstream processing. Coordinates are extracted from nested arrays, timestamps converted to ISO 8601, and tsunami flags converted from integers to booleans.
• Single-request efficiency -- The USGS API supports up to 20,000 results per request, so most searches complete in seconds without pagination.
• Scheduled monitoring -- Run on a schedule to continuously track earthquake activity. Combine with Apify webhooks for real-time alerts via email, Slack, or custom endpoints.
• No API key required -- The USGS earthquake API is free and open.

Key features

• Magnitude filtering with minimum and/or maximum thresholds (e.g., M5.0+ for significant events)
• Geographic radius search using center latitude/longitude and radius in kilometers (up to 20,001 km)
• Date range queries to filter by start and end dates
• Depth filtering with minimum and maximum depth in kilometers
• PAGER alert level filter for green, yellow, orange, or red alert levels
• Tsunami indicators showing whether a tsunami warning was associated with each event
• Community felt reports from the USGS "Did You Feel It?" system
• Shake intensity metrics including CDI (Community Decimal Intensity) and MMI (Modified Mercalli Intensity)
• Up to 20,000 results per run in a single API call

How to use USGS Earthquake Search

1. Navigate to the USGS Earthquake Search on the Apify Store.
2. Click Try for free to open the actor in Apify Console.
3. Set your desired filters -- at minimum, consider setting a start date and minimum magnitude.
4. For location-based searches, provide latitude, longitude, and radius together.
5. Click Start and wait for the run to complete.
6. Download your results from the Dataset tab in JSON, CSV, or Excel format.

Input parameters

Parameter	Type	Required	Default	Description
starttime	string	No	--	Start date (YYYY-MM-DD). Earthquakes from this date onward
endtime	string	No	--	End date (YYYY-MM-DD). Leave empty for latest available data
minmagnitude	number	No	--	Minimum magnitude (e.g., 4.0 for moderate, 6.0 for strong)
maxmagnitude	number	No	--	Maximum magnitude
latitude	number	No	--	Center latitude for radius search (-90 to 90). Use with longitude and maxradiuskm
longitude	number	No	--	Center longitude for radius search (-180 to 180). Use with latitude and maxradiuskm
maxradiuskm	number	No	--	Search radius in km from center point (max 20,001)
mindepth	number	No	--	Minimum depth in kilometers
maxdepth	number	No	--	Maximum depth in kilometers
alertlevel	select	No	--	PAGER alert level: green, yellow, orange, or red
maxResults	integer	No	100	Maximum number of earthquakes to return (1--20,000)

Input examples

Significant earthquakes worldwide in 2024:

{
    "starttime": "2024-01-01",
    "endtime": "2024-12-31",
    "minmagnitude": 6.0,
    "maxResults": 500
}

Earthquakes near Tokyo (within 300 km):

{
    "latitude": 35.6762,
    "longitude": 139.6503,
    "maxradiuskm": 300,
    "minmagnitude": 4.0,
    "starttime": "2025-01-01",
    "maxResults": 200
}

Severe-impact earthquakes only:

{
    "alertlevel": "red",
    "starttime": "2020-01-01",
    "maxResults": 50
}

Shallow earthquakes in California region:

{
    "latitude": 36.7783,
    "longitude": -119.4179,
    "maxradiuskm": 500,
    "maxdepth": 20,
    "minmagnitude": 3.0,
    "starttime": "2025-01-01",
    "maxResults": 500
}

Input tips

• Always set a start date -- Without it, the API defaults to the last 30 days. Set starttime explicitly to control the time window.
• Use magnitude filters for large datasets -- Setting minmagnitude to 4.0+ dramatically reduces result counts when you only need significant events.
• All three radius parameters are required together -- latitude, longitude, and maxradiuskm must all be provided for a geographic search to work.
• Use significance scores in the output to prioritize events. The significance field (0-1000+) combines magnitude, felt reports, and damage potential.
• Schedule hourly runs with a short lookback window to build a near-real-time earthquake monitoring pipeline.

Output example

{
    "eventId": "us7000q1bc",
    "magnitude": 6.2,
    "magnitudeType": "mww",
    "place": "74 km SSW of Ishinomaki, Japan",
    "time": "2025-06-15T03:22:41.000Z",
    "updated": "2025-06-15T08:14:22.000Z",
    "latitude": 37.8214,
    "longitude": 141.0891,
    "depth": 42.3,
    "tsunami": true,
    "felt": 1842,
    "cdi": 5.8,
    "mmi": 6.1,
    "alert": "yellow",
    "significance": 812,
    "status": "reviewed",
    "eventType": "earthquake",
    "url": "https://earthquake.usgs.gov/earthquakes/eventpage/us7000q1bc",
    "extractedAt": "2025-06-15T10:30:00.000Z"
}

Output fields

Field	Type	Description
eventId	string	Unique USGS event identifier
magnitude	number	Earthquake magnitude on the moment magnitude scale
magnitudeType	string	Magnitude calculation method (mww, mb, ml, md, etc.)
place	string	Human-readable location description
time	string	Event origin time in ISO 8601 format
updated	string	Last time event data was updated by USGS
latitude	number	Epicenter latitude in decimal degrees
longitude	number	Epicenter longitude in decimal degrees
depth	number	Hypocenter depth in kilometers (rounded to 1 decimal)
tsunami	boolean	Whether a tsunami warning was issued
felt	number|null	Number of "Did You Feel It?" community reports
cdi	number|null	Community Decimal Intensity (felt report-based, 1-10+ scale)
mmi	number|null	Modified Mercalli Intensity (instrumental, 1-10+ scale)
alert	string|null	PAGER alert level: green, yellow, orange, red, or null
significance	number	USGS significance score (0-1000+, combines magnitude + felt + damage)
status	string	Review status: "automatic" or "reviewed" by a seismologist
eventType	string	Event type: earthquake, quarry blast, explosion, etc.
url	string	Direct link to the USGS event detail page
extractedAt	string	ISO 8601 timestamp of extraction

Magnitude types

Code	Name	Description
mww	Moment magnitude (W-phase)	Most common for M5.0+ events, uses long-period seismic waves
mb	Body-wave magnitude	Uses short-period P-waves, common for teleseismic events
ml	Local (Richter) magnitude	The original Richter scale, used for local/regional events
md	Duration magnitude	Based on signal duration, used for smaller local events
mwb	Moment magnitude (body-wave)	Alternative moment magnitude calculation method

PAGER alert levels

Level	Expected Impact	Description
Green	Limited	Shaking felt, minimal damage expected
Yellow	Moderate	Some damage expected, localized casualties possible
Orange	Significant	Significant damage and casualties likely
Red	Severe	Extensive damage, high fatalities possible

Intensity scales

Metric	Source	Scale	Description
CDI	Community reports	1-10+	Derived from "Did You Feel It?" citizen reports. Reflects how people experienced the shaking
MMI	Seismograph data	1-10+	Instrumentally estimated from ground motion models. Based on seismograph and shake map data

Use cases

• Seismic monitoring -- Schedule regular runs to track earthquake activity near population centers, fault lines, or critical infrastructure. Set up Slack/email alerts for significant events.
• Disaster response -- Immediately identify the location, magnitude, and potential impact of recent earthquakes for emergency coordination.
• Insurance and risk modeling -- Analyze historical earthquake patterns by region, magnitude, and depth for catastrophe models and underwriting.
• Engineering and construction -- Assess seismic activity near construction sites or existing structures for structural design requirements.
• Academic research -- Study seismological patterns, tectonic plate interactions, and earthquake clustering for geophysics research.
• Tsunami monitoring -- Filter events with tsunami: true for coastal hazard monitoring systems.

Programmatic access (API)

Python:

from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")

run = client.actor("ryanclinton/usgs-earthquake-search").call(run_input={
    "starttime": "2025-01-01",
    "minmagnitude": 5.0,
    "maxResults": 200,
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(f"M{item['magnitude']} — {item['place']}")
    print(f"  Depth: {item['depth']} km | Alert: {item['alert']} | Tsunami: {item['tsunami']}")
    print(f"  Felt by: {item['felt']} people | Significance: {item['significance']}")

JavaScript:

import { ApifyClient } from "apify-client";

const client = new ApifyClient({ token: "YOUR_API_TOKEN" });

const run = await client.actor("ryanclinton/usgs-earthquake-search").call({
    starttime: "2025-01-01",
    minmagnitude: 5.0,
    maxResults: 200,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
for (const item of items) {
    console.log(`M${item.magnitude} — ${item.place}`);
    console.log(`  Depth: ${item.depth} km | Alert: ${item.alert}`);
}

cURL:

# Start a run
curl "https://api.apify.com/v2/acts/ryanclinton~usgs-earthquake-search/runs" \
    -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -d '{
        "starttime": "2025-01-01",
        "minmagnitude": 5.0,
        "maxResults": 200
    }'

# Fetch results (after run completes)
curl "https://api.apify.com/v2/datasets/DATASET_ID/items?format=json" \
    -H "Authorization: Bearer YOUR_API_TOKEN"

How it works -- technical details

Input (dates, magnitude, location, depth, alert, maxResults)
  │
  ▼
┌─────────────────────────────────────────────┐
│  1. URL Builder                             │
│  • format=geojson, orderby=time             │
│  • limit=min(maxResults, 20000)             │
│  • starttime, endtime → date params        │
│  • minmagnitude, maxmagnitude → mag params  │
│  • mindepth, maxdepth → depth params        │
│  • alertlevel → alert param                 │
│  • latitude + longitude + maxradiuskm →    │
│    radius search (all 3 required together)  │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│  2. Single API Fetch                        │
│  • GET earthquake.usgs.gov/fdsnws/event/    │
│    1/query                                  │
│  • Returns GeoJSON FeatureCollection        │
│  • Up to 20,000 features per response       │
│  • No pagination needed                     │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│  3. Transform                               │
│  • Coordinates: [lon, lat, depth] array    │
│    → separate lat, lon, depth fields       │
│  • Depth: rounded to 1 decimal place       │
│  • Timestamps: epoch ms → ISO 8601        │
│  • Tsunami: 1 → true, 0 → false          │
│  • All other fields: flat camelCase        │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│  4. Output & Summary                        │
│  • Each earthquake → Apify dataset         │
│  • Summary: magnitude range & average,      │
│    tsunami warning count, alert level       │
│    breakdown, average depth                 │
└─────────────────────────────────────────────┘

GeoJSON coordinate extraction

The USGS API returns earthquakes as GeoJSON features with coordinates in [longitude, latitude, depth] order (note: longitude comes first in GeoJSON, which is the opposite of the typical lat/lon convention). The actor extracts these into separate latitude, longitude, and depth fields for easier consumption.

Single-request architecture

Unlike most API actors that paginate, USGS Earthquake Search makes a single API call. The USGS FDSN Event API supports up to 20,000 results per request via the limit parameter, which is sufficient for most use cases. This makes the actor extremely fast -- typically completing in 5-15 seconds.

Significance score

The USGS computes a significance score (0-1000+) that combines multiple factors:

• Magnitude (primary factor)
• Number of felt reports from "Did You Feel It?"
• Estimated damage from PAGER
• Whether fatalities occurred

Events with significance > 600 are considered highly significant. This is useful for filtering the most impactful earthquakes from large result sets.

How much does it cost to use?

Scenario	Earthquakes	API calls	Time	Est. cost
Recent significant events	100	1	~5 sec	~$0.001
Regional annual search	500	1	~8 sec	~$0.001
Large global dataset	5,000	1	~12 sec	~$0.002
Maximum extraction	20,000	1	~15 sec	~$0.003

The USGS API is completely free. Apify's free tier includes $5 of monthly platform usage.

Limitations

1. 20,000 result maximum -- The USGS API caps at 20,000 results per request. Use date ranges and magnitude filters to split larger datasets.
2. No country-name search -- The API does not support searching by country. Use latitude/longitude radius search to define geographic areas.
3. Default 30-day window -- Without a starttime, the API returns only the last 30 days. Always set a start date for historical queries.
4. Radius search requires all 3 parameters -- latitude, longitude, and maxradiuskm must all be provided together. Partial input is ignored.
5. PAGER alerts only for M5.0+ -- Smaller earthquakes typically do not receive PAGER alert level assessments.
6. Automatic vs. reviewed status -- Initial event data is "automatic" and may be revised within hours. Check the status field for data quality.
7. Non-earthquake events -- The USGS catalog includes quarry blasts, explosions, and other seismic events. Check eventType to filter for earthquakes only.
8. CDI/MMI may be null -- Intensity data is only available for events where felt reports were submitted or shake maps were generated.

Responsible use

• USGS earthquake data is public information. Use it for monitoring, research, emergency planning, and public safety.
• Follow the USGS Data Policy when using the data.
• When building public-facing earthquake alert systems, clearly indicate data latency and the difference between automatic and reviewed events.
• Present earthquake data responsibly, especially during active seismic crises when misinformation can cause panic.

FAQ

How far back does the data go? The USGS catalog has comprehensive global coverage for M5.0+ events since the early 1970s. Smaller magnitudes depend on regional seismograph density.

How quickly does new data appear? Initial "automatic" records appear within 2-5 minutes of detection. Seismologists review and refine data over subsequent hours. The status field indicates review state.

Can I search by country? Not directly. Use latitude/longitude radius search to define a circular area around any location. For example, Japan: latitude 36.0, longitude 138.0, radius 500 km.

What is the PAGER alert level? PAGER estimates earthquake impact severity. Green = limited damage, yellow = moderate, orange = significant, red = severe/catastrophic. Only M5.0+ events typically receive PAGER assessments.

What is the difference between CDI and MMI? CDI (Community Decimal Intensity) comes from citizen "Did You Feel It?" reports. MMI (Modified Mercalli Intensity) is estimated from seismograph data. Both use similar 1-10+ scales but from different data sources.

What is the significance score? A USGS-computed metric (0-1000+) combining magnitude, felt reports, damage estimates, and fatalities. Events > 600 are highly significant.

Integrations and related actors

The output dataset can be exported in JSON, CSV, or Excel format, or accessed programmatically via the Apify API. Use webhooks to trigger automated workflows when a run completes.

Related Actor	Description	Use with
FEMA Disaster Declaration Search	U.S. federal disaster declarations	Cross-reference which earthquakes triggered federal responses
NOAA Weather Alert Monitor	Active U.S. weather alerts	Combined natural hazard monitoring
GDACS Disaster Alerts	Global disaster alerts	International multi-hazard monitoring
Nominatim Geocoder	Convert addresses to coordinates	Get lat/lon for radius searches
OpenStreetMap POI Search	Find points of interest near coordinates	Identify infrastructure near earthquake epicenters

Connect with any Apify integration including Google Sheets, Slack, Zapier, Make (Integromat), Amazon S3, and custom API endpoints to build automated earthquake monitoring workflows.