Monitor USGS GeoJSON earthquake feeds with Python 3 from a CLI terminal. Optional audible alarm terminal bell or custom command is supported. Many options are available to customize output but python-tabulate formatting is used by default.
- Python3 >= 3.10
- Both python-tabulate and Requests
- 256 color terminal capability for color output
- Network access to https://earthquake.usgs.gov
pipx install from the PyPi package is recommended; pipx uses a virtual environment and optionally adds usgs-quakemon to the user's path.
# Recommended PyPi pipx installation #
# presumes "pipx ensurepath" setup #
pipx install usgs-quakemon
usgs-quakemon --help
# Recommended PyPi pipx update
pipx upgrade usgs-quakemon
# Remote GitHub + pipx installation #
pipx install 'git+https://github.com/ryan-steed-usa/usgs-quakemon'
usgs-quakemon --help
# Remote GitHub + pipx update
pipx upgrade usgs-quakemonAdditional installation options
# PyPi uvx installation
uvx usgs-quakemon
# PyPi uvx update
uvx usgs-quakemon@latest
# Clone repository + pipx installation #
git clone https://github.com/ryan-steed-usa/usgs-quakemon
pipx install ./usgs-quakemon
usgs-quakemon --help
# Clone repository + pipx update
cd ./usgs-quakemon
git pull
pipx upgrade usgs-quakemon
# Clone + direct execution
git clone https://github.com/ryan-steed-usa/usgs-quakemon
cd usgs-quakemon
python3 -m pip install -r requirements.txt
python3 usgs-quakemon --helpIf no arguments are specified, the significant earthquakes for the day (--day)
is output by default.
USGS has developed PAGER: an automated system for rapidly estimating impact,
exposure, fatalities, and losses. Color-coded alerting determines the
suggested levels of response: no response needed (green), local/regional (yellow),
national (orange), or international (red).
+-------------------------+----------------------+---------------------------+
| Alert Level and Color | Estimated Fatalities | Estimated Losses (USD) |
+-------------------------+----------------------+---------------------------+
| Red | 1,000+ | $1 billion+ |
| Orange | 100 - 999 | $100 million - $1 billion |
| Yellow | 1 - 99 | $1 million - $100 million |
| Green | 0 | < $1 million |
+-------------------------+----------------------+---------------------------+
Full usage
usage: usgs-quakemon [-h] [-a ALARM] [-f] [-g] [-m MAGNITUDE] [-l] [-p PAGER [PAGER ...]] [-n] [-s] [-r REFRESH] [-ro] [-t TIME_FORMAT] [--color | --no-color] [--api-timeout API_TIMEOUT] [--accept-warning] [--version] [-h45 | -h25 | -h10 |
-hs | -ha | -d45 | -d25 | -d10 | -ds | -da | -w45 | -w25 | -w10 | -ws | -wa | -m45 | -m25 | -m10 | -ms | -ma]
Monitor recent earthquakes reported by USGS at https://earthquake.usgs.gov.
If no arguments are specified, the significant earthquakes for the day (--day)
is output by default.
USGS has developed PAGER: an automated system for rapidly estimating impact,
exposure, fatalities, and losses. Color-coded alerting determines the
suggested levels of response: no response needed (green), local/regional (yellow),
national (orange), or international (red).
+-------------------------+----------------------+---------------------------+
| Alert Level and Color | Estimated Fatalities | Estimated Losses (USD) |
+-------------------------+----------------------+---------------------------+
| Red | 1,000+ | $1 billion+ |
| Orange | 100 - 999 | $100 million - $1 billion |
| Yellow | 1 - 99 | $1 million - $100 million |
| Green | 0 | < $1 million |
+-------------------------+----------------------+---------------------------+
options:
-h, --help show this help message and exit
-a, --alarm ALARM set a custom alarm command, this disables the terminal bell alarm, for example using the sox utility: "play -q ~/Audio/quake-alarm.wav"
-f, --follow enable follow mode like tail, (default: False)
-g, --geo-link enable geo: link column, (default: False)
-m, --magnitude MAGNITUDE
enable audible alarm (defaults to terminal bell) for specified magnitude threshold, value >= mag will trigger the alarm
-l, --localtime display timestamps in local timezone, (default: True)
-p, --pager PAGER [PAGER ...]
enable audible alarm (defaults to terminal bell) for desired pager, valid pagers are ('red', 'orange', 'yellow', 'green')
-n, --no-usgs-link enable the More Info column displaying USGS link, (default: True)
-s, --usgs-short-link
display only the USGS eventpage ID instead of the entire link, (default: False)
-r, --refresh REFRESH
set the API request refresh rate in optional time unit, omitted unit presumes "s" (seconds); minimum 1m, maximum 24h (default: 5m)
-ro, --run-once disable watch and run a single loop (default: False)
-t, --time-format TIME_FORMAT
set an strptime compatible string to customize the time format (default: %Y-%m-%d %H:%M:%S)
--color, --no-color control color output (default: True)
--api-timeout API_TIMEOUT
set the API request timeout value in seconds, minimum 10 (default: 10)
--accept-warning accept/suppress all warning prompts (default: False)
--version show program's version number and exit
-h45, --hour45 show earthquakes >= M4.5 for the last hour
-h25, --hour25 show earthquakes >= M2.5 for the last hour
-h10, --hour10 show earthquakes >= M1.0 for the last hour
-hs, --hour show significant earthquakes for the hour
-ha, --hour-all show all earthquakes for the last hour
-d45, --day45 show earthquakes >= M4.5 for the last day
-d25, --day25 show earthquakes >= M2.5 for the last day
-d10, --day10 show earthquakes >= M1.0 for the last day
-ds, --day show significant earthquakes for the day
-da, --day-all show all earthquakes for the last day
-w45, --week45 show earthquakes >= M4.5 for the last week
-w25, --week25 show earthquakes >= M2.5 for the last week
-w10, --week10 show earthquakes >= M1.0 for the last week
-ws, --week show significant earthquakes for the week
-wa, --week-all show all earthquakes for the last week
-m45, --month45 show earthquakes >= M4.5 for the last month
-m25, --month25 show earthquakes >= M2.5 for the last month
-m10, --month10 show earthquakes >= M1.0 for the last month
-ms, --month show significant earthquakes for the month
-ma, --month-all show all earthquakes for the last month
This command monitors for significant earthquakes occurring within the past week using a customized local timezone format. It will refresh every 4 hours automatically, and execute play -q ~/Audio/quake-alarm.wav if any alerts above green are detected. Non-default Geo URIs are also output.
usgs-quakemon -ws -p 'red' 'orange' 'yellow' --time-format '%a %m-%d-%Y %I:%M:%S %p' -a "play -q ~/Audio/quake-alarm.wav" -r 4h -g -lExample output:
No data is collected nor stored by the author. Some information including origin IP address and HTTP request headers are required to be transmitted to the USGS API endpoint (https://earthquake.usgs.gov/) in order to poll for earthquake updates. The author cannot be held liable for the data collection policy instituted by the server administrators of the USGS services. Privacy and security are highly valued and important to the author. This program will always remain transparent and open-source.
This project is based upon (and was originally forked from) quakewatch by baraclese. Thanks!
Generative "AI" is/was not used to "Vibe code" this project but (local) open-source and open-weight LLMs are employed for knowledge and summarization, mostly for commit logs.