georest.usgs.earthquakes

Client for the USGS earthquake catalog (the FDSN event web service).

Every earthquake the USGS and its partner networks have located, worldwide, back to the early 1900s for large events, searchable by time, area, magnitude and depth:

from georest.usgs import earthquakes

big = earthquakes.search("2025-01-01", "2025-12-31", min_magnitude=6)
big[["time", "magnitude", "place", "depth_km", "tsunami"]]

near_la = earthquakes.search("2025-01-01", "2025-12-31",
                             center=(-118.24, 34.05), radius_km=100,
                             min_magnitude=3)

Results are complete. The service refuses any search matching more than 20,000 events, so search() counts first and then fetches the events 20,000 at a time until it has them all. count() tells you how many a search will return before you run it.

Copyright 2026 Ryan Rock and Ian Housman

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Module Attributes

PAGE_LIMIT

The most events the service returns in one request.

ORDERS

How results can be ordered, onto the service's names.

Functions

count([start, end])

How many events a search() with the same arguments returns.

get_event(event_id)

Everything the catalog holds about one event.

search([start, end, bbox, center, ...])

Earthquakes (and other seismic events) matching a search.
georest.usgs.earthquakes.PAGE_LIMIT = 20000

The most events the service returns in one request.

georest.usgs.earthquakes.ORDERS = {'largest': 'magnitude', 'newest': 'time', 'oldest': 'time-asc', 'smallest': 'magnitude-asc'}

How results can be ordered, onto the service’s names.

georest.usgs.earthquakes.count(start=None, end=None, **filters) → int[source]

How many events a search() with the same arguments returns.

Example:

from georest.usgs import earthquakes

earthquakes.count("2025-01-01", "2025-12-31", min_magnitude=2.5)   # e.g. 29167
georest.usgs.earthquakes.search(start=None, end=None, *, bbox=None, center=None, radius_km=None, min_magnitude=None, max_magnitude=None, min_depth_km=None, max_depth_km=None, event_type=None, alert_level=None, order: str = 'newest') → Any[source]

Earthquakes (and other seismic events) matching a search.

Parameters:

  • start – Time range, as "YYYY-MM-DD" or an ISO 8601 time (UTC). Without start the service searches the last 30 days.

  • end – Time range, as "YYYY-MM-DD" or an ISO 8601 time (UTC). Without start the service searches the last 30 days.

  • bbox – (west, south, east, north) in degrees. A box that crosses the antimeridian works with west > east.

  • center – A circle instead: (lon, lat) and a radius in kilometers.

  • radius_km – A circle instead: (lon, lat) and a radius in kilometers.

  • min_magnitude – Magnitude range.

  • max_magnitude – Magnitude range.

  • min_depth_km – Depth range, in kilometers below sea level.

  • max_depth_km – Depth range, in kilometers below sea level.

  • event_type – Keep one kind of event, e.g. "earthquake". The catalog also holds quarry blasts, explosions and ice quakes.

  • alert_level – Keep events with this PAGER alert level: "green", "yellow", "orange" or "red".

  • order – "newest" (default), "oldest", "largest" or "smallest".

Returns:

id, time (UTC), magnitude, magnitude_type, place, depth_km, lon, lat, type, alert (PAGER level), tsunami, felt (number of “Did You Feel It?” reports), cdi and mmi (intensities), significance, status, network, updated, title and url (the event page). Every matching event is returned; searches beyond 20,000 events are fetched in pages.

Return type:

pandas.DataFrame, one row per event

Example:

from georest.usgs import earthquakes

# Magnitude 6 and larger worldwide in 2025, largest first
big = earthquakes.search("2025-01-01", "2025-12-31", min_magnitude=6,
                         order="largest")
big[["time", "magnitude", "place", "depth_km", "alert", "tsunami"]]

# Within 100 km of Los Angeles
earthquakes.search("2025-01-01", "2025-12-31", center=(-118.24, 34.05),
                   radius_km=100, min_magnitude=3)
georest.usgs.earthquakes.get_event(event_id: str) → dict[source]

Everything the catalog holds about one event.

Parameters:

event_id – The event’s id, e.g. from the id column of search().

Returns:

The event’s fields as in a search() row, plus products (the kinds of information available for it, such as "shakemap", "dyfi", "losspager", "moment-tensor") and product_urls (each product’s main file, by product kind).

Example:

from georest.usgs import earthquakes

quake = earthquakes.search("2025-01-01", "2025-12-31", min_magnitude=7,
                           order="largest").iloc[0]
detail = earthquakes.get_event(quake["id"])
detail["place"], detail["products"]