Skip to main content

Best Practices

SafeSky UAV API - Integration Guide

This guide provides architectural patterns and best practices for integrating the SafeSky UAV API into mission control software, moving-map applications, and operational dashboards.

Overview

The SafeSky API enables developers to build production-grade air traffic awareness systems that display real-time positions of UAVs, helicopters, recreational aviation, general aviation aircraft, and commercial traffic.

This guide addresses the technical challenges of building responsive, scalable traffic layers that meet operational aviation standards.

Reference Implementation: https://live.safesky.app

Key Design Goals
  • Real-time traffic awareness with minimal latency
  • Smooth, professional rendering on dynamic maps
  • Efficient resource utilization for fleet operations
  • Compliance with aviation best practices

1. Integration Architecture

Dual-Thread Pattern

Implement traffic retrieval and telemetry publishing as independent, asynchronous processes. This separation is critical for operational reliability.

┌─────────────────────┐      ┌─────────────────────┐
│  Traffic Retrieval  │      │   UAV Telemetry     │
│      Thread         │      │  Publisher Thread   │
├─────────────────────┤      ├─────────────────────┤
│ GET /v1/uav         │      │ POST /v1/uav        │
│ Viewport queries    │      │ Position updates    │
│ 3-second polling    │      │ 1Hz transmission    │
└─────────────────────┘      └─────────────────────┘
         ↓                            ↓
    ┌────────────────────────────────────┐
    │      Application State/Map         │
    └────────────────────────────────────┘

Architectural Benefits:

  • Fault isolation: Network issues in one thread don't cascade to the other
  • Independent scaling: Adjust polling and publishing rates separately
  • Simplified error handling: Each thread manages its own retry logic
  • Resource optimization: Non-blocking I/O prevents thread starvation

Implementation Note: In single-threaded environments (e.g., JavaScript), use separate async tasks or workers to achieve the same isolation.

2. Traffic Retrieval Strategy

Efficient traffic retrieval is essential for a responsive UI and predictable backend load. The SafeSky UAV API supports two complementary ways to retrieve surrounding traffic using the same endpoint (GET /v1/uav):

  • Viewport Query (bounding box): best for map rendering (what’s visible on screen).
  • Radius Query (circle around a point): best for proximity logic (alerts, local awareness around a UAV/operator).

Choose the strategy based on how your application defines the “area of interest”.

Viewport-Based Queries

For map-based applications, use bounding box queries that align with the visible viewport:

GET /v1/uav?viewport=lat_min,lng_min,lat_max,lng_max

Example:

GET /v1/uav?viewport=48.8566,2.3522,48.8766,2.3922

Viewport queries are recommended for moving maps because they:

  • Match how mapping SDKs work (screen = rectangle)
  • Avoid fetching large off-screen traffic that won’t be rendered
  • Scale naturally with zoom level (smaller bounds when zoomed in, larger when zoomed out)
Radius Queries

Use radius queries when your logic is centred around a specific point (e.g., UAV position, operator location, mission centroid) and you want all traffic within a fixed distance, regardless of the current map viewport.

GET /v1/uav?lat=<latitude>&lng=<longitude>&rad=<meters>

Example:

GET /v1/uav?lat=48.8566&lng=2.3522&rad=10000

Radius queries are recommended when you need:

  • Proximity / safety alerting around a UAV (or operator) position
  • Backend checks independent of UI viewport (e.g., monitoring a mission corridor)
  • Applications without a map, or where map rendering is secondary

Trade-offs:

  • A radius query may return aircraft outside the currently visible map area (if you also render a map)
  • If used for rendering, you may want client-side filtering to prevent clutter outside the viewport

Technical Advantages of Viewport Query vs Radius Query:

Aspect Viewport Query Radius Query
Zoom adaptability Natural scaling with map bounds Fixed circular area
Data efficiency Fetches only visible region Often includes off-screen data
Rendering alignment 1:1 with visible area Requires post-filtering
Edge cases Handles rectangular screens correctly Circular overlap issues
Viewport Padding (Overscan)

In moving-map applications, the visible viewport changes continuously as the user pans, zooms, or as the own-ship position moves across the map. If traffic is queried only for the exact visible bounds, aircraft can appear abruptly at the screen edges or disappear momentarily during fast interactions.

To avoid this, extend the queried viewport 5–15% beyond the visible map area. This technique—commonly referred to as overscan allows the client to pre-fetch traffic that is about to enter the screen.

This approach is widely used in aviation navigation displays and professional GIS systems to ensure smooth visual continuity.

Implementation Example:

