Statistics & Analytics

Transform your aircraft tracking data into actionable insights

SkySpy provides comprehensive statistics and analytics capabilities for tracking aircraft activity, analyzing flight patterns, monitoring system performance, and gamification features. This guide covers all available metrics, real-time streaming, historical analysis, and data export options.

Overview

Architecture

graph TB
    subgraph "Data Sources"
        ADS[ADS-B Receiver]
        ACARS[ACARS Decoder]
    end

    subgraph "Processing Layer"
        CACHE[(Redis Cache)]
        DB[(PostgreSQL)]
        CELERY[Celery Workers]
    end

    subgraph "API Layer"
        REST[REST API]
        WS[Socket.IO]
    end

    subgraph "Frontend"
        DASH[Stats Dashboard]
        GAME[Gamification View]
    end

    ADS --> DB
    ACARS --> DB
    DB --> CELERY
    CELERY --> CACHE
    CACHE --> REST
    CACHE --> WS
    REST --> DASH
    WS --> DASH
    REST --> GAME
    WS --> GAME

Components

Pro Tip: All statistics are cached for performance with configurable TTLs, and most support customizable time ranges.

Aircraft Statistics

Core metrics about tracked aircraft within your coverage area.

Live Metrics Dashboard

Altitude Distribution

{
  "total": 42,
  "with_position": 38,
  "military": 3,
  "emergency_squawks": [],
  "altitude": {
    "ground": 2,
    "low": 8,
    "medium": 18,
    "high": 14
  }
}

Top Aircraft Leaderboards

Real-time leaderboards computed from currently tracked aircraft.

Flight Patterns

Flight pattern analytics provide insights into traffic patterns over time.

Busiest Hours Heatmap

Hourly activity distribution for visualization as a heatmap.

xychart-beta
    title "Typical Daily Traffic Pattern"
    x-axis [0, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22]
    y-axis "Aircraft Count" 0 --> 60
    bar [5, 3, 2, 8, 25, 42, 48, 52, 50, 45, 35, 15]

Top Routes

Most frequent origin-destination pairs based on ACARS data and callsign analysis.

Request:

GET /api/v1/flight-patterns/routes?hours=24&limit=20

Response:

{
  "routes": [
    {
      "origin": "KJFK",
      "destination": "KLAX",
      "count": 45,
      "airlines": ["AAL", "UAL", "DAL"]
    }
  ],
  "total_routes": 156,
  "time_range_hours": 24
}

Aircraft Types Distribution

Flight Duration by Type

{
  "duration_by_type": [
    {
      "type": "B738",
      "avg_minutes": 45.2,
      "min_minutes": 5.0,
      "max_minutes": 180.5,
      "session_count": 234
    }
  ]
}

Geographic Statistics

Geographic analytics based on aircraft registration and origin data.

Countries of Origin

Breakdown by country based on registration prefix.

Request:

GET /api/v1/stats/geographic/countries

Response:

{
  "countries": [
    {
      "country": "United States",
      "country_code": "US",
      "count": 234,
      "military_count": 12,
      "military_pct": 5.1
    }
  ],
  "total_countries": 28
}

Airlines/Operators

Connected Airports

Airports most connected to your coverage area based on ACARS mentions.

{
  "airports": [
    {
      "icao": "KJFK",
      "iata": "JFK",
      "name": "John F Kennedy International Airport",
      "country": "United States",
      "count": 156
    }
  ]
}

Military vs Civilian

Endpoint: GET /api/v1/stats/geographic/military-breakdown

Returns military/civilian split by country with counts and percentages.

System Performance

Tracking Quality Metrics

Quality metrics for your ADS-B reception.

Quality Grades

{
  "icao_hex": "A1B2C3",
  "callsign": "UAL123",
  "session": {
    "first_seen": "2024-01-15T10:30:00Z",
    "last_seen": "2024-01-15T11:45:00Z",
    "duration_minutes": 75.0,
    "total_positions": 892
  },
  "quality": {
    "grade": "excellent",
    "update_rate_per_min": 11.89,
    "expected_positions": 900,
    "completeness_pct": 99.1
  },
  "gaps": {
    "total_count": 2,
    "total_time_seconds": 45,
    "gap_percentage": 1.0,
    "max_gap_seconds": 30
  },
  "signal": {
    "avg_rssi": -18.5,
    "min_rssi": -25.2,
    "max_rssi": -12.1
  }
}

