Best Practices

SafeSky UAV API - Integration Guide

This pageguide provides developer-orientedarchitectural patterns and best practices for integrating the SafeSky UAV API into custom mission control software, moving-map applications, orand operational dashboards.

Overview

The objectiveSafeSky isAPI enables developers to build aproduction-grade smooth,air scalable,traffic awareness systems that display real-time positions of UAVs, helicopters, general aviation aircraft, and operationallycommercial correcttraffic. This guide addresses the technical challenges of building responsive, scalable traffic layerlayers showingthat crewedmeet aircraft,operational helicopters,aviation and UAV activity in real time.standards.

AReference live reference implementation using these principles is available at: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. Recommended Integration Architecture

Dual-Thread Pattern

AImplement robusttraffic integrationretrieval shouldand maintaintelemetry publishing as twoindependent, independentasynchronous executionprocesses. threads:This separation is critical for operational reliability.

1.

┌─────────────────────┐      ┌─────────────────────┐
│  Traffic Retrieval  │      │ Telemetry Publisher │
│      Thread

│ Responsible│ forThread fetching│ nearby├─────────────────────┤ air├─────────────────────┤ traffic│ Uses GET /v1/uav Updates│ the│ map continuously

2. UAV Publishing Thread

Responsible for publishing your UAV telemetry Uses POST /v1/uav │ │ Viewport queries │ │ Position updates │ │ 1Hz polling │ │ 1Hz transmission │ └─────────────────────┘ └─────────────────────┘ ↓ ↓ ┌────────────────────────────────────┐ │ Application State/Map │ └────────────────────────────────────┘

Architectural Benefits:

Fault isolation: Network issues in one thread don't cascade to the other RunsIndependent independentlyscaling: ofAdjust trafficpolling retrievaland publishing rates separately Simplified error handling: Each thread manages its own retry logic Resource optimization: Non-blocking I/O prevents thread starvation

SeparatingImplementation theseNote: concernsIn improvessingle-threaded reliability,environments scalability,(e.g., andJavaScript), erroruse handling.separate async tasks or workers to achieve the same isolation.

---

2. Retrieving Traffic forRetrieval aStrategy

Moving Map

Use

Viewport-Based Queries

For map-based applications, always preferuse viewport-basedbounding box queries insteadthat ofalign radius-basedwith searches.the visible viewport:

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

Why

Example:

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

Technical Advantages:

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

Performance Impact: At high zoom levels (city view), viewport queries arecan preferredreduce

payload Matchessize mapby rendering40-60% logiccompared Scalesto efficientlyradius-based atapproaches allthat zoomcover levelsthe Avoidssame unnecessaryvisible off-screen traffic Enables smooth pan & zoom interactions area.

---

Add

Viewport a Safety MarginPadding (Outset)

Overscan)

AlwaysExtend extendquery thebounds viewport slightly5-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 bounds.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)

Tuning Guidance: Use larger padding (12-15%) for high-speed traffic environments or slower network connections.

---

Polling Frequency

Recommended margin:interval: 1 second (1Hz)
+5% to +15% on each side of the viewport

This ensures:frequency balances real-time awareness with reasonable bandwidth consumption.

Rationale:

• Aircraft nearmoving screenat edges100 areknots stilltravel fetched~50 meters per second
• No1-second visualupdates “pop-in”provide whensmooth panninginterpolation without perceptible lag
• BetterAligns anticipationwith ofaviation-grade fast-movingsituational trafficawareness requirements

Acceptable load for both mobile and web clients

FetchingNetwork slightly more traffic than visible is intentional and recommended.Optimization:

---

Polling Frequency

• RecommendedImplement GETexponential interval:backoff 1for secondfailed requests
• ProvidesConsider smoothcompression motion(gzip/brotli) andfor near-real-time awarenessresponses
• SuitableUse HTTP/2 or HTTP/3 where available for bothconnection UAV and crewed aircraft trafficmultiplexing

---

3. Publishing UAV Telemetry

UsePublishing the following endpoint to publish one or more UAVs:

Endpoint

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

Publishing Frequency

Recommended POST interval:Frequency: 1 second (1Hz)

---

Batch Publishing (Stronglyfor Recommended)

Fleet Operations

IfWhen managing multiple UAVsUAVs, simultaneously, always publishuse batch publishing by sending an array of telemetry objects in batch using a single POST request.

WhyPerformance batchComparison:

publishingmatters: 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 overheadhandshake vs. multiple connections
• LowerAtomic latencytimestamps: All UAVs share consistent update time
• ConsistentLower timestampslatency: acrossOne UAVsround-trip instead of N round-trips
• BetterImproved scalabilityscalability: Essential for fleetsswarm andoperations swarms(20+ UAVs)

RecommendedBest approach:Practice:

Aggregate all UAV telemetry updatesin peryour cycleapplication Sendloop themand togetherpublish oncethe perentire secondfleet Avoidstate individual POSTs per UAV 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
  }
]

---

4. Pre-Flight Visibility

(Grounded

GROUNDED Status)

Status

Advertise Before Takeoff

Broadcasting

Before takeoff, it is considered best practice to publish thePublish UAV with:

position

with statusstatus: = GROUNDED
"GROUNDED"

When:

Ideally 3–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

Why:State Transition:

Makes UAV activity visible to helicopters and crewed aircraft Improves shared situational awareness Mirrors aviation intent signaling

SwitchTransition to AIRBORNEstatus: "AIRBORNE" immediately afterupon takeoff.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.

---

5. Smooth Aircraft Motion (Rendering

Client-Side Extrapolation)

Position Extrapolation

Traffic updates arrive at discrete 1-second intervals. To avoidachieve “jumping”smooth icons:

animation,

Useimplement extrapolationdead reckoning between updates

Predict position using:

Last known position Ground speed Course Linearly extrapolate until the next update arrives updates.

ThisAlgorithm:

creates:

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:

• Smooth,Transforms professionaldiscrete position updates into fluid 60fps animation

Eliminates visual "jumping" or "teleporting" artifacts Creates professional, aviation-grade map renderingpresentation BetterImproves user perception of traffic flow Reduced visual jitterpatterns

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

---

6. Traffic Ageing,Aging Uncertainty &and Expiry

Data Freshness Management

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

Advisory UAV Traffic

• ValidValidity: upUp to 2 minutes after timestamplast expiryupdate
• ShouldRationale: remainLower visiblespeed withand appropriatepredictable flight patterns

Display: Apply visual indicationindicators for aged data (reduced opacity, uncertainty ring)

Other

Real-Time Air Traffic (ADS-B, FLARM, ADS-L, etc.)

L)

Time since last updateAge	RecommendedState

behaviorVisualization 0–30 seconds0-30s DisplayCurrent normallyFull opacity, normal icon 30–45 seconds30-45s DisplayStale withReduced opacity + expanding uncertainty circle >4545s secondsExpired Remove from display

Uncertainty Visualization

Implementation ShowApproach:

an

function expandinggetUncertaintyRadius(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 aroundradius
last}
known

position

Purpose:

Radius increases over time to reflect possible movement Prevents false precision afterin signalposition lossestimates. Users see explicit uncertainty rather than misleading "current" positions.

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

---

7. Visual RepresentationDesign BestGuidelines

Practices

Traffic Icon States

RecommendedImplement progressive visual cues: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:

• SolidUAV/Drone: icon:Quadcopter freshor datafixed-wing silhouette
• ReducedHelicopter: opacity:Rotor-based agingicon datawith rotation indicator
• ExpandingGeneral uncertaintyAviation: circle:Small signalaircraft degradationsilhouette
• DistinctCommercial: iconsLarger peraircraft trafficprofile

categoryUnknown: (UAV,Generic helicopter,aircraft GA, jet)symbol

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

---

8. Icon Sets

Assets

To simplify integration, SafeSky provides ready-to-use trafficoptimized icon sets optimised for maprapid rendering.integration.

📦Download: Icon sets download (placeholder):
https://docs.safesky.app/downloads/iconsets

Includes:Package Contents:

• Formats: SVG (vector) and PNG formats(raster)
• MultipleSizes: sizes24×24, 32×32, 48×48, 64×64 px
• DarkThemes: 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 themesicons)

---

9. RecommendedConfiguration Reference

Timing Summary

Parameters

ActionParameter	IntervalValue

Rationale GET traffic (viewport) 1 second Optimal balance of real-time awareness and bandwidth POST UAV telemetry 1 second Maintains continuity for receiving applications Pre-flight GROUNDED publish 3–5 minutesmin before takeoff Provides advanced notice to nearby traffic StartUncertainty uncertaintyvisualization 30 seconds after update Reflects realistic position drift DiscardTraffic trafficexpiry (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

---

10. Reference Implementation

AExplore livea exampleproduction implementingimplementation allof these best practices is available at: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.

---

Additional Resources

API Reference: Full endpoint documentation and schemas Authentication Guide: HMAC signing and API key management Rate Limits: Request throttling and quota information Support: Technical support channels and community forums