Search Earthquakes
earthquake_searchRead-onlyIdempotent
Search earthquakes by time range, magnitude, depth, location radius, PAGER alert level, or felt reports. Supports USGS (global, richer metadata: PAGER, DYFI, ShakeMap) and EMSC, an independent global catalog operated by the European-Mediterranean Seismological Centre. For location-based queries, provide latitude, longitude, and radius_km together. A rectangular study area is expressed with min_latitude, max_latitude, min_longitude, and max_longitude — each independently optional, so a single edge is a valid constraint. Combining the box with the lat/lon/radius circle intersects the two, returning only events inside both. Both catalogs include non-tectonic records (quarry blasts, explosions) — every event carries its event_type, and event_type="earthquake" filters the rest out on USGS. USGS-specific filters (alert_level, event_type, min_felt, min_significance) are not sent when source=emsc — the response names them in ignoredFilters. Use earthquake_count first to gauge result size before requesting large result sets. A single call returns at most 20,000 events; larger result sets are retrieved by paging with offset, which is passed straight through to the upstream FDSN API. When a result is capped, nextOffset carries the offset for the following page and totalCount the full match count — or countUnavailable reports that the count lookup failed and the total is unknown.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum events to return per call. Default 100. Large limits (>1000) may result in slow responses. Max 20000. Combine with offset to retrieve match sets larger than one call can return. | |
| offset | No | Index of the first event to return, counting from 1 — offset=1 is the first match (both upstream APIs reject 0). Omit for the first page, then pass the nextOffset value from a capped result to fetch the next one. Ordering is set by order_by, so keep order_by, limit, and every filter identical across pages. | |
| source | No | Data source. Both catalogs are global. "usgs" covers global events with PAGER, DYFI, and ShakeMap metadata. "emsc" is an independent global catalog operated by the European-Mediterranean Seismological Centre — use it to cross-check any event, anywhere, against a separate network. It publishes no PAGER, DYFI, or ShakeMap metadata and no per-event detail endpoint; its station coverage is densest around Europe and the Mediterranean. | usgs |
| end_time | No | End of time range as ISO 8601, in the same forms start_time accepts. Defaults to current time if omitted. | |
| latitude | No | Latitude for radius search. Requires longitude and radius_km. | |
| min_felt | No | Minimum number of DYFI (Did You Feel It?) reports. Use to find events with confirmed public impact. Only available from USGS. | |
| order_by | No | Sort order. "time" returns newest first; "magnitude" returns largest first. | time |
| longitude | No | Longitude for radius search. Requires latitude and radius_km. | |
| radius_km | No | Search radius in kilometers from the lat/lon point. 100 km covers a metro region; 500 km covers a large country. Max 20001.6, the ceiling USGS enforces. Converted to degrees for EMSC (1° ≈ 111.2 km). | |
| event_type | No | Filter by upstream event classification, e.g. "earthquake" to exclude quarry blasts and explosions, or "quarry blast" to see only those. Matched verbatim against the USGS catalog, which accepts any string and returns zero matches for an unrecognized one. Only available from USGS. | |
| start_time | No | Start of time range as ISO 8601 (e.g. "2026-01-01" or "2026-05-23T00:00:00"). A bare year expands to January 1st and an unpadded month or day is zero-padded, so both sources honor the same window. Defaults to 30 days before end_time (or before the current time) if omitted — applied server-side so USGS and EMSC honor the same window. | |
| alert_level | No | Minimum PAGER alert level. PAGER estimates economic loss and casualties. "green" = minimal impact; "red" = extreme. Only available from USGS. | |
| max_depth_km | No | Maximum depth in kilometers. Bounded to the documented -100 to 1000 km catalog envelope. | |
| max_latitude | No | Northern edge of a bounding-box search, in degrees. | |
| min_depth_km | No | Minimum depth in kilometers. Bounded to the documented -100 to 1000 km catalog envelope. Shallow quakes (0–70 km) typically cause more surface damage than deep quakes (>300 km). | |
| min_latitude | No | Southern edge of a bounding-box search, in degrees. Independent of the other three box parameters — supply any of them. Must not exceed max_latitude when both are given. | |
| max_longitude | No | Eastern edge of a bounding-box search, in degrees. | |
| max_magnitude | No | Maximum magnitude. | |
| min_longitude | No | Western edge of a bounding-box search, in degrees. Range extends beyond ±180 so a box can cross the antimeridian (e.g. min_longitude=170, max_longitude=190) — always keep min_longitude at or below max_longitude rather than inverting the pair. | |
| min_magnitude | No | Minimum magnitude (Richter or equivalent). M2.5+ is felt by some people; M5+ can cause damage; M7+ is major. | |
| min_significance | No | Minimum USGS significance score (0–2000+). Combines magnitude, felt reports, and PAGER estimates. Significant events typically score 600+. Only available from USGS. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of events returned. | |
| error | No | Present when the call failed. Absent on success. | |
| events | No | Matching earthquake events. | |
| notice | No | Recovery guidance when results are empty or capped — how to broaden filters or get the full count. Absent when the result set is non-empty and within the limit. | |
| source | No | Data source used. | |
| queryEcho | No | Echo of the effective parameters sent to the upstream API, including server-resolved defaults. Use to diagnose unexpected or empty results — a filter absent here was not sent upstream. | |
| truncated | No | True when results were capped by the limit parameter. totalCount carries the full match count when available, and nextOffset the input for the following page. With countUnavailable set the total is unknown, so this flag means the page was filled, not that more events are confirmed to remain. | |
| nextOffset | No | Value to pass as the offset input to retrieve the next page, with every other input unchanged. Present only when more events remain; absent means this was the last page. | |
| totalCount | No | Total events matching the query before the limit was applied. Fetched via a follow-up count query when results are truncated at the limit. Absent when results were not capped, and when that follow-up query failed — countUnavailable separates the two. | |
| ignoredFilters | No | USGS-only filters supplied in the input but not sent upstream because source=emsc does not support them. The result set is NOT constrained by these — re-run with source=usgs to apply them. Absent when every supplied filter was applied. | |
| countUnavailable | No | True when the follow-up total-count query failed, so the total is unknown for this call rather than never requested. The returned events are complete and unaffected; only totalCount is missing. Retry earthquake_count with the same filters to recover the total. Absent whenever the count succeeded or was never needed. |