Skip to main content

Best Practices

This page provides developer-oriented best practices for integrating the SafeSky UAV API into custom mission control software, moving-map applications, or operational dashboards.

The objective is to build a smooth, scalable, and operationally correct traffic layer showing crewed aircraft, helicopters, and UAV activity in real time.

A live reference implementation using these principles is available at:
👉 https://live.safesky.app

A robust integration should maintain two independent execution threads:

1. Traffic Retrieval Thread
  • Responsible for 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
  • Runs independently of traffic retrieval

Separating these concerns improves reliability, scalability, and error handling.

2. Retrieving Traffic for a Moving Map

Use Viewport-Based Queries

For map-based applications, always prefer viewport-based queries instead of radius-based searches.

GET /v1/uav?viewport=lat_min,lng_min,lat_max,lng_max
Why viewport queries are preferred
  • Matches map rendering logic
  • Scales efficiently at all zoom levels
  • Avoids unnecessary off-screen traffic
  • Enables smooth pan & zoom interactions
Add a Safety Margin (Outset)

Always extend the viewport slightly beyond the visible map bounds.

Recommended margin:
+5% to +15% on each side of the viewport

This ensures:

  • Aircraft near screen edges are still fetched
  • No visual “pop-in” when panning
  • Better anticipation of fast-moving traffic

Fetching slightly more traffic than visible is intentional and recommended.

Polling Frequency

3. Publishing UAV Telemetry

Use the following endpoint to publish one or more UAVs:

POST /v1/uav
Publishing Frequency
  • Recommended POST interval: 1 second
Batch Publishing (Strongly Recommended)

If managing multiple UAVs simultaneously, always publish telemetry in batch using a single POST request.

Why batch publishing matters:

  • Reduced HTTP overhead
  • Lower latency
  • Consistent timestamps across UAVs
  • Better scalability for fleets and swarms
  • Aggregate all UAV telemetry updates per cycle
  • Send them together once per second
  • Avoid individual POSTs per UAV
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 Status)

Advertise Before Takeoff

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

status = GROUNDED

When:

  • Ideally 3–5 minutes before takeoff

Why:

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

Switch to AIRBORNE immediately after takeoff.

5. Smooth Aircraft Motion (Client-Side Extrapolation)

Traffic updates arrive at discrete intervals. To avoid “jumping” icons:

Use extrapolation between updates
  • Predict position using:
    • Last known position
    • Ground speed
    • Course
  • Linearly extrapolate until the next update arrives

This creates:

  • Smooth, professional map rendering
  • Better perception of traffic flow
  • Reduced visual jitter

6. Traffic Ageing, Uncertainty & Expiry

Different traffic types have different lifetimes.

Advisory UAV Traffic
  • Valid up to 2 minutes after timestamp expiry
  • Should remain visible with appropriate visual indication
Other Air Traffic (ADS-B, FLARM, ADS-L, etc.)
Time since last update Recommended behavior
0–30 seconds Display normally
30–45 seconds Display with expanding uncertainty circle
>45 seconds Remove from display
Uncertainty Visualization
  • Show an expanding circle around last known position
  • Radius increases over time to reflect possible movement
  • Prevents false precision after signal loss

7. Visual Representation Best Practices

  • Solid icon: fresh data
  • Reduced opacity: aging data
  • Expanding uncertainty circle: signal degradation
  • Distinct icons per traffic category (UAV, helicopter, GA, jet)

8. Icon Sets

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

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

Includes:

  • SVG and PNG formats
  • Multiple sizes
  • Dark and light themes
Action Interval
GET traffic (viewport) 1 second
POST UAV telemetry 1 second
Pre-flight GROUNDED publish 3–5 minutes before takeoff
Start uncertainty 30 seconds
Discard traffic 45 seconds

10. Reference Implementation

A live example implementing all these best practices is available at:

👉 https://live.safesky.app

Back to top