# USGS Earthquakes API

> USGS Earthquakes returns recent and significant earthquake data as a workflow and API.

USGS Earthquakes searches recent earthquakes near a required place, with optional time, distance, magnitude, and result filters. List significant earthquakes returns worldwide events for a selected past day, week, or month.

- Page: https://fous.com/workflows/usgs-earthquakes
- Handle: `@usgs-earthquakes`
- Category: [Science](https://fous.com/workflows/category/science)
- Source website: https://earthquake.usgs.gov
- Last verified: Sep 30, 2026
- Fous is not affiliated with USGS Earthquakes.

## Methods

### List significant earthquakes

Operation `list_significant_earthquakes`, version 1. 1 credit per call.

List significant earthquakes worldwide for the past day, week, or month, newest first. Impact summaries and alert levels are shown when USGS provides them.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `period` | string | no | `"past_week"` | Time period to list, for example past_week. |

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "period": {
      "enum": [
        "past_day",
        "past_week",
        "past_month"
      ],
      "type": "string",
      "default": "past_week",
      "description": "Time period to list, for example past_week.",
      "examples": [
        "past_week",
        "past_day",
        "past_month"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "period": "past_week"
    },
    {
      "period": "past_day"
    },
    {
      "period": "past_month"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `earthquakes` | array |  | Significant earthquakes sorted newest first. |
| `earthquakes[].time` | string or null | `"2026-09-25T21:23:03.309000Z"` | Earthquake time in UTC, ISO 8601. |
| `earthquakes[].event_id` | string | `"us6000txpi"` | USGS event ID. |
| `earthquakes[].latitude` | number or null | `-21.2982` | Epicenter latitude in degrees. |
| `earthquakes[].location` | string or null | `"80 km ENE of Tadine, New Caledonia"` | Location in words. |
| `earthquakes[].longitude` | number or null | `168.61` | Epicenter longitude in degrees. |
| `earthquakes[].magnitude` | number or null | `6.6` | Earthquake magnitude. |
| `earthquakes[].alert_level` | string or null | `"green"` | USGS PAGER alert level, when available. |
| `earthquakes[].details_link` | string | `"https://earthquake.usgs.gov/earthquakes/eventpage/us6000txpi"` | USGS event details page. |
| `earthquakes[].felt_reports` | integer or null | `11` | Number of public felt reports, when available. |
| `earthquakes[].alert_meaning` | string or null | `"little or no damage expected"` | Expected damage and deaths for this alert level. |
| `earthquakes[].tsunami_alert` | string or null | `"no"` | Whether the event has a tsunami alert flag. |
| `earthquakes[].estimated_impact_summary` | string or null | `"Green alert for shaking-related fatalities and economic losses. There is a low likelihood of casualties and damage."` | USGS estimated impacts when a PAGER summary is available. |

**Example input**

```json
{
  "period": "past_week"
}
```

**Example output**

```json
{
  "earthquakes": [
    {
      "time": "2026-09-25T21:23:03.309000Z",
      "event_id": "us6000txpi",
      "latitude": -21.2982,
      "location": "80 km ENE of Tadine, New Caledonia",
      "longitude": 168.61,
      "magnitude": 6.6,
      "alert_level": "green",
      "details_link": "https://earthquake.usgs.gov/earthquakes/eventpage/us6000txpi",
      "felt_reports": 11,
      "alert_meaning": "little or no damage expected",
      "tsunami_alert": "no",
      "estimated_impact_summary": "Green alert for shaking-related fatalities and economic losses. There is a low likelihood of casualties and damage."
    }
  ]
}
```

### Search earthquakes

Operation `search_earthquakes`, version 1. 1 credit per call.

Find recent USGS earthquakes near a city, address, or region, with distances and times in the searched place’s time zone. Felt reports and alert levels may be unavailable for some earthquakes.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `sort` | string | no | `"largest"` | Order earthquakes by newest or largest, for example newest. |
| `place` | string | yes | `"Los Angeles, CA"` | City, address, or region to search near, for example Los Angeles, CA. |
| `days_back` | integer | no | `30` | Number of past days to search, for example 7. |
| `max_results` | integer | no | `5` | Maximum number of earthquakes to return, for example 50. |
| `radius_miles` | number | no | `300` | Search radius in miles, for example 100. |
| `minimum_magnitude` | number | no | `4` | Smallest earthquake magnitude to include, for example 2.5. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "place"
  ],
  "properties": {
    "sort": {
      "enum": [
        "newest",
        "largest"
      ],
      "type": "string",
      "default": "newest",
      "description": "Order earthquakes by newest or largest, for example newest.",
      "examples": [
        "largest"
      ]
    },
    "place": {
      "type": "string",
      "description": "City, address, or region to search near, for example Los Angeles, CA.",
      "examples": [
        "Los Angeles, CA",
        "Tokyo, Japan",
        "London, UK"
      ]
    },
    "days_back": {
      "type": "integer",
      "default": 7,
      "maximum": 365,
      "minimum": 1,
      "description": "Number of past days to search, for example 7.",
      "examples": [
        30,
        1
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 50,
      "maximum": 200,
      "minimum": 1,
      "description": "Maximum number of earthquakes to return, for example 50.",
      "x-fous-developer": true,
      "examples": [
        5
      ]
    },
    "radius_miles": {
      "type": "number",
      "default": 100,
      "maximum": 1000,
      "description": "Search radius in miles, for example 100.",
      "exclusiveMinimum": 0,
      "examples": [
        300,
        10
      ]
    },
    "minimum_magnitude": {
      "type": "number",
      "default": 2.5,
      "description": "Smallest earthquake magnitude to include, for example 2.5.",
      "examples": [
        4,
        8
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "place": "Los Angeles, CA"
    },
    {
      "sort": "largest",
      "place": "Tokyo, Japan",
      "days_back": 30,
      "max_results": 5,
      "radius_miles": 300,
      "minimum_magnitude": 4
    },
    {
      "place": "London, UK",
      "days_back": 1,
      "radius_miles": 10,
      "minimum_magnitude": 8
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `earthquakes` | array |  | Recent earthquakes near the searched place. |
| `earthquakes[].depth_km` | number or null | `11.85` | Earthquake depth in kilometers. |
| `earthquakes[].latitude` | number | `33.843` | Epicenter latitude. |
| `earthquakes[].location` | string or null | `"7 km WSW of Hermosa Beach, CA"` | Earthquake location in words. |
| `earthquakes[].time_utc` | string | `"2026-09-27T15:40:01.460+00:00"` | Earthquake time in UTC, ISO 8601. |
| `earthquakes[].longitude` | number | `-118.468833333333` | Epicenter longitude. |
| `earthquakes[].magnitude` | number or null | `3.55404092525043` | Earthquake magnitude. |
| `earthquakes[].alert_level` | string or null |  | USGS alert level in words, if available. |
| `earthquakes[].depth_miles` | number or null | `7.36` | Earthquake depth in miles. |
| `earthquakes[].distance_km` | number | `31.21` | Distance from the searched place in kilometers. |
| `earthquakes[].details_link` | string | `"https://earthquake.usgs.gov/earthquakes/eventpage/ci41339927"` | USGS earthquake details page. |
| `earthquakes[].felt_reports` | integer or null | `2115` | Number of felt reports, if known. |
| `earthquakes[].time_at_place` | string | `"2026-09-27T08:40:01.460-07:00"` | Earthquake time in the searched place’s time zone, ISO 8601 with offset. |
| `earthquakes[].tsunami_alert` | string | `"no"` | Whether the USGS flags the earthquake as a possible tsunami. |
| `earthquakes[].usgs_event_id` | string | `"ci41339927"` | USGS event ID. |
| `earthquakes[].distance_miles` | number | `19.39` | Distance from the searched place in miles. |

**Example input**

```json
{
  "place": "Los Angeles, CA"
}
```

**Example output**

```json
{
  "earthquakes": [
    {
      "depth_km": 11.85,
      "latitude": 33.843,
      "location": "7 km WSW of Hermosa Beach, CA",
      "time_utc": "2026-09-27T15:40:01.460+00:00",
      "longitude": -118.468833333333,
      "magnitude": 3.55404092525043,
      "alert_level": null,
      "depth_miles": 7.36,
      "distance_km": 31.21,
      "details_link": "https://earthquake.usgs.gov/earthquakes/eventpage/ci41339927",
      "felt_reports": 2115,
      "time_at_place": "2026-09-27T08:40:01.460-07:00",
      "tsunami_alert": "no",
      "usgs_event_id": "ci41339927",
      "distance_miles": 19.39
    },
    {
      "depth_km": 7.18,
      "latitude": 35.3126666666667,
      "location": "17 km WSW of Johannesburg, CA",
      "time_utc": "2026-09-24T03:11:42.650+00:00",
      "longitude": -117.804,
      "magnitude": 2.62,
      "alert_level": null,
      "depth_miles": 4.46,
      "distance_km": 145.8,
      "details_link": "https://earthquake.usgs.gov/earthquakes/eventpage/ci41338223",
      "felt_reports": 1,
      "time_at_place": "2026-09-23T20:11:42.650-07:00",
      "tsunami_alert": "no",
      "usgs_event_id": "ci41338223",
      "distance_miles": 90.59
    },
    {
      "depth_km": 7.23,
      "latitude": 35.3098333333333,
      "location": "17 km WSW of Johannesburg, CA",
      "time_utc": "2026-09-23T20:44:36.440+00:00",
      "longitude": -117.8055,
      "magnitude": 2.96,
      "alert_level": null,
      "depth_miles": 4.49,
      "distance_km": 145.46,
      "details_link": "https://earthquake.usgs.gov/earthquakes/eventpage/ci41337999",
      "felt_reports": null,
      "time_at_place": "2026-09-23T13:44:36.440-07:00",
      "tsunami_alert": "no",
      "usgs_event_id": "ci41337999",
      "distance_miles": 90.38
    }
  ]
}
```

## Quick start

Call the API with a Fous API key (`FOUS_API_KEY`). To create one, turn on Developer mode in Fous Studio, then open Keys & connections → API keys (https://app.fous.com/keys).

```bash
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
: "${FOUS_API_KEY:?Set FOUS_API_KEY before running this example}"

curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 120 \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@usgs-earthquakes",
  "visibility": "public",
  "operation": "list_significant_earthquakes",
  "version": 1,
  "input": {
    "period": "past_week"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
import json
import os
import urllib.error
import urllib.request

api_key = os.environ.get("FOUS_API_KEY")
if not api_key:
    raise RuntimeError("Set FOUS_API_KEY before running this example")

body = json.loads("{\n  \"api\": \"@usgs-earthquakes\",\n  \"visibility\": \"public\",\n  \"operation\": \"list_significant_earthquakes\",\n  \"version\": 1,\n  \"input\": {\n    \"period\": \"past_week\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
// First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
const apiKey = process.env.FOUS_API_KEY;
if (!apiKey) throw new Error("Set FOUS_API_KEY before running this example");

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(120_000),
  body: JSON.stringify({
  "api": "@usgs-earthquakes",
  "visibility": "public",
  "operation": "list_significant_earthquakes",
  "version": 1,
  "input": {
    "period": "past_week"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

Or describe the data in plain language: send `{"api":"@usgs-earthquakes","prompt":"Describe the data you need, with every detail"}` to the same URL. Fous fills in the input, runs the method that fits and returns only the fields you asked for; `data.route.calls[].request` is the exact call it made. Routing is free; the run costs the same.

## Use cases

- Track recent earthquakes near an office or facility
- Compare earthquake magnitudes across nearby locations
- Review significant earthquakes from a selected period
- Check reported felt reports and alert levels
- Assess earthquake distances, depths, and possible tsunami flags

## FAQ

### Is Fous affiliated with USGS Earthquakes?

No. Fous is not affiliated with USGS Earthquakes. This workflow reads the public earthquake.usgs.gov website and returns its data.

### How much does it cost?

Each run costs 1 credit. With pay-as-you-go, a credit costs 1¢; monthly plans cost less per credit.

### Do I need a USGS Earthquakes account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from earthquake.usgs.gov when you run it; repeating the same request within a day may return the saved result. Fous checks this workflow automatically; it last passed a check on Sep 30, 2026.

### What earthquakes happened near a particular place?

Search earthquakes returns recent earthquakes near a required city, address, or region, with distances and times.

### What significant earthquakes occurred worldwide this week?

List significant earthquakes returns worldwide significant earthquakes for a selected period, including the past week.

### How strong was an earthquake, and how deep was it?

Search earthquakes returns magnitude and depth for recent nearby earthquakes. List significant earthquakes returns magnitude for significant events.

## Related

- [NASA API](https://fous.com/workflows/nasa.md): NASA provides astronomy pictures from June 16, 1995 onward, up to 100 media matches, inclusive UTC asteroid approaches, recent approximate natural events, and upcoming ISS sightings for listed cities.
- [USGS Water Data API](https://fous.com/workflows/usgs-water-data.md): Public USGS river gauge readings and monitoring locations.
- [Google Search API](https://fous.com/workflows/google-search.md): Google Search returns public web, image, job, event, related-question, and autocomplete results in Google’s order, with answers and details when available; results may be fewer, omit information, or be empty.
- [US Census Bureau API](https://fous.com/workflows/us-census-bureau.md): US Census Bureau returns statistics from varying Census years, population estimates through July 1, and address geographies using Census vintages that may differ from representation.
- [National Weather Service API](https://fous.com/workflows/national-weather-service.md): National Weather Service provides U.S. day-and-night forecasts for seven days, hourly forecasts for up to 156 hours where available, active alerts, and latest nearby station observations.
- [Google Maps API](https://fous.com/workflows/google-maps.md): Google Maps returns nearby places, public place details, up to 100 public reviews, and up to three routes; transit options vary by departure time.
- [FEMA API](https://fous.com/workflows/fema.md): FEMA provides public U.S. flood maps and disaster information, including approximate address-based flood risk details and federal disaster declarations by state or county.
- [InciWeb API](https://fous.com/workflows/inciweb.md): InciWeb provides US interagency information on active wildfires and related incidents, with latest dated updates and evacuation or closure notices; past notices may no longer apply.
- [All Science workflows](https://fous.com/workflows/category/science)