const OVERSCAN_FACTOR = 0.10; // 10% padding

function getQueryViewport(mapBounds) {
  const latPadding = (mapBounds.north - mapBounds.south) * OVERSCAN_FACTOR;
  const lngPadding = (mapBounds.east - mapBounds.west) * OVERSCAN_FACTOR;
  
  return {
    lat_min: mapBounds.south - latPadding,
    lng_min: mapBounds.west - lngPadding,
    lat_max: mapBounds.north + latPadding,
    lng_max: mapBounds.east + lngPadding
  };
}

Why this matters for moving maps

  • Smooth panning: Aircraft already exist just outside the visible area, so panning the map does not trigger sudden icon appearances.
  • Predictable motion: Fast-moving aircraft (e.g. 150–250+ knots) remain visible and continuous between polling cycles.
  • Reduced visual jitter: Small map movements do not require immediate re-queries, improving UI stability.
  • Professional look & feel: Matches the behaviour users expect from aviation-grade navigation displays.
Polling Frequency

This frequency balances real-time awareness with bandwidth efficiency.

Network Optimization:

  • Consider compression (gzip) for responses

3. Understanding Traffic Types

The SafeSky API returns two distinct types of UAV traffic, each with different data models and display requirements.

Live Traffic vs. Advisory Traffic
Characteristic Live Traffic Advisory Traffic
Data Source Real-time telemetry from active UAVs Pre-declared activity areas
Precision Exact position (lat/lng) Area-based (polygon or point + radius)
Update Frequency 1-5 seconds ~1 minute
Use Case Track UAVs in real-time flight Show planned or ongoing operations
Transponder Type ADS-B, FLARM, ADS-L, or custom ADVISORY
Position Accuracy High (GPS-based) Low (area indicator)
Live Traffic Response Model

Live traffic represents UAVs and aircraft transmitting real-time position data:

{
  "id": "UAV123",
  "latitude": 48.86584,
  "longitude": 2.63723,
  "beacon_type": "UAV",
  "call_sign": "FlyingFrog",
  "transponder_type": "ADS-B",
  "last_update": 1733412793,
  "altitude": 180,
  "course": 250,
  "ground_speed": 24,
  "status": "AIRBORNE",
  "accuracy": 10
}

Key Fields:

  • Precise latitude and longitude coordinates
  • Real-time motion data: ground_speed, course, vertical_rate
  • High position accuracy (typically <100m)
  • Status: AIRBORNE, GROUNDED, or INACTIVE
Advisory Traffic Response Model

Advisory traffic is returned as GeoJSON FeatureCollection format:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "id": "Advisory123",
        "call_sign": "UAV_Alpha",
        "last_update": 1738142598,
        "max_altitude": 150,
        "remarks": "Surveying area"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [4.39201, 50.69378],
            [4.39300, 50.69400],
            [4.39400, 50.69500],
            [4.39201, 50.69378]
          ]
        ]
      }
    }
  ]
}

Key Features:

  • Full GeoJSON FeatureCollection format
  • Can contain Polygon or Point geometry types
  • max_altitude represents maximum operational altitude
  • max_distance property (for Point geometry) defines operational radius
  • Render as polygon shapes or circular areas on the map
Display Recommendations
Displaying Live Traffic

Live traffic should be rendered as precise point symbols with real-time updates:

Visual Styling:

  • Icon: Aircraft/UAV symbol oriented by course heading
  • Position: Exact lat/lng coordinates
  • Animation: Smooth extrapolation between updates
  • Label: Show call_sign, altitude, and ground_speed
  • Color: Solid, distinct color by beacon_type

Implementation:

  • Use standard aircraft icons (see Section 9)
  • Apply position extrapolation (see Section 6)
  • Update icon rotation based on course
  • Display motion vector or heading indicator
Displaying Advisory Traffic

Advisory traffic should be rendered as area indicators rather than precise points.

Visual Styling:

  • Fill: Semi-transparent orange/amber (20-30% opacity)
  • Stroke: Solid distinct color (e.g., rgb(255, 140, 0))
  • Label: Show call_sign and max_altitude
  • Z-Index: Below live traffic
  • No heading indicator: Advisory areas are static zones

Implementation Example:

