GeoSentinel is a real-time geospatial incident monitoring platform built for developers and operators who run situational-awareness systems. It continuously pulls events from GDELT Cloud v2, ACLED, FIRMS NASA, USGS, OpenSky (military flights), and AISStream (AIS vessels), normalises each raw record to a shared canonical model, deduplicates across sources, clusters related events using DBSCAN spatio-temporal grouping, and exposes the resulting incidents through a versioned REST API backed by PostgreSQL/PostGIS. A React dashboard with Mapbox GL JS renders incidents as live 2D/3D map layers with a virtualised incident list, spatial filtering by Area of Interest (AOI), and human-in-the-loop correction tools — making it equally useful as a stand-alone operations dashboard or as a data-pipeline backend for downstream analytics.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.
Quickstart
Clone the repo, start PostgreSQL, install dependencies, and pull your first real earthquake events in under 10 minutes.
Architecture
Deep-dive into the five-layer pipeline from raw source ingestion through DBSCAN clustering to the REST API.
Data Sources
Details on each integrated source — polling frequencies, authentication, rate-limiting handling, and category mappings.
API Reference
Full reference for every
/v1/ endpoint: incidents, AOI CRUD, corrections, health, seed, military flights, and AIS vessels.Key Capabilities
Multi-Source Ingestion
Independent ingestors for GDELT, ACLED, FIRMS NASA, USGS, OpenSky military flights, and AISStream — each with retry/exponential backoff and isolated failure handling so one source outage never stalls the pipeline.
Canonical Normalisation
Every raw record — whether a USGS GeoJSON feature, an ACLED JSON payload, or a FIRMS CSV row — is mapped to the same
EventCanonicalCreate Pydantic schema, with UTC timestamps, WGS84 coordinates, normalised severity (0–10), and source-independence class.DBSCAN Spatio-Temporal Clustering
Events are grouped into incidents using a mixed-metric DBSCAN:
d = w_space × (haversine_km / KM_MAX) + w_time × (Δhours / HOURS_MAX). Epsilon and weights are tunable per incident category; events from different categories are never merged regardless of proximity.Incident Lifecycle State Machine
Every incident flows through a fully audited state machine:
open → updated → stale → closed or false_positive. All transitions — including manual operator corrections — are logged append-only in corrections_audit.AOI Spatial Filtering
Define named Areas of Interest as arbitrary GeoJSON polygons. The API exposes
GET /v1/aoi/{id}/incidents backed by a PostGIS ST_Intersects query, and AOI geometry drives per-source fetch bounding boxes in the FIRMS ingestor.Human-in-the-Loop Corrections
Operators can submit
false_positive, close, reclassify, relocate, and merge corrections via POST /v1/corrections. Each correction is validated against the incident’s current state and written to the immutable audit log.Current Limitations
Data Licenses
The following table summarises the licence terms for every data source integrated into GeoSentinel. Verify current terms with each provider before deploying in production.| Source | Licence | Key Restriction |
|---|---|---|
| FIRMS NASA | NASA Open Data — free use | Attribution required |
| USGS Earthquake Hazards | Public domain | None |
| GDELT Project | Public domain | None |
| ACLED | CC BY-NC 4.0 | Non-commercial use only |
| OpenSky Network | OpenSky Terms of Use | Non-commercial use permitted |
| MarineTraffic | Commercial | Raw data redistribution not permitted |
| Mapbox GL JS | Commercial | Requires a valid Mapbox access token — usage limits apply per plan |