# USGS Real-Time Earthquake Data

> USGS Real-Time Earthquake Data is a paid API for AI agents from quakes.withzero.ai, paid per call via MPP, $0.001/call, status unknown (last checked 2026-09-13).

Queries USGS real-time earthquake data by time period, minimum magnitude, and optional geographic radius, returning location, depth, magnitude, and tsunami warnings.

## Facts

- Endpoint: POST https://quakes.withzero.ai/run
- Price: $0.001/call
- Payment: MPP
- Status: unknown
- Last checked: 2026-09-13
- Activations on Zero: 0
- Provider: quakes.withzero.ai
- Website: https://quakes.withzero.ai
- Canonical page: https://www.zero.xyz/c/quakes-withzero-ai-usgs-real-time-earthquake-data-f1e3ad88
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_Em3u8e3WJbR6DHj0X3jlI

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability quakes-withzero-ai-usgs-real-time-earthquake-data-f1e3ad88 -d '<json body>'
```

Example prompt: Show me all earthquakes of magnitude 4.5 or greater that happened in the last week within 500 km of Tokyo (latitude 35.68, longitude 139.69), and flag any tsunami warnings.

## When to prefer this

Use this endpoint when you need real-time or recent USGS earthquake data with flexible filtering by time window, magnitude threshold, and geographic area. Ideal for monitoring seismic activity, alerting on tsunami warnings, or building disaster-awareness features. Prefer this over static datasets when up-to-the-minute data matters.

## Known failure modes

- Invalid period enum value returns validation error
- minMagnitude must be one of the allowed enum strings, not a raw number
- maxRadiusKm must be greater than 0 (exclusiveMinimum)
- latitude/longitude out of range (-90 to 90 and -180 to 180) returns error
- If lat/lon provided without maxRadiusKm, defaults to 500 km radius
- USGS upstream unavailable may return 503 or empty results
- No earthquakes matching criteria returns empty array with total=0

## How this service works

Real-time earthquake data from USGS. Query recent earthquakes by time period and minimum magnitude. Optionally filter by geographic radius. Returns magnitude, location, depth, and tsunami warnings.

## Output

Returns a list of earthquakes sorted newest first, each with magnitude, human-readable location, ISO 8601 timestamp, latitude/longitude, depth in km, tsunami warning boolean, optional alert level (green/yellow/orange/red), and a USGS detail URL — plus a total count and the queried time period.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "period": {
   "enum": [
    "hour",
    "day",
    "week",
    "month"
   ],
   "type": "string",
   "description": "Time period (default \"day\")"
  },
  "latitude": {
   "type": "number",
   "maximum": 90,
   "minimum": -90,
   "description": "Filter: center latitude for radius search (-90 to 90)"
  },
  "longitude": {
   "type": "number",
   "maximum": 180,
   "minimum": -180,
   "description": "Filter: center longitude for radius search (-180 to 180)"
  },
  "maxRadiusKm": {
   "type": "number",
   "maximum": 20000,
   "minimum": 0,
   "description": "Filter: max radius in km from lat/lon (default 500)",
   "exclusiveMinimum": true
  },
  "minMagnitude": {
   "enum": [
    "1.0",
    "2.5",
    "4.5",
    "significant"
   ],
   "type": "string",
   "description": "Minimum magnitude threshold (default \"2.5\")"
  }
 },
 "additionalProperties": false
}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "required": [
  "earthquakes",
  "total",
  "period"
 ],
 "properties": {
  "total": {
   "type": "number",
   "description": "Total earthquakes matching criteria"
  },
  "period": {
   "type": "string",
   "description": "Time period queried"
  },
  "earthquakes": {
   "type": "array",
   "items": {
    "type": "object",
    "required": [
     "magnitude",
     "place",
     "time",
     "latitude",
     "longitude",
     "depth",
     "url",
     "tsunami"
    ],
    "properties": {
     "url": {
      "type": "string",
      "description": "USGS detail URL"
     },
     "time": {
      "type": "string",
      "description": "Time of earthquake (ISO 8601)"
     },
     "alert": {
      "type": "string",
      "description": "Alert level (green, yellow, orange, red)"
     },
     "depth": {
      "type": "number",
      "description": "Depth in km"
     },
     "place": {
      "type": "string",
      "description": "Location description (e.g. \"45 km E of Chenega, Alaska\")"
     },
     "tsunami": {
      "type": "boolean",
      "description": "Whether a tsunami warning was issued"
     },
     "latitude": {
      "type": "number",
      "description": "Latitude"
     },
     "longitude": {
      "type": "number",
      "description": "Longitude"
     },
     "magnitude": {
      "type": "number",
      "description": "Earthquake magnitude"
     }
    },
    "additionalProperties": false
   },
   "description": "List of earthquakes, newest first"
  }
 },
 "additionalProperties": false
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/quakes-withzero-ai-usgs-real-time-earthquake-data-f1e3ad88/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from quakes.withzero.ai](https://www.zero.xyz/host/quakes.withzero.ai/llms.txt)