# 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/tools/usgs-earthquakes
- Handle: `@usgs-earthquakes`
- Category: [Science](https://fous.com/tools/category/science)
- Source website: https://earthquake.usgs.gov
- Last verified: Sep 30, 2026

## Methods

### List significant earthquakes

Operation `list_significant_earthquakes`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

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 completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

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

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_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.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

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=180) 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.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_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);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/usgs-earthquakes`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `list_significant_earthquakes`: List significant earthquakes. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `search_earthquakes`: Search earthquakes. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-usgs-earthquakes https://api.fous.com/mcp/tools/usgs-earthquakes --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

## 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

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this USGS Earthquakes tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. 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. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified 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/tools/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/tools/usgs-water-data.md): Public USGS river gauge readings and monitoring locations.
- [Google Search API](https://fous.com/tools/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/tools/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/tools/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/tools/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/tools/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/tools/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 tools](https://fous.com/tools/category/science)