USGS APIearthquake.usgs.gov ↗
Query the USGS earthquake catalog by time range, magnitude, and bounding box. Returns event IDs, magnitudes, coordinates, and place descriptions.
What is the USGS API?
The USGS Earthquake Catalog API provides access to global seismic event data through 1 endpoint — search_earthquakes — that returns arrays of earthquake records filtered by time window, magnitude bounds, and geographic bounding box. Each event in the response carries its ID, magnitude, place description, and coordinates. Results support pagination via limit and offset, making it straightforward to page through large result sets.
curl -X GET 'https://api.parse.bot/scraper/87ade977-1503-483e-a286-67b51f07a4d2/search_earthquakes?limit=5&offset=1&endtime=2026-07-22&orderby=time&starttime=2026-07-15&max_latitude=90&min_latitude=-90&max_longitude=180&max_magnitude=9.0&min_longitude=-180&min_magnitude=4.0' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace earthquake-usgs-gov-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: USGS Earthquake Catalog SDK — bounded, re-runnable; every call capped."""
from parse_apis.earthquake_usgs_gov_api import Usgs, OrderBy, InvalidInput
client = Usgs()
# Search recent significant earthquakes worldwide, sorted by magnitude descending.
for quake in client.earthquakes.search(
starttime="2026-07-15", endtime="2026-07-22",
min_magnitude="4.5", orderby=OrderBy.MAGNITUDE, limit=3
):
print(quake.place, quake.magnitude, quake.depth)
# Drill into one result from a bounded geographic search (California).
quake = client.earthquakes.search(
starttime="2026-07-01", endtime="2026-07-22",
min_latitude="32", max_latitude="42",
min_longitude="-125", max_longitude="-114",
orderby=OrderBy.TIME, limit=1
).first()
if quake:
print(quake.id, quake.magnitude, quake.latitude, quake.longitude)
# Typed error handling for invalid inputs.
try:
client.earthquakes.search(
starttime="bad-date", endtime="2026-07-22", limit=1
).first()
except InvalidInput as e:
print("invalid input:", e.message)
print("exercised: earthquakes.search")
Query the USGS earthquake catalog. Returns seismic events matching the given time range, magnitude bounds, and optional geographic bounding box. Results are ordered by the chosen sort and paginated via offset. Each event includes its ID, magnitude, place description, coordinates (longitude, latitude, depth in km), occurrence time (epoch ms), last-updated time (epoch ms), review status, and USGS detail URL.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of events to return (1–20000). |
| offset | integer | 1-based offset for pagination. First page is offset=1. |
| endtimerequired | string | End of the time window, ISO format YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS. |
| orderby | string | Sort order for results. |
| starttimerequired | string | Start of the time window, ISO format YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS. |
| max_latitude | string | Northern boundary of bounding box, decimal degrees [-90, 90]. |
| min_latitude | string | Southern boundary of bounding box, decimal degrees [-90, 90]. |
| max_longitude | string | Eastern boundary of bounding box, decimal degrees [-360, 360]. |
| max_magnitude | string | Maximum magnitude filter (e.g. '7.0'). Omitting applies no upper bound. |
| min_longitude | string | Western boundary of bounding box, decimal degrees [-360, 360]. |
| min_magnitude | string | Minimum magnitude filter (e.g. '2.5'). Omitting returns all magnitudes. |
{
"type": "object",
"fields": {
"metadata": "object with generation timestamp, title, limit, offset, and count",
"earthquakes": "array of earthquake event objects"
},
"sample": {
"data": {
"metadata": {
"count": 5,
"limit": 5,
"title": "USGS Earthquakes",
"offset": 1,
"generated": 1784738396000
},
"earthquakes": [
{
"id": "us7000t2cl",
"url": "https://earthquake.usgs.gov/earthquakes/eventpage/us7000t2cl",
"time": 1784677485433,
"depth": 121.887,
"place": "44 km SSE of Nahrin, Afghanistan",
"status": "reviewed",
"updated": 1784678445040,
"latitude": 35.6983,
"longitude": 69.3313,
"magnitude": 4.4,
"detail_url": "https://earthquake.usgs.gov/fdsnws/event/1/query?eventid=us7000t2cl&format=geojson"
}
]
},
"status": "success"
}
}About the USGS API
What the API Returns
The search_earthquakes endpoint queries the USGS earthquake catalog and returns two top-level objects: metadata and earthquakes. The metadata object includes the generation timestamp, result title, the applied limit and offset values, and the total count of matching events. The earthquakes array contains one object per seismic event, with each record exposing the event ID, magnitude, human-readable place description, and coordinates.
Filtering and Query Parameters
Two parameters are always required: starttime and endtime, both in ISO format (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS). You can narrow results to a rectangle by supplying all four bounding-box parameters: min_latitude, max_latitude, min_longitude, and max_longitude. Latitude values range from -90 to 90; longitude values accept the wider -360 to 360 range to accommodate antimeridian-crossing boxes. The orderby parameter controls sort order, and limit caps the number of events returned per request (1–20000).
Pagination
Pagination uses a 1-based offset. To retrieve the second page of 100 results, set limit=100 and offset=101. The metadata.count field tells you the total number of matching events so you can calculate how many pages exist before fetching them. There is no cursor-based pagination; all navigation is handled through offset arithmetic.
The USGS API is a managed, monitored endpoint for earthquake.usgs.gov — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when earthquake.usgs.gov changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official earthquake.usgs.gov API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a real-time earthquake alert dashboard filtered by magnitude and geographic region
- Analyze historical seismic activity over a custom time window for a specific bounding box
- Aggregate weekly or monthly earthquake counts by magnitude range for a reporting pipeline
- Identify clusters of seismic events near infrastructure locations using coordinate data
- Feed earthquake event data into a GIS tool using the latitude/longitude fields
- Generate academic research datasets of global seismicity for a defined date range
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does USGS provide an official developer API for earthquake data?+
What does the `search_earthquakes` endpoint return for each event?+
earthquakes array includes the event ID, magnitude, a place description (e.g. '14km NNE of Ridgecrest, CA'), and the event's coordinates. The metadata object separately reports the total count, limit, and offset applied to the query.Can I filter results by depth or by specific magnitude type (Mw, Ml, etc.)?+
How fresh is the earthquake data returned by this API?+
metadata object includes a generation timestamp so you can see when the response was produced.