API DOCUMENTATION

Integrate AeroScope flight tracking data into your applications with our REST API and WebSocket streaming interface. Over 50 endpoints for real-time aircraft intelligence.

AUTHENTICATION

All API requests require authentication via a bearer token. Obtain your token by authenticating through the login endpoint:

POST /api/auth/login
Content-Type: application/json

{ "password": "your_access_token" }

Response:
{ "token": "eyJhbGci...", "expires_in": "24h" }

Include the token in subsequent requests using the Authorization header:

Authorization: Bearer eyJhbGci...

Tokens expire after 24 hours. Refresh by re-authenticating through the login endpoint.

AIRCRAFT DATA ENDPOINTS

GET /api/aircraft
Returns all currently tracked aircraft with full telemetry: position, altitude, speed, heading, callsign, ICAO hex, aircraft type, and enrichment data.
GET /api/aircraft/:icao
Returns detailed data for a specific aircraft identified by its ICAO 24-bit hex address, including historical positions and analysis results.
GET /api/aircraft/stats
Returns aggregate statistics: total aircraft count, type breakdown, altitude distribution, speed histogram, and coverage metrics.

ANALYSIS ENDPOINTS

GET /api/threats
Returns threat assessments for all tracked aircraft, including threat score (0-100), contributing factors, and classification level.
GET /api/patterns
Returns detected flight patterns: orbits, racetracks, loiter patterns, grid searches, and formation flights with classification confidence.
GET /api/drones
Returns drone detection results with confidence scores, classification rationale, and flight characteristics that triggered detection.
GET /api/airspace/complexity
Returns real-time airspace complexity score with contributing factors and ATC-style recommendations.
GET /api/alerts
Returns active alerts including geofence violations, threat score changes, pattern detections, and anomaly detections.

GEOFENCE ENDPOINTS

GET /api/geofence
Returns all configured geofences with their center coordinates, radius, altitude filters, and current violation status.
POST /api/geofence
Create a new geofence. Required body: { lat, lon, radius_nm, name }. Optional: min_altitude, max_altitude, alert_on_entry, alert_on_exit.

DATA EXPORT ENDPOINTS

GET /api/export/csv
Export current aircraft data as CSV. Optional query parameters: fields (comma-separated field list), filter (aircraft type or threat level).
GET /api/export/json
Export current aircraft data as JSON. Supports the same filtering parameters as CSV export.
GET /api/export/geojson
Export aircraft positions as GeoJSON FeatureCollection for use in GIS tools and mapping applications.

WEBSOCKET STREAMING

Connect to the WebSocket endpoint for real-time data streaming:

ws://aeroscope.live/ws?token=eyJhbGci...

The WebSocket delivers the following message types:

WS aircraft_update
Full aircraft state update broadcast every 12 seconds, containing all tracked aircraft with current positions and analysis results.
WS alert
Real-time alert notifications for geofence violations, high threat scores, pattern detections, and anomaly events.
WS stats
Periodic system statistics including aircraft count, data source status, pipeline performance metrics, and uptime.

RATE LIMITS

API requests are rate-limited to ensure fair access for all users:

Rate limit headers are included in API responses: X-RateLimit-Remaining and X-RateLimit-Reset.

USE CASES