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

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

Magnitude types

PAGER alert levels

Intensity scales

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?

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.

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