USGS Quakes is a custom integration for Home Assistant that monitors earthquake events from the USGS Earthquake Hazards Program. It provides geo_location entities for each event matching your filter criteria.
Important
Starting from v1.2.0, this integration uses the domain usgs_earthquakes_feed, which overrides the built-in Home Assistant core integration of the same name. In the integrations overview, it will display a special icon in the upper-right corner of the integration card indicating it overrides a core integration.
If you were using the previous usgs_quakes domain (v1.1.x or earlier), you must remove the old integration and set it up again after upgrading to v1.2.0.
- Monitors earthquakes from the USGS GeoJSON feed.
- Filters by:
- Minimum Magnitude (Mw)
- Maximum Distance from your location (Radius)
- Creates
geo_locationentities for each event. - Includes a special sensor
sensor.usgs_earthquakes_feed_latestthat:- State is the timestamp of the most recent new earthquake event
- Exposes new events via the
latest_eventsattribute (only events detected in the current update cycle; empty when no new earthquakes have arrived) - Fires a
usgs_earthquakes_feed_new_eventsevent on the HA event bus whenever new earthquakes are detected
- Includes a
format_eventsaction that returns earthquake events as formatted text via a response variable
- Home Assistant 2024.6.0 or newer
- Internet access to fetch data from USGS
- Open HACS in Home Assistant.
- Go to Integrations → Custom Repositories.
- Add this repository:
Select type: Integration
https://github.com/Geek-MD/USGS_Quakes - Install and restart Home Assistant.
- Go to Settings → Devices & Services → Add Integration and select USGS Quakes.
- Download this repository.
- Copy the folder
custom_components/usgs_earthquakes_feed/into your Home Assistantconfig/custom_components/directory. - Restart Home Assistant.
- Add the integration via the UI.
Version 1.2.0 changed the integration domain from usgs_quakes to usgs_earthquakes_feed. Home Assistant treats these as two different integrations, so a one-time manual migration is required:
- Go to Settings → Devices & Services.
- Find the USGS Quakes entry with domain
usgs_quakesand delete it. - Install v1.2.0 (via HACS or manually) and restart Home Assistant.
- Go to Settings → Devices & Services → Add Integration and set up USGS Quakes again.
All configuration is done through the UI.
- Latitude / Longitude – Your location
- Radius (Km) – Max distance to include earthquakes
- Minimum Magnitude (Mw) – Ignore earthquakes below this
- Feed Type – Select from 20 different USGS feeds (past hour, day, week, etc.)
You can modify these settings anytime from the integration’s Options menu.
Supported USGS feed types include:
- All earthquakes (past hour, day, week, month)
- Only significant events
- Filtered by magnitude: 1.0+, 2.5+, 4.5+
Full list: USGS GeoJSON Feed Documentation
This sensor exposes:
state: Timestamp of the most recent new earthquake event (only changes when new earthquakes are detected)latest_events: List of new earthquakes detected in the current update cycle, ordered from newest to oldest. Empty when no new earthquakes have arrived since the last update.
How it works:
- First run (or after HA restart):
latest_eventscontains all earthquakes that match your filter criteria.- Subsequent updates with no new earthquakes:
latest_eventsis empty ([]) and the sensor state does not change.- New earthquake detected:
latest_eventscontains only the new event(s), the sensor state updates to the newest event's timestamp.
Every time new earthquakes are detected the integration fires this event on the HA event bus. You can use it as an automation trigger:
trigger:
- platform: event
event_type: usgs_earthquakes_feed_new_eventsThe event data contains:
| Field | Description |
|---|---|
entry_id |
Config-entry ID of the integration instance |
count |
Number of new events detected |
events |
List of new earthquake event dicts |
automation:
- alias: "Notify on new earthquake"
trigger:
- platform: event
event_type: usgs_earthquakes_feed_new_events
action:
- service: notify.mobile_app_my_phone
data:
title: "🌍 New Earthquake"
message: >
{{ trigger.event.data.count }} new earthquake(s) detected.
Latest: {{ trigger.event.data.events[0].title }}Returns the stored earthquake events formatted as human-readable text via a response variable.
action: usgs_earthquakes_feed.format_events
response_variable: result
# result.formatted_events contains multiline text, e.g.:M 5.2 - Near Valparaíso, Chile
Lugar: 8 km NW of Valparaíso
Magnitud: 5.2 Mw
Fecha/Hora: 2025-09-18 04:33:22
Localización: https://www.google.com/maps?q=-33.0458,-71.6197
Call the following service to manually refresh the earthquake feed:
service: usgs_earthquakes_feed.force_feed_updateYou can trigger this from Developer Tools, automations, or UI buttons.
Call this action to retrieve the stored events as formatted text (response variable required):
action: usgs_earthquakes_feed.format_events
response_variable: quake_reportThe variable quake_report.formatted_events will contain a multiline string with event details.
- On first setup (or after HA restart), all events matching the filters are treated as new and included in
latest_events. - On subsequent updates, only new events (based on USGS
id) are included inlatest_events. - When no new earthquakes are detected,
latest_eventsis empty ([]) and the sensor state does not change. - Events in
latest_eventsare ordered from newest to oldest. - All magnitude and distance values follow standard units (Mw, km).
Developed by @Geek-MD
Powered by USGS GeoJSON Feed
Special thanks to @AdamsLab01 for reporting critical bugs and improvements.
MIT © Edison Montes @GeekMD
💻 Proudly developed with GitHub Copilot 🚀