usgs-quakemon 1.0.2

Monitor USGS earthquake feeds with Python 3 from a CLI terminal.

usgs-quakemon

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.

Requirements

• Python3 >= 3.10
• Both python-tabulate and Requests
• 256 color terminal capability for color output
• Network access to https://earthquake.usgs.gov

Installation & Update

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-quakemon

Additional 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 --help

Usage

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              |
+-------------------------+----------------------+---------------------------+

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

Example

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 -l

Example output:

Privacy

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.

---

Credits

This project is based upon (and was originally forked from) quakewatch by baraclese. Thanks!

Notes

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.