Coverage Gaps Analysis

Endpoint: GET /api/v1/stats/tracking-quality/gaps

Antenna Metrics

Beta Feature - Advanced antenna performance analytics

Polar Coverage Plot

Reception data by bearing (direction) for antenna pattern visualization.

pie showData
    title "Coverage by Quadrant"
    "North (0-90°)" : 28
    "East (90-180°)" : 24
    "South (180-270°)" : 22
    "West (270-360°)" : 26

{
  "bearing_data": [
    {
      "bearing_start": 0,
      "bearing_end": 10,
      "count": 1234,
      "max_distance_nm": 185.5,
      "avg_rssi": -18.2
    }
  ],
  "summary": {
    "coverage_pct": 94,
    "total_sightings": 45678,
    "sectors_with_data": 34
  }
}

RSSI vs Distance Correlation

Signal strength analysis by distance for antenna performance evaluation.

{
  "scatter_data": [
    {"distance_nm": 50.5, "rssi": -15.2},
    {"distance_nm": 120.3, "rssi": -22.8}
  ],
  "band_statistics": [
    {"band": "0-25nm", "avg_rssi": -12.5, "count": 500},
    {"band": "25-50nm", "avg_rssi": -16.2, "count": 800}
  ],
  "trend_line": {
    "slope": -0.05,
    "intercept": -10.5,
    "interpretation": "Normal signal degradation with distance"
  },
  "overall_statistics": {
    "avg_rssi": -17.5,
    "min_rssi": -28.0,
    "max_rssi": -8.5
  }
}

Real-Time Stats Streaming

SkySpy provides Socket.IO-based real-time statistics streaming.

Connection Flow

sequenceDiagram
    participant Client
    participant SocketIO as Socket.IO
    participant Cache
    participant Database

    Client->>SocketIO: Connect to /stats namespace
    SocketIO-->>Client: stats.connected (available types)

    Client->>SocketIO: stats.subscribe (flight_patterns)
    SocketIO-->>Client: stats.subscribed

    loop Every 5 seconds
        Cache->>SocketIO: Stats updated
        SocketIO-->>Client: stats.update
    end

    Client->>SocketIO: stats.request (specific query)
    SocketIO->>Cache: Check cache
    alt Cache hit
        Cache-->>SocketIO: Cached data
    else Cache miss
        SocketIO->>Database: Query
        Database-->>SocketIO: Fresh data
        SocketIO->>Cache: Store
    end
    SocketIO-->>Client: stats.response

Available Stat Types

Flight Stats

Geographic Stats

Session Stats

Time Stats

ACARS Stats

Gamification Stats

Socket.IO Messages

Subscribe:

socket.emit('stats.subscribe', {
  stat_types: ['flight_patterns', 'tracking_quality']
});

Request Data:

socket.emit('stats.request', {
  stat_type: 'flight_patterns',
  filters: {
    hours: 24,
    limit: 50
  },
  request_id: 'req-123'
});

Set Filters:

socket.emit('stats.set_filters', {
  filters: {
    hours: 48,
    aircraft_type: 'B738'
  }
});

Refresh Cache:

socket.emit('stats.refresh', {
  stat_type: 'geographic'
});

Listening for Updates:

socket.on('stats.update', (data) => {
  console.log('Stats updated:', data);
});

socket.on('stats.response', (data) => {
  console.log('Stats response:', data);
});

Historical Data Analysis

Trends Over Time

Request:

GET /api/v1/history/trends?hours=24&interval=hour

Response:

{
  "intervals": [
    {
      "timestamp": "2024-01-15T10:00:00Z",
      "unique_aircraft": 42,
      "total_positions": 1234,
      "military_count": 3
    }
  ],
  "summary": {
    "total_unique_aircraft": 156,
    "peak_concurrent": 52,
    "total_intervals": 24
  }
}

Top Performers

Endpoint: GET /api/v1/history/top

