# ToolMint USGS Earthquakes

> Query USGS earthquake.usgs.gov FDSN/GeoJSON by point+radius, bbox, or near-me summary. Normalized events with felt/tsunami flags. Public domain US government data.

- Status: Live
- Price: $0.01 / call (x402 exact, USDC on Base eip155:8453, payTo 0xfbF7413bcB3a604936775C96FDbe0b0C9c9E37F5)
- Base URL: https://toolmint-usgs-earthquakes-json.toolmint.workers.dev
- OpenAPI: https://toolmint.toolmint.workers.dev/tools/usgs-earthquakes-json/openapi.json

## Routes

- `GET /query` $0.01: Query by point+radius or bbox; minMagnitude + time; normalized + summary
- `GET /quakes` $0.01: Alias of /query
- `GET /quakes/near` $0.01: Near-me 7-day summary
- `GET /quakes/feed` $0.01: USGS summary feed
- `GET /earthquakes` $0.01: Alias of /query (alias)
- `GET /quakes/bbox` $0.01: Alias of /query (bbox) (alias)
- `GET /quakes/radius` $0.01: Alias of /query (point+radius) (alias)
- `GET /near` $0.01: Alias of /quakes/near (alias)
- `GET /feed` $0.01: Alias of /quakes/feed (alias)

## When to use it

- Recent or historical earthquakes around a location (`/quakes/near`, `/query`).
- Events in a lat/lon box or above a magnitude in a time window (`/query`).
- The latest USGS summary feeds, like "significant this week" (`/quakes/feed`).

Not for: earthquake forecasting or risk scores (this is a list of recorded events), or safety-critical alerts. A search that finds nothing returns `count: 0` and is still charged, because that is a real answer.

## Example

```bash
curl -i "https://toolmint-usgs-earthquakes-json.toolmint.workers.dev/quakes/near?lat=37.77&lon=-122.42&radiusKm=200&minMagnitude=2.5"
```

Trimmed response (values illustrative):

```json
{
  "tool": "usgs-earthquakes-json",
  "version": "0.1.0",
  "mode": "near",
  "window": "7d",
  "point": { "lat": 37.77, "lon": -122.42, "radiusKm": 200 },
  "minMagnitude": 2.5,
  "count": 3,
  "summary": {
    "text": "3 events; strongest M3.1 near ...",
    "feltCount": 1, "tsunamiCount": 0,
    "strongest": { "id": "...", "mag": 3.1, "place": "...", "time": "2026-10-30T08:15:00.000Z" },
    "byMagBucket": { "3-4.9": 1, "<3": 2 }
  },
  "strongest": [ "..." ],
  "latest": [ "..." ],
  "events": [
    {
      "id": "...", "mag": 3.1, "magType": "...", "place": "...",
      "time": "2026-10-30T08:15:00.000Z", "updated": "...",
      "lat": 37.5, "lon": -122.1, "depthKm": 8.0,
      "felt": 12, "feltReported": true, "tsunami": false,
      "significance": 150, "status": "reviewed", "type": "earthquake",
      "cdi": null, "mmi": null, "alert": null, "url": "...", "title": "..."
    }
  ],
  "provenance": {
    "source": "USGS Earthquake Hazards Program / FDSN Event API",
    "sourceUrl": "https://earthquake.usgs.gov/fdsnws/event/1/query?...",
    "fetched_at": "2026-10-31T12:00:00.000Z",
    "license": "US Government work - public domain (USGS)",
    "terms": "https://www.usgs.gov/information-policies-and-instructions/copyrights-and-credits"
  },
  "fetchedAt": "2026-10-31T12:00:00.000Z",
  "cached": false,
  "note": "Near-me summary from USGS FDSN (last 7 days). Public domain."
}
```

`/query` returns the same event fields with `mode` (`radius`, `bbox` or `global`), `query`, `count`, `summary`, `events`. `/quakes/feed` adds `feed`.

## Data source and licence

USGS Earthquake Hazards Program (FDSN Event API and GeoJSON summary feeds). US Government work, public domain; see the USGS copyright and credits page. No API key. Data is preliminary and USGS revises events (`status`, `updated`).

## Freshness and caching

Results can be served from a 5 minute in-memory cache (`cached: true`). USGS feeds update on their own schedule; `fetchedAt` is when we asked.

## Limits

- At most 100 events per call; a larger `limit` is clamped, not rejected.
- `all_month` is a large feed (about 7 MB); it is allowed but may be slow or fail on a small Cloudflare plan (a failure is not charged).
- `felt` counts and `alert` levels come straight from USGS and are often empty.