function renderPolygonAdvisory(advisoryGeoJSON) {
  const features = advisoryGeoJSON.features.map(feature => {
    const props = feature.properties;
    
    if (feature.geometry.type === 'Polygon') {
      // Convert GeoJSON coordinates to map projection format
      const coordinates = feature.geometry.coordinates[0].map(coord => 
        [coord[0], coord[1]] // [lng, lat]
      );
      
      // Render polygon with exact boundaries
      const polygon = new Polygon({
        coordinates: [coordinates],
        fill: 'rgba(255, 165, 0, 0.25)', // Semi-transparent orange
        stroke: 'rgb(255, 140, 0)',
        strokeWidth: 2
      });
      
      // Calculate polygon centroid for label placement
      const centroid = calculatePolygonCentroid(coordinates);
      
      const label = new Label({
        position: centroid,
        text: `${props.call_sign || props.id}\nMax Alt: ${props.max_altitude}m`,
        style: {
          backgroundColor: 'rgba(255, 255, 255, 0.8)',
          padding: '4px',
          borderRadius: '4px'
        }
      });
      
      return [polygon, label];
    } else if (feature.geometry.type === 'Point') {
      // Handle point-based advisory within GeoJSON
      const coords = feature.geometry.coordinates;
      const radius = props.max_distance || 500;
      
      const circle = new Circle({
        center: [coords[0], coords[1]],
        radius: radius,
        fill: 'rgba(255, 165, 0, 0.25)',
        stroke: 'rgb(255, 140, 0)',
        strokeWidth: 2
      });
      
      return circle;
    }
  }).flat();
  
  return features;
}

// Helper function for centroid calculation
function calculatePolygonCentroid(coordinates) {
  let x = 0, y = 0;
  coordinates.forEach(coord => {
    x += coord[0];
    y += coord[1];
  });
  return [x / coordinates.length, y / coordinates.length];
}

Rendering Best Practices:

  1. Coordinate Order: GeoJSON uses [longitude, latitude] order—ensure your mapping library expects this format
  2. Closed Polygons: The first and last coordinates are identical in GeoJSON; some libraries auto-close, others don't
  3. Multi-Polygon Support: If advisories can have holes or multiple parts, handle MultiPolygon geometry type
  4. Simplification: For complex polygons with many vertices, consider simplification at high zoom levels for performance
  5. Label Placement: Position labels at the polygon centroid or largest interior point to avoid edge placement
  6. Point Geometry: When rendering Point-based advisories, use the max_distance property as the circle radius

Visual Distinction is Critical:

  • Users must immediately recognize advisory areas as zones of potential activity, not exact positions
  • Never render advisory traffic with precise aircraft icons that imply real-time tracking
  • Always show the operational radius/area visually
  • Use different colors/styles to distinguish from live traffic

User Experience Guidelines:

  • Hover/Click Info: Display call_sign, max_altitude, remarks (if available), and last_update timestamp
  • Opacity: Use semi-transparent fills (20-30% opacity) to avoid obscuring map features
  • Z-Index: Render advisory areas below live traffic to maintain priority
  • Update Frequency: Advisory areas change infrequently; avoid aggressive re-rendering
Example: Mixed Traffic Response

When querying traffic with GET /v1/uav, you receive an array of live traffic objects:

[
  {
    "latitude": 48.86584,
    "longitude": 2.63723,
    "beacon_type": "JET",
    "call_sign": "IBE06CK",
    "transponder_type": "ADS-B",
    "last_update": 1733412793,
    "altitude": 10554,
    "course": 205,
    "ground_speed": 237,
    "status": "AIRBORNE",
    "id": "3423C3"
  },
  {
    "id": "hx-137105",
    "latitude": 63.41303,
    "longitude": 10.11205,
    "beacon_type": "UAV",
    "accuracy": 1852,
    "call_sign": "HWX137105",
    "transponder_type": "ADVISORY",
    "last_update": 1766068287,
    "altitude": 231,
    "course": 0,
    "ground_speed": 0,
    "remarks": "Axel B\n97497815\nAviant",
    "operation_area": "{\"type\":\"Polygon\",\"coordinates\":[[[10.11204838,63.42966685],[10.10479224,63.42934699],[10.09781542,63.42839974],[10.09138643,63.42686155],[10.08575261,63.42479163],[10.08113055,63.42226962],[10.07769777,63.41939255],[10.07558594,63.41627108],[10.07487581,63.41302522],[10.07559419,63.40977973],[10.07771302,63.4066593],[10.08115047,63.4037838],[10.08577418,63.40126364],[10.09140636,63.39919557],[10.09783067,63.39765894],[10.10480049,63.39671274],[10.11204838,63.39639325],[10.11929626,63.39671274],[10.12626608,63.39765894],[10.1326904,63.39919557],[10.13832258,63.40126364],[10.14294628,63.4037838],[10.14638373,63.4066593],[10.14850256,63.40977973],[10.14922095,63.41302522],[10.14851081,63.41627108],[10.14639898,63.41939255],[10.14296621,63.42226962],[10.13834414,63.42479163],[10.13271032,63.42686155],[10.12628133,63.42839974],[10.11930452,63.42934699],[10.11204838,63.42966685]]]}",
    "status": "AIRBORNE"
  },
  {
    "id": "096E2863",
    "latitude": 59.17081,
    "longitude": 9.5268,
    "beacon_type": "HELICOPTER",
    "vertical_rate": 45,
    "accuracy": 0,
    "call_sign": "ROTORWING 30",
    "transponder_type": "ADS-BI",
    "last_update": 1766068285,
    "altitude": 450,
    "altitude_accuracy": 10,
    "course": 315,
    "ground_speed": 54,
    "status": "AIRBORNE"
  }
]

Note: Advisory traffic is retrieved separately as GeoJSON via the same endpoint when advisory areas are active in the queried region.

4. Publishing UAV Information

The SafeSky API provides two distinct publishing mechanisms depending on whether you have live telemetry or only planned operation areas.

4.1 Live UAV Telemetry Publishing

Endpoint: POST /v1/uav

Use this when you have real-time position data from active UAVs.

POST /v1/uav
Content-Type: application/json

Publishing Frequency: 1 second (1Hz)

Batch Publishing for Fleet Operations

When managing multiple UAVs, always use batch publishing by sending an array of telemetry objects in a single request.

Performance Comparison:

Approach UAVs Requests/sec HTTP Overhead Network Latency
Individual 10 10 ~4KB 10× RTT
Batch 10 1 ~400B 1× RTT

Key Benefits:

  • Reduced overhead: Single HTTP handshake vs. multiple connections
  • Lower latency: One round-trip instead of N round-trips
  • Improved scalability: Essential for swarm operations (20+ UAVs)

Best Practice: Aggregate telemetry in your application loop and publish the entire fleet state atomically.

Example: Batch UAV Publish Payload
[
  {
    "id": "UAV1",
    "latitude": 48.86584,
    "longitude": 2.63723,
    "altitude": 120,
    "course": 205,
    "ground_speed": 12,
    "status": "AIRBORNE",
    "last_update": 1733412793
  },
  {
    "id": "UAV2",
    "latitude": 48.87012,
    "longitude": 2.64188,
    "altitude": 115,
    "course": 210,
    "ground_speed": 10,
    "status": "AIRBORNE",
    "last_update": 1733412793
  }
]

5. Pre-Flight Visibility

GROUNDED Status Broadcasting

Publish UAV position with status: "GROUNDED" 3-5 minutes before takeoff.

{
  "id": "UAV1",
  "latitude": 48.86584,
  "longitude": 2.63723,
  "altitude": 0,
  "status": "GROUNDED",
  "last_update": 1734537600
}

Operational Rationale:

  • Provides advanced notification to nearby crewed aircraft and helicopters
  • Establishes situational awareness before airspace usage
  • Aligns with aviation practice of pre-flight intent signaling
  • Particularly important near helipads, airports, or low-altitude flight zones

State Transition: Transition to status: "AIRBORNE" immediately upon takeoff to reflect actual flight status.

Implementation Note: For mission planning applications, this can be automated based on pre-filed flight plans or launch schedules.

6. Smooth Motion Rendering

Client-Side Position Extrapolation

Traffic updates arrive at discrete 3-second intervals. To achieve smooth animation, implement dead reckoning between updates.

Algorithm:

function extrapolatePosition(aircraft, currentTime) {
  const elapsedSeconds = (currentTime - aircraft.last_update) / 1000;
  const distanceMeters = aircraft.ground_speed * 0.514444 * elapsedSeconds; // knots to m/s
  
  const deltaLat = distanceMeters * Math.cos(aircraft.course * Math.PI / 180) / 111320;
  const deltaLng = distanceMeters * Math.sin(aircraft.course * Math.PI / 180) / 
                   (111320 * Math.cos(aircraft.latitude * Math.PI / 180));
  
  return {
    latitude: aircraft.latitude + deltaLat,
    longitude: aircraft.longitude + deltaLng
  };
}

Rendering Impact:

  • Transforms discrete position updates into fluid 60fps animation
  • Eliminates visual "jumping" or "teleporting" artifacts
  • Creates professional, aviation-grade map presentation
  • Improves user perception of traffic flow patterns

Limitation: Extrapolation assumes constant velocity and heading. Maneuvering aircraft may show brief position discrepancies until the next update.

7. Traffic Aging and Expiry

Data Freshness Management

Different traffic sources have different validity windows based on their update characteristics.

Advisory UAV Traffic:
  • Validity: Up to 2 minutes after last update
  • Rationale: Lower speed and predictable flight patterns
  • Display: Apply visual indicators for aged data (reduced opacity, uncertainty ring)
Real-Time Air Traffic (ADS-B, FLARM, ADS-L):
Age State Visualization
0-30s Current Full opacity, normal icon
30-45s Stale Reduced opacity + expanding uncertainty circle
>45s Expired Remove from display
Uncertainty Visualization:

Implementation Approach:

function getUncertaintyRadius(lastUpdate, currentTime, groundSpeed) {
  const ageSeconds = (currentTime - lastUpdate) / 1000;
  if (ageSeconds < 30) return 0;
  
  // Assume maximum maneuvering potential
  const maxDistanceMeters = groundSpeed * 0.514444 * ageSeconds;
  return maxDistanceMeters; // Display as circle radius
}

Purpose: Prevents false precision in position estimates. Users see explicit uncertainty rather than misleading "current" positions.

Visual Design: Use semi-transparent expanding circles that grow linearly with time since last update.

8. Visual Design Guidelines

Traffic Icon States

Implement progressive visual feedback to communicate data confidence:

Current (0–30s) Aging (30–45s) Uncertain Expired (>45s)
Solid icon
Full color		 70% opacity
Subtle pulse		 + uncertainty circle Remove from display
Traffic Categorization

Use distinct iconography for different aircraft types:

  • UAV/Drone: Quadcopter or fixed-wing silhouette
  • Helicopter: Rotor-based icon with rotation indicator
  • General Aviation: Small aircraft silhouette
  • Commercial: Larger aircraft profile
  • Unknown: Generic aircraft symbol

Accessibility Note: Ensure icons are distinguishable by shape, not just color, for colorblind users.

9. Icon Assets

SafeSky provides optimized icon sets for rapid integration.

Download: aircraft_icons.zip

Beacon Type to Icon Mapping:

The table below defines the standard mapping between beacon types returned by the SafeSky API and the corresponding icon assets to be used for visualisation. Each beacon type is associated with a default static SVG icon.

For certain aircraft categories where motion is an important visual cue (notably helicopters and gyrocopters), an optional animated icon set is available. These animation frames can be cycled to represent rotor movement and improve situational awareness, but their use is optional and depends on client-side rendering capabilities and performance constraints.

Beacon type Icon (static) Optional animation
UNKNOWN dot.svg —
STATIC_OBJECT dot.svg —
GLIDER glider.svg —
PARA_GLIDER para_glider.svg —
HAND_GLIDER hand_glider.svg —
PARA_MOTOR para_motor.svg —
PARACHUTE parachute.svg —
FLEX_WING_TRIKES flex_wing_trikes.svg —
THREE_AXES_LIGHT_PLANE light_aircraft.svg —
MOTORPLANE aircraft.svg —
JET heavy_aircraft.svg —
HELICOPTER helicopter.svg helicopter-anim_0.svg … helicopter-anim_3.svg
GYROCOPTER gyrocopter.svg gyrocopter-anim_0.svg … gyrocopter-anim_3.svg
AIRSHIP airship.svg —
BALLOON ballon.svg —
UAV uav.svg —
PAV pav.svg —
MILITARY military.svg —

10. Configuration Reference

Timing Parameters
Parameter Value Rationale
GET traffic (viewport) 3 seconds Optimal balance of real-time awareness and bandwidth efficiency
POST UAV telemetry 1 second Maintains continuity for receiving applications
Pre-flight GROUNDED publish 3–5 min before takeoff Provides advanced notice to nearby traffic
Uncertainty visualization 30 seconds after update Reflects realistic position drift
Traffic expiry (non-UAV) 45 seconds after update Prevents stale data display
UAV expiry 2 minutes after update Accommodates lower-frequency updates
Viewport overscan 10-15% Eliminates edge transition artifacts

11. Reference Implementation

Explore a production implementation of these patterns:

Live Demo: https://live.safesky.app

The reference implementation demonstrates:

  • Dual-thread architecture with independent polling and publishing
  • Viewport-based queries with dynamic overscan
  • Client-side position extrapolation for smooth rendering
  • Progressive data aging with uncertainty visualization
  • Batch telemetry publishing for fleet operations

Use the browser developer tools to observe network traffic patterns, polling behavior, and rendering optimizations in a production environment.

Back to top