Skip to main content

Live UAV operations

The Live UAV Operations API enables real-time tracking of UAVs by allowing the publication of live telemetry data, including position, altitude, velocity, and status. Additionally, the API provides the ability to retrieve nearby airborne traffic.

Typically, you can poll using GET and push data using POST as frequently as every 5 seconds, providing a balanced trade-off between latency and situational awareness. If necessary, the minimum polling and push interval can be reduced to 1 second for real-time responsiveness.

1. Publish UAV

Endpoint: POST /v1/uav
Description:Publishes one or many UAV position to the SafeSky platform. Optionally, it's returning a list of nearby aircraft for each UAV position within a default radius of 10000 meters. This response will not include the UAV you have posted.

Use case: Submit one or multiple UAV positions and receive nearby air traffic in a single API call.

Request Headers:

  • Content-Type: application/json
  • x-api-key: <your_api_key>

Note:

  • UAVs that you have published in this POST are excluded from the response.
  • If your UAV is equipped with an ADS-B, FLARM, or ADS-L transponder, you must populate the icao24 field with the transponder's hexadecimal code. For more details, see the SafeSky FAQ.

Request Body:

Field Type Required Description
id string Yes Unique identifier for the UAV.
last_update long Yes The time of the event in seconds since epoch at UTC-0.
latitude double Yes Latitude in decimal degrees (4 decimal precision).
longitude double Yes Longitude in decimal degrees (4 decimal precision).
altitude int Yes Altitude of the UAV in AMSL meters. Use -9999 if altitude is unknown
ground_speed int Yes Ground speed of the UAV in meters per second.
course int Yes Direction of travel in degrees clockwise relative to true north.
status string Yes Current status of the UAV (INACTIVE, AIRBORNE, GROUNDED).

Query Parameters:

Parameter Type Required Description Default
alt_min int No Filter all aircraft below the given altitude in AMSL meters. Zero means 'unused'. 0
alt_max int No Filter all aircraft above the given altitude in AMSL meters. Zero means 'unused'. 0
return_nearby_traffic boolean No Return information about aircraft traffic within proximity of the UAV positions. false

Additional query Parameters when show_nearby_traffic = true:

Parameter Type Required Description Default
rad int No Radius distance in meters from all UAV reference point (maximum: 20000 meters). 10000
return_grounded_traffic boolean No Include grounded beacons. false

Response:

  • 201 CREATED: UAV published successfully; returns a list of nearby aircraft.
  • 400 BAD REQUEST: Invalid parameters or failed authentication.

Example 1: POST Request to submit 1 UAV position:

POST /v1/uav?altitude_min=1000&altitude_max=3000&radius=15000&return_nearby_traffic=true
Content-Type: application/json

[
    {
        "id": "UAV123",
        "status": "AIRBORNE",
        "altitude": 180,
        "course": 250,
        "ground_speed": 24,
        "latitude": 50.69378,
        "longitude": 4.39201,
        "call_sign": "FlyingFrog"
    }
]

Example 2: POST Request to submit multiple UAV position:

POST /v1/uav?altitude_min=1000&altitude_max=3000&radius=15000&return_nearby_traffic=true
Content-Type: application/json

[
    {
        "id": "UAV1",
        "altitude": 180,
        "latitude": 50.69378,
        "longitude": 4.39201
    },
    {
        "id": "UAV2",
        "altitude": 180,
        "latitude": 50.7,
        "longitude": 4.2
    },
    {
        "id": "UAV3",
        "altitude": 180,
        "latitude": 50.8,
        "longitude": 4.1
    },
    {
        "id": "UAV4",
        "altitude": 180,
        "latitude": 58.97969734871041, 
        "longitude": 5.754451051174314
    }
]

Example Response:

[
     {
        "latitude": 48.86584,
        "longitude": 2.63723,
        "beacon_type": "JET",
        "call_sign": "IBE06CK",
        "transponder_type": "ADS-B",
        "last_update": 1733412793,
        "altitude": 10554,
        "vertical_rate": 2,
        "accuracy": 0,
        "altitude_accuracy": 0,
        "course": 205,
        "ground_speed": 237,
        "turn_rate": 0.0,
        "status": "AIRBORNE",
        "id": "3423C3"
    },
    {
        "latitude": 48.95459,
        "longitude": 2.44153,
        "beacon_type": "JET",
        "call_sign": "NJE419F",
        "transponder_type": "ADS-B",
        "last_update": 1733412793,
        "altitude": 0,
        "vertical_rate": 0,
        "accuracy": 0,
        "altitude_accuracy": 0,
        "course": 292,
        "ground_speed": 0,
        "turn_rate": 0.0,
        "status": "GROUNDED",
        "id": "494105"
    }
]

2. Get Aircraft

Endpoint: GET /v1/uav

Description
Retrieve a list of aircraft traffic either within a circular radius around a reference point, or within a viewport rectangle (bounding box).

By default, the radius-based search uses 10,000 meters, with a maximum of 20,000 meters.

When using the viewport search, a maximum of 300 aircraft is returned. This limit is sufficient for map-based visualisation, even at low zoom levels.

Altitude filters are available in both modes.

Use case
Continuously fetch nearby traffic to visualise aircraft movements on a live or moving map.

Request Headers

  • x-api-key: <your_api_key>

Notes

  • If you have published UAVs via this API, they may appear in the response depending on the filters.
  • Search mode selection:
    • Use viewport to retrieve traffic inside a map bounding box (recommended for map-based UIs).
    • Otherwise, use lat + lng with rad for a circular proximity search.

Query Parameters

Parameter Type Required Description Default
lat double No Latitude in decimal degrees (4 decimal precision). Required for radius search. 0
lng double No Longitude in decimal degrees (4 decimal precision). Required for radius search. 0
viewport string No Bounding box to retrieve traffic, formatted as lat_min,lng_min,lat_max,lng_max (4 decimal precision is sufficient). —
alt_min int No Filter aircraft below the given altitude in AMSL meters. 0 means unused. 0
alt_max int No Filter aircraft above the given altitude in AMSL meters. 0 means unused. 0
rad int No Radius in meters from the reference point (maximum 20,000 m). Used only when viewport is not provided. 10000
show_grounded boolean No Include traffic with GROUNDED status if set to true. false

Response

  • 200 OK: Returns a list of nearby aircraft.
  • 400 BAD REQUEST: Invalid parameters or failed authentication.

Example 1: Radius-based request

GET /v1/uav?lat=48.8588&lng=2.2943&alt_min=1000&alt_max=3000&rad=15000

Example 2: Viewport-based request

GET /v1/uav?viewport=43.1035,-2.0821,47.9943,15.3216&alt_min=0&alt_max=5000&show_grounded=true

Example Response

[
  {
    "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"
  }
]
Back to top