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

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

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)

Extend query bounds 5-15% beyond the visible viewport to improve UX and anticipate edge transitions.

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
  };
}

Benefits:

Eliminates visual "pop-in" during map panning
Pre-loads aircraft approaching screen edges
Smooths fast-moving traffic transitions (e.g., aircraft at 200+ knots)
Minimal bandwidth overhead (typically <10% additional data)

Polling Frequency

Recommended interval: 3 seconds

This frequency balances real-time awareness with bandwidth efficiency.

Rationale:

Aircraft moving at 100 knots travel ~150 meters in 3 seconds
3-second updates provide adequate situational awareness while reducing server load
Reduces bandwidth consumption by 66% compared to 1-second polling
Client-side extrapolation maintains smooth visual rendering between updates
Acceptable load for both mobile and web clients with lower data usage

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 representation:
• 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:

Coordinate Order: GeoJSON uses [longitude, latitude] order—ensure your mapping library expects this format
Closed Polygons: The first and last coordinates are identical in GeoJSON; some libraries auto-close, others don't
Multi-Polygon Support: If advisories can have holes or multiple parts, handle MultiPolygon geometry type
Simplification: For complex polygons with many vertices, consider simplification at high zoom levels for performance
Label Placement: Position labels at the polygon centroid or largest interior point to avoid edge placement
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:

[
  {
    "id": "3423C3",
    "latitude": 48.86584,
    "longitude": 2.63723,
    "beacon_type": "JET",
    "transponder_type": "ADS-B",
    "call_sign": "IBE06CK",
    "last_update": 1733412793,
    "altitude": 10554,
    "ground_speed": 237,
    "course": 205,
    "accuracy": 10,
    "status": "AIRBORNE"
  },
  {
    "id": "UAV456",
    "latitude": 48.87012,
    "longitude": 2.64188,
    "beacon_type": "UAV",
    "transponder_type": "ADS-L",
    "call_sign": "DRONE1",
    "last_update": 1733412795,
    "altitude": 120,
    "ground_speed": 15,
    "course": 180,
    "accuracy": 5,
    "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,
    "beacon_type": "JET",
    "call_sign": "IBE06CK",
    "transponder_type": "ADS-B",
    "last_update": 1733412793,
    "altitude": 120,10554,
    "course": 205,
    "ground_speed": 12,237,
    "status": "AIRBORNE",
    "last_update"id": 1733412793"3423C3"
  },
  {
    "id": "UAV2"hx-137105",
    "latitude": 48.87012,63.41303,
    "longitude": 2.64188,10.11205,
    "beacon_type": "UAV",
    "accuracy": 1852,
    "call_sign": "HWX137105",
    "transponder_type": "ADVISORY",
    "last_update": 1766068287,
    "altitude": 115,231,
    "course": 210,0,
    "ground_speed": 10,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": 17334127931766068285,
    "altitude": 450,
    "altitude_accuracy": 10,
    "course": 315,
    "ground_speed": 54,
    "status": "AIRBORNE"
  }
]

4.2 Advisory Area Publishing

Endpoint: POST /v1/advisory

Use this when you want to declare planned operation areas without live telemetry (e.g., scheduled operations, inspection zones).

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

Publishing Frequency: ~1 minute (advisory areas change infrequently)

Request Format: GeoJSON FeatureCollection

Advisory areas use the widely-adopted GeoJSON format, which allows you to define operation areas as:

Points with radius (max_distance property)
Polygons (closed coordinate arrays)

Example 1: Point-Based Advisory

Publish a circular operation area using a point and radius:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "id": "advisory_001",
        "call_sign": "Survey_Alpha",
        "last_update": 1738142598,
        "max_altitude": 150,
        "max_distance": 500,
        "remarks": "Railway inspection"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [4.39201, 50.69378]
      }
    }
  ]
}

Example 2: Polygon-Based Advisory

Publish a complex operation area using a polygon:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "id": "advisory_002",
        "call_sign": "UAV_Alpha",
        "last_update": 1738142598,
        "max_altitude": 120,
        "remarks": "Powerline inspection"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [4.39201, 50.69378],
            [4.39300, 50.69400],
            [4.39400, 50.69500],
            [4.39201, 50.69378]
          ]
        ]
      }
    }
  ]
}

Required Properties

Property	Type	Required	Description
`id`	string	Yes	Unique identifier for the advisory
`call_sign`	string	No	Call sign for identification
`last_update`	long	Yes	Timestamp in seconds since epoch (UTC)
`max_altitude`	int	Yes	Maximum altitude in meters AMSL
`max_distance`	int	Yes (for Point)	Radius in meters for point-based advisories
`remarks`	string	No	Free text description of the operation

Important Notes:

When using Point geometry, the max_distance property is required
When using Polygon geometry, coordinates must form a closed loop (first and last coordinate must be identical)
You can publish multiple advisories in a single request by adding multiple features to the FeatureCollection
Stop publishing an advisory when the operation is complete (advisories expire automatically)

Response:

201 Created: Advisory published successfully
400 Bad Request: Invalid GeoJSON or authentication failure

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:

Data Freshness States:
┌─────────────┬──────────────┬────────────────┬──────────────┐
│   Current   │     Aging    │  Uncertain     │   Expired    │
│   (0-30s)   │   (30-45s)   │                │    (>45s)    │
├─────────────┼──────────────┼────────────────┼──────────────┤
│ Solid icon  │ 70% opacity  │ + uncertainty  │ Remove from  │
│ Full color  │ Subtle pulse │   circle       │   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.zip

Package Contents:

Formats: SVG (vector) and PNG (raster)
Sizes: 24×24, 32×32, 48×48, 64×64 px
Themes: Light and dark mode variants
Categories: UAV, helicopter, GA, commercial, glider, balloon

Usage Recommendations:

Use SVG for web applications (resolution independence, smaller payload)
Use PNG for native applications with fixed DPI requirements
Implement theme switching based on map style (dark maps = light icons)

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.