{
  "longest_tracked": [
    {
      "icao_hex": "A1B2C3",
      "callsign": "UAL123",
      "aircraft_type": "B738",
      "duration_min": 185.5,
      "is_military": false
    }
  ],
  "furthest_distance": [...],
  "highest_altitude": [...],
  "closest_approach": [...]
}

Distance Analytics

Endpoint: GET /api/v1/history/analytics/distance

{
  "statistics": {
    "mean_nm": 45.2,
    "median_nm": 38.5,
    "max_nm": 245.8,
    "percentile_90": 125.0
  },
  "distribution": {
    "0-25nm": 234,
    "25-50nm": 567,
    "50-100nm": 890,
    "100-150nm": 345,
    "150+nm": 123
  }
}

Speed Analytics

Endpoint: GET /api/v1/history/analytics/speed

{
  "statistics": {
    "mean_kt": 285,
    "max_kt": 612,
    "percentile_90": 480
  },
  "fastest_sessions": [
    {
      "icao_hex": "A1B2C3",
      "callsign": "UAL789",
      "max_speed": 612
    }
  ]
}

Correlation Analysis

Endpoint: GET /api/v1/history/analytics/correlation

xychart-beta
    title "Altitude vs Speed Correlation"
    x-axis ["0-10k", "10-20k", "20-30k", "30k+"]
    y-axis "Avg Speed (kts)" 0 --> 500
    bar [180, 320, 420, 480]

Engagement Statistics

Peak Tracking Periods

{
  "peak_periods": [
    {
      "hour": "2024-01-15T14:00:00Z",
      "unique_aircraft": 52,
      "position_count": 3456,
      "military_count": 4
    }
  ],
  "summary": {
    "avg_aircraft_per_hour": 35.2,
    "max_aircraft_in_hour": 52
  }
}

Return Visitors

Aircraft seen multiple times within the time range.

{
  "return_visitors": [
    {
      "icao_hex": "A1B2C3",
      "registration": "N12345",
      "session_count": 5,
      "total_positions": 2345,
      "first_session": "2024-01-15T06:00:00Z",
      "last_session": "2024-01-15T18:00:00Z"
    }
  ],
  "stats": {
    "total_unique_aircraft": 156,
    "returning_aircraft": 23,
    "return_rate_pct": 14.7
  }
}

Most Watched Aircraft

Endpoint: GET /api/v1/stats/engagement/most-watched

Gamification Features

Level up your aircraft spotting experience!

SkySpy includes gamification elements to make aircraft spotting more engaging.

Personal Records

Track your best achievements across multiple categories.

{
  "records": [
    {
      "record_type": "max_distance",
      "record_type_display": "Maximum Distance",
      "icao_hex": "A1B2C3",
      "callsign": "UAL123",
      "aircraft_type": "B77W",
      "registration": "N12345",
      "operator": "United Airlines",
      "value": 245.8,
      "achieved_at": "2024-01-15T14:30:00Z",
      "previous_value": 220.5,
      "previous_icao_hex": "B2C3D4"
    }
  ]
}

Rare Sightings

Notable and rare aircraft detections.

Rarity Types and Scores

Notable Registration Patterns

Ultra-Rare Aircraft Types

Collection Progress

Endpoint: GET /api/v1/stats/gamification/collection

{
  "total_unique_aircraft": 1234,
  "military_aircraft": 156,
  "unique_types": 89,
  "unique_operators": 234,
  "unique_countries": 45,
  "first_aircraft": {
    "icao_hex": "A1B2C3",
    "registration": "N12345",
    "first_seen": "2023-06-15T10:00:00Z"
  },
  "most_seen": [
    {
      "icao_hex": "B2C3D4",
      "registration": "N54321",
      "operator": "Southwest Airlines",
      "times_seen": 156
    }
  ]
}

Sighting Streaks

Track consecutive day streaks for various categories.

{
  "streaks": [
    {
      "streak_type": "any_sighting",
      "streak_type_display": "Daily Sighting",
      "current_streak_days": 15,
      "current_streak_start": "2024-01-01",
      "last_qualifying_date": "2024-01-15",
      "best_streak_days": 45,
      "best_streak_start": "2023-10-01",
      "best_streak_end": "2023-11-15"
    }
  ]
}

Daily Statistics

Endpoint: GET /api/v1/stats/gamification/daily?days=30

{
  "days": [
    {
      "date": "2024-01-15",
      "unique_aircraft": 156,
      "new_aircraft": 12,
      "total_sessions": 234,
      "total_positions": 45678,
      "military_count": 8,
      "max_distance_nm": 185.5,
      "max_altitude": 45000,
      "max_speed": 580,
      "top_types": {"B738": 45, "A320": 38},
      "top_operators": {"United": 25, "American": 22}
    }
  ]
}

Lifetime Statistics

Endpoint: GET /api/v1/stats/gamification/lifetime

{
  "total_unique_aircraft": 12345,
  "total_sessions": 56789,
  "total_positions": 2345678,
  "unique_aircraft_types": 156,
  "unique_operators": 456,
  "unique_countries": 78,
  "active_tracking_days": 365,
  "total_rare_sightings": 234,
  "all_time_records": {
    "max_distance": {"value": 285.5, "icao_hex": "A1B2C3"},
    "max_altitude": {"value": 51000, "icao_hex": "B2C3D4"}
  },
  "first_sighting": {
    "icao_hex": "C3D4E5",
    "timestamp": "2023-01-01T10:00:00Z"
  }
}

API Endpoints Reference

Stats API

History API

Favorites API

Gamification API

Common Query Parameters

Exporting Data

JSON Export

All API endpoints return JSON data that can be exported directly.

Flight Patterns:

# Export flight patterns for last 48 hours
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-server/api/v1/stats/flight-patterns?hours=48" \
  > flight_patterns.json

Gamification:

# Export gamification stats
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-server/api/v1/stats/gamification/lifetime" \
  > lifetime_stats.json

Combined:

# Export all stats
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-server/api/v1/stats/combined" \
  > all_stats.json

CSV Export

For tabular data, convert JSON to CSV:

# Using jq to convert routes to CSV
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-server/api/v1/flight-patterns/routes" | \
  jq -r '.routes[] | [.origin, .destination, .count] | @csv' \
  > routes.csv

Output format:

"KJFK","KLAX",45
"KORD","KJFK",38
"KLAX","KSFO",32

Scheduled Exports

Use Celery tasks for scheduled data exports:

from skyspy.tasks import export_daily_stats

# Schedule via Celery Beat
CELERY_BEAT_SCHEDULE = {
    'export-daily-stats': {
        'task': 'skyspy.tasks.export_daily_stats',
        'schedule': crontab(hour=0, minute=5),  # 12:05 AM daily
    },
}

Frontend Integration

Using the Stats Hook

The useStatsData hook provides access to all statistics data:

import { useStatsData } from '../hooks';

function MyStatsComponent({ apiBase, wsRequest, wsConnected }) {
  const data = useStatsData({
    apiBase,
    wsRequest,
    wsConnected,
    filters: {
      timeRange: '24h',
      showMilitaryOnly: false
    }
  });

  const {
    stats,              // Current aircraft stats
    top,                // Top aircraft leaderboards
    histStats,          // Historical stats
    flightPatternsData, // Flight patterns
    geographicData,     // Geographic breakdown
    trackingQualityData,// Quality metrics
    engagementData,     // Engagement stats
    antennaAnalytics,   // Antenna performance
    throughputHistory,  // Message rate history
    aircraftHistory     // Aircraft count history
  } = data;

  return (
    // Your component JSX
  );
}

Filter Options

const filters = {
  timeRange: '24h',       // '1h', '6h', '24h', '48h', '7d'
  showMilitaryOnly: false,
  categoryFilter: '',     // 'Commercial', 'GA', 'Military', etc.
  aircraftType: '',       // 'B738', 'A320', etc.
  minAltitude: '',
  maxAltitude: '',
  minDistance: '',
  maxDistance: ''
};

Time Range Mappings

Caching Strategy

Statistics are cached at multiple levels for performance:

Forcing Cache Refresh

REST API:

GET /api/v1/stats/flight-patterns?refresh=true

Socket.IO:

socket.emit('stats.request', {
  stat_type: 'flight_patterns',
  filters: { force_refresh: true }
});

Best Practices

Related Documentation

• Socket.IO API - Real-time streaming details
• Authentication - API token management
• Alerts - Set up stat-based alerts