Sky and Sea Alert is a lightweight Python MeshMonitor script that provides aircraft overhead and vessel nearby alerts for a configured latitude/longitude over Meshtastic, using your own locally collected data or official cloud APIs.
MeshMonitor handles Meshtastic, webhooks, routing, and delivery.
Sky and Sea Alert focuses purely on detection, filtering, and alert formatting.
No scraping.
No shared API keys.
No direct radio transmission.
Sky and Sea Alert v2.0.0 introduced a breaking architectural change:
- ❌ No longer positioned as “free cloud API” software
- ✅ Local receivers are now the primary and recommended data source
- ✅ Cloud APIs are explicitly optional and clearly labeled (paid / rate-limited)
This change removes API shutdown risk, ToS ambiguity, and onboarding confusion.
v2.2.0 standardizes and documents expanded aircraft cloud provider support, while preserving the local-first architecture:
- ✅ Free/open aircraft cloud providers (no RapidAPI required)
- ADSB.lol (recommended)
- airplanes.live
- adsb.fi
- ADSB One
⚠️ OpenSky supported as a limited provider (eligibility and policies apply)- 💲 ADSBexchange via RapidAPI remains supported as the paid option
- ✅ Local ADS-B + AIS remains the recommended and most sustainable path
git clone https://github.com/maxhayim/sky-and-sea-alert.git
cd sky-and-sea-alert
Or download sky_and_sea_alert.py directly.
export SSA_MODE=demo
python sky_and_sea_alert.py
You should immediately see sample
This verifies your environment and MeshMonitor formatting.
export SSA_LAT=25.7816
export SSA_LON=-80.2220
- Free & unlimited → Local receivers (ADS-B + AIS) (recommended)
- No hardware → Cloud providers (free or paid)
export SSA_MODE=sky_and_sea
export SSA_ADSB_URL=http://127.0.0.1:8080/data/aircraft.json
export SSA_AIS_URL=http://127.0.0.1:8181/ais.json
python sky_and_sea_alert.py
(Use your actual local endpoints. See sections below.)
export SSA_MODE=aircraft-cloud
export SSA_AIRCRAFT_PROVIDER=adsblol
python sky_and_sea_alert.py
Alternate providers:
export SSA_AIRCRAFT_PROVIDER=airplaneslive
export SSA_AIRCRAFT_PROVIDER=adsbfi
export SSA_AIRCRAFT_PROVIDER=adsbone
export SSA_AIRCRAFT_PROVIDER=opensky
export SSA_MODE=aircraft-cloud
export SSA_AIRCRAFT_PROVIDER=adsbx_rapidapi
export ADSBX_API_KEY="YOUR_RAPIDAPI_KEY"
python sky_and_sea_alert.py
export SSA_MODE=vessels-cloud
export AISHUB_API_KEY="YOUR_AISHUB_USERNAME"
python sky_and_sea_alert.py
- Hardware: RTL-SDR + ADS-B antenna
- Software:
- dump1090
- readsb
- Output: local JSON over HTTP
Flow: ADS-B receiver → dump1090/readsb → Sky and Sea Alert → MeshMonitor → Meshtastic
No API keys.
No rate limits.
Real-time data.
Local aircraft endpoint (common default):
export SSA_ADSB_URL=http://127.0.0.1:8080/data/aircraft.json
If you want a clean Docker-first ADS-B stack, look at SDR-Enthusiasts software offerings (e.g., ultrafeeder + readsb/tar1090).
Sky and Sea Alert stays the alerting layer; those stacks handle receiver/decoding and expose the same aircraft.json endpoint.
Local receivers can be accessed securely over the internet using a VPN.
Recommended VPN: Tailscale
- No port forwarding
- Encrypted
- Works behind NAT / CGNAT
- Ideal for Raspberry Pi deployments
Example: Remote Pi (ADS-B) → Tailscale → Sky and Sea Alert → MeshMonitor
Use:
export SSA_MODE=aircraft-cloud
export SSA_AIRCRAFT_PROVIDER=
Providers:
- adsblol (recommended)
- airplaneslive
- adsbfi
- adsbone
- opensky (limited)
- adsbx_rapidapi (paid)
Cloud APIs can be rate limited and policies can change. Use responsibly.
Base: https://api.adsb.lol
Provider:
export SSA_AIRCRAFT_PROVIDER=adsblol
Optional override:
export SSA_ADSBLOL_BASE=https://api.adsb.lol
API guide: http://api.airplanes.live/v2/
(Provider defaults to https://api.airplanes.live in the script.)
Provider:
export SSA_AIRCRAFT_PROVIDER=airplaneslive
Optional override:
export SSA_AIRPLANESLIVE_BASE=https://api.airplanes.live
Provider:
export SSA_AIRCRAFT_PROVIDER=adsbfi
Optional override:
export SSA_ADSBFI_BASE=https://opendata.adsb.fi/api
Provider:
export SSA_AIRCRAFT_PROVIDER=adsbone
Optional override:
export SSA_ADSBONE_BASE=https://api.adsb.one
OpenSky’s policy may restrict access; eligibility requirements can apply.
Provider:
export SSA_AIRCRAFT_PROVIDER=opensky
Optional override:
export SSA_OPENSKY_BASE=https://opensky-network.org/api
Official low-cost option:
https://www.adsbexchange.com/api-lite/
RapidAPI listing:
https://rapidapi.com/adsbx/api/adsbexchange-com1
Environment variable:
export ADSBX_API_KEY="YOUR_RAPIDAPI_KEY"
- Hardware: RTL-SDR + VHF AIS antenna
- Software:
- AIS-catcher
- rtl_ais
- Output: local JSON or NMEA
Flow: AIS receiver → AIS-catcher → Sky and Sea Alert → MeshMonitor → Meshtastic
Local AIS endpoint is user-provided:
export SSA_AIS_URL=http://127.0.0.1:8181/ais.json
AIS Hub API page:
https://www.aishub.net/api
How to get access:
- Create an AIS Hub account
- Visit the API page above
- Use the AIS API tab
- Your API “key” is typically your AIS Hub username for the webservice
- Observe the documented rate limits
Environment variable:
export AISHUB_API_KEY="YOUR_AISHUB_USERNAME"
- demo — sample alerts, no data sources
- aircraft-local — local ADS-B receiver (dump1090/readsb)
- vessels-local — local AIS receiver (AIS JSON endpoint)
- sky_and_sea — local ADS-B + local AIS
- aircraft-cloud — cloud aircraft lookup (selected by SSA_AIRCRAFT_PROVIDER)
- vessels-cloud — AIS Hub (account-based)
- Python 3.8+
- Internet (optional for local-only mode)
- SDR hardware (optional, recommended)
No Docker required.
No scraping.
No shared credentials.
Core:
SSA_MODE=sky_and_sea
SSA_LAT=25.7816
SSA_LON=-80.2220
SSA_AIRCRAFT_RADIUS_MI=10
SSA_VESSEL_RADIUS_MI=3
SSA_POLL_INTERVAL=60
SSA_SUPPRESS_MINUTES=15
Aircraft (Local):
SSA_ADSB_URL=http://127.0.0.1:8080/data/aircraft.json
Aircraft (Cloud):
SSA_MODE=aircraft-cloud
SSA_AIRCRAFT_PROVIDER=adsblol (adsblol | airplaneslive | adsbfi | adsbone | opensky | adsbx_rapidapi)
SSA_ADSBLOL_BASE=https://api.adsb.lol
SSA_AIRPLANESLIVE_BASE=https://api.airplanes.live
SSA_ADSBFI_BASE=https://opendata.adsb.fi/api
SSA_ADSBONE_BASE=https://api.adsb.one
SSA_OPENSKY_BASE=https://opensky-network.org/api
ADSBX_API_KEY=your_rapidapi_key (only for adsbx_rapidapi)
Vessels (Local):
SSA_AIS_URL=http://127.0.0.1:8181/ais.json
Vessels (Cloud):
SSA_MODE=vessels-cloud
AISHUB_API_KEY=your_aishub_username
Sky and Sea Alert is fully compatible with MeshMonitor Auto Responder scripting.
Commands:
!ssa
!ssa sky
!ssa sea
!ssa demo
!ssa help
Output:
{ "response": "
MeshMonitor handles:
- Meshtastic
- Webhooks
- Routing
- Channels
- Retries
Sky and Sea Alert never transmits on radios directly.
The following ecosystems exist but are not directly integrated due to licensing, lack of stable public REST API, or commercial restrictions:
- ADSBHub
- adsb.exposed
- Fly Italy ADSB
- HPRadar
- FlightAware
- Flightradar24
- Plane Finder
- AirNav Radar
- Planespotters.net (not real-time ADS-B)
- Plane Watch (ACARS/data projects)
- radarvirtuel.com
- AV Delphi
- The Air Traffic
Sky and Sea Alert does not scrape websites or bypass terms of service.
This project is licensed under the MIT License.
See the LICENSE file for details.
Full license text: https://opensource.org/licenses/MIT
Pull requests are welcome. Open an issue first to discuss ideas or report bugs.
- MeshMonitor built by Yeraze
- Shout out and inspired by TheFlightWall
- ADSB.lol
- airplanes.live
- adsb.fi
- ADSB One
- ADSBexchange
- AIS Hub API
Discover other community-contributed scripts for MeshMonitor: https://meshmonitor.org/user-scripts.html