Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/danizd/GeoSentinel/llms.txt

Use this file to discover all available pages before exploring further.

GeoSentinel polls the USGS FDSN Event API every three minutes to ingest significant seismic events worldwide. The US Geological Survey publishes a near-real-time GeoJSON feed of earthquake detections from its global seismograph network — the most reliable public source for rapid earthquake notification. GeoSentinel applies a minimum magnitude filter of 4.0 to eliminate microseismicity and focus on events likely to cause structural impact or human casualties. No API key is required; the USGS feed is a fully public, domain-licensed government resource.

​
What USGS Provides

The USGS FDSN (Federation of Digital Seismograph Networks) web service delivers GeoJSON FeatureCollection objects where each Feature represents a seismic event. Key fields per event:
  • properties.time — epoch milliseconds of the origin time (UTC)
  • properties.mag — moment magnitude (Richter scale)
  • properties.type — event type: earthquake, explosion, quarry blast, ice quake, sonic boom
  • properties.place — human-readable location description (e.g. “15 km SSE of Pátzcuaro, Mexico”)
  • properties.ids — comma-separated list of authoritative IDs for the event (used for deduplication)
  • properties.url — USGS event detail page
  • properties.horizontalError — horizontal location uncertainty in km
  • geometry.coordinates — [longitude, latitude, depth_km]

​
API Details

PropertyValue
Base URLhttps://earthquake.usgs.gov/fdsnws/event/1/query
Formatformat=geojson
AuthNone — public feed
Polling intervalEvery 180 seconds (3 minutes)
Minimum magnitudeminmagnitude=4.0
Default lookback5 minutes per poll
The full URL built by _build_url() looks like: 
https://earthquake.usgs.gov/fdsnws/event/1/query?format=geojson
  &starttime=2025-07-15T10:00:00
  &endtime=2025-07-15T10:05:00
  &minmagnitude=4.0

​
Magnitude Filter

The minmagnitude=4.0 filter is applied at the API level — the USGS server returns only events at or above this threshold. Magnitude 4.0 is the approximate lower bound where an earthquake becomes widely felt and may cause minor structural damage. Events below this threshold are considered microseismicity and are not ingested.

​
Event Type Mapping

The mapper in usgs_mapper.py translates USGS properties.type to GeoSentinel internal event types:
USGS typeInternal event_typeCategory
earthquakeearthquakeDISASTER_NATURAL
explosionexplosion_seismicDISASTER_NATURAL
quarry blastquarry_blastDISASTER_NATURAL
ice quakeice_quakeDISASTER_NATURAL
sonic boomsonic_boomDISASTER_NATURAL
(unknown)earthquakeOTHER
Unknown type values default to event_type = "earthquake" but are assigned category = OTHER to avoid contaminating natural disaster metrics with uncategorized events.

​
Severity Mapping

Severity (0–10) is derived from the moment magnitude using a stepped table. The mapper applies math.ceil() to the raw magnitude before table lookup — a magnitude 5.8 event is treated as magnitude 6 for severity purposes, reflecting a conservative upward rounding: 
severity = _normalize_severity(math.ceil(magnitude)) if magnitude else _normalize_severity(0)
Moment magnitude (ceiled)Severity
≤ 3.0 (ceiled: 1–3)1.0
3.1–4.0 (ceiled: 4)2.0
4.1–5.0 (ceiled: 5)4.0
5.1–6.0 (ceiled: 6)6.0
6.1–7.0 (ceiled: 7)8.0
> 7.0 (ceiled: ≥ 8)10.0
A magnitude 7.2 earthquake (ceiled to 8) yields severity 10.0. A magnitude 4.1 event (ceiled to 5) yields severity 4.0.

​
Confidence Score

All USGS events are assigned a fixed confidence of 8.0 — reflecting the highly reliable, sensor-based nature of seismograph data operated by a federal scientific agency. USGS does not publish per-event confidence scores.

​
Deduplication

USGS events are deduplicated using the first ID in the properties.ids comma-separated list: 
event_id_source = props.get("ids", "").split(",")[0].strip(",")
USGS can assign multiple IDs to the same event (from different regional networks), but the first entry in ids is the primary authoritative identifier. If ids is empty, the GeoJSON feature’s top-level id field is used as a fallback.

​
Coordinate Extraction

GeoJSON coordinates arrive as [longitude, latitude, depth_km] — note the longitude-first GeoJSON convention, which the mapper handles explicitly: 
coords = geom.get("coordinates", [])
lon       = coords[0] if len(coords) > 0 else None
lat       = coords[1] if len(coords) > 1 else None
depth_km  = coords[2] if len(coords) > 2 else None
Depth is preserved in source_refs as "depth: {depth_km} km".

​
Source References

Each normalized USGS event includes location context in source_refs: 
source_refs = [
    props["place"],           # e.g. "15 km SSE of Pátzcuaro, Mexico"
    f"depth: {depth_km} km",  # e.g. "depth: 10.0 km"
    props["url"],             # USGS event page URL
]

​
Independence Class

USGS is classified as sensor — carrying a ×2.0 confidence weight during incident aggregation. Seismographic data is a direct physical measurement from scientific instrumentation with no editorial layer. See Independence Classes.

​
Retry and Backoff

The ingestor retries up to 5 times with exponential backoff (base 2, cap 60 seconds). The poll window uses lookback_hours if provided, otherwise defaults to a 5-minute window aligned to the polling interval: 
lookback = timedelta(hours=lookback_hours) if lookback_hours else timedelta(minutes=5)
starttime = endtime - lookback

​
Running the Ingestor

cd backend
uv run python backend/scripts/run_usgs.py
The USGS feed is entirely free and has no rate limit documented for the GeoJSON endpoint. GeoSentinel’s 3-minute polling interval is well within normal usage. No API key registration is required.
To fetch a longer historical window — for example, all magnitude 4.0+ earthquakes in the past 7 days — pass lookback_hours=168 to USGSIngestor.run():
ingestor.run(db_session, lookback_hours=168)

Build docs developers (and LLMs) love

Get started for freeTalk to us