SeismoAlert: A real-time earthquake monitoring toolkit in Python (codes included)

Introduction

In this project, I built SeismoAlert, a Python toolkit for real-time earthquake monitoring and anomaly detection using USGS earthquake data.

I designed it as a practical command-line workflow so I can quickly fetch new events, analyze seismicity trends, generate interactive maps, and run alert checks from the same interface.

Project repository: SeismoAlert on GitHub

Motivation

I wanted a compact and reproducible workflow for day-to-day earthquake monitoring tasks.

In many practical cases, we need to answer questions like:

• What happened in the last 24 hours above a certain magnitude?
• Is the current seismicity rate unusual compared to the recent baseline?
• Where are the events concentrated spatially?
• Did any alert-level condition trigger?

Instead of combining multiple scripts and manual checks, I built one package with a clear CLI and testable modules.

What this app does

SeismoAlert includes four primary workflows:

• fetch: download recent events from USGS
• analyze: run Gutenberg-Richter analysis and anomaly detection
• map: generate an interactive HTML map
• monitor: run one-shot monitoring with alert rules

I also structured it so I can use the same functionality directly as a Python library.

Installation

Install from PyPI

pip install seismoalert

Install from source

git clone https://github.com/earthinversion/seismoalert.git
cd seismoalert
pip install -e .

Install for development

pip install -e ".[dev,test,docs]"

How I use it

1) Fetch recent earthquakes

# Default: last 1 day, M>=2.5
seismoalert fetch

# Custom window and threshold
seismoalert fetch --days 7 --min-magnitude 4.0 --limit 200

2) Run seismicity analysis

seismoalert analyze --days 30 --min-magnitude 1.0 --window-days 7

This step computes:

• magnitude of completeness (Mc)
• Gutenberg-Richter a and b values
• anomalous windows in event rate

3) Generate an interactive map

seismoalert map --days 7 --min-magnitude 2.5 --output earthquakes.html

4) Run monitor and alert checks

seismoalert monitor --days 1 --min-magnitude 4.0 --alert-magnitude 6.0 --alert-count 50

Current alert rules include:

• large earthquake threshold
• high seismicity-rate threshold

Background loop with Makefile

I also use the project Makefile when I want a simple operational loop. I run these commands from the SeismoAlert repository root:

make install
make run
make status
make close

In this mode, make run launches a background monitor loop and writes logs to .run/seismoalert.log.

For ad hoc commands, I can use:

make fetch ARGS="--days 2 --min-magnitude 3.0"
make analyze ARGS="--days 30 --window-days 7"
make map ARGS="--output earthquakes.html"
make monitor ARGS="--alert-magnitude 6.5"

If I am not inside the repository (or if I installed only from PyPI), I run the CLI directly instead of make:

seismoalert fetch --days 2 --min-magnitude 3.0
seismoalert analyze --days 30 --window-days 7

>> seismoalert fetch --days 2 --min-magnitude 3.0   

Fetched 74 earthquakes (M>=3.0, last 2 day(s))
Saved 74 events to /Users/utpalkumar/Documents/datascience/seismoalert-CI-CD-Github/earthquakes.csv
Largest event: M7.1

Top events:
  M7.1  55 km NNW of Kota Belud, Malaysia  (2026-02-22 16:57 UTC)
  M6.1  93 km SW of Nikolski, Alaska  (2026-02-23 05:11 UTC)
  M6.0  south of the Fiji Islands  (2026-02-22 07:43 UTC)
  M5.8  Kuril Islands  (2026-02-22 07:25 UTC)
  M5.5  92 km SW of Nikolski, Alaska  (2026-02-23 10:02 UTC)

Using SeismoAlert as a Python library

I can also integrate SeismoAlert inside Python workflows:

from seismoalert.client import USGSClient
from seismoalert.analyzer import gutenberg_richter

client = USGSClient()
catalog = client.fetch_earthquakes(min_magnitude=2.5)
gr = gutenberg_richter(catalog)
print(gr.b_value)

Engineering workflow and quality controls

I built this project with maintainability in mind:

• package layout under src/seismoalert
• unit, integration, and e2e tests
• linting and formatting workflow
• documentation built with Sphinx
• CI checks and coverage reporting

Useful project links:

• Docs: seismoalert.readthedocs.io
• Issues: GitHub Issues

How I plan to evolve this app

I see this as a strong base that can evolve in several directions:

• add region-specific presets and tectonic-zone filters
• support richer alert delivery backends (webhook/email integrations beyond stubs)
• add configurable anomaly strategies for different seismic regimes
• publish scheduled summaries and trend snapshots
• add more visualization layers beyond epicenter points

I also plan to keep improving reliability by expanding test coverage around edge cases and API failure handling.

Download and source code

I shared the source-code download in the downloads section: SeismoAlert Download Entry

Source code repository: GitHub - earthinversion/seismoalert