Skip to main content

# Model Definition

This page describes the data models returned and accepted by the SafeSky Public REST API.

1. Beacon Model

The Beacon model defines the structure of an aircraft position as provided by or submitted to the SafeSky network, based on the ADS-BI protocol.

Fields

Field Type Required Description
id string Yes The unique identifier of the beacon (e.g., ICAO 24-bit hex address or SafeSky-assigned ID).
latitude double Yes Latitude in decimal degrees.
longitude double Yes Longitude in decimal degrees.
altitude int Yes Height of the beacon in meters, based on GPS altitude AMSL.
course int Yes Direction of travel in degrees, clockwise relative to true north (0–359).
ground_speed int Yes Current ground speed in meters per second.
last_update long No Time of the event in seconds since epoch (UTC). Minimum value: 1.
status string No Current operational status of the beacon. See Status Values.
beacon_type string No Aircraft category. See Beacon Types.
transponder_type string No Technology used to broadcast the position. See Transponder Types.
call_sign string No Beacon call sign. Only present if the pilot has a public profile.
vertical_rate int No Vertical rate in m/s. Positive values indicate climbing; negative values indicate descending.
accuracy int No Accuracy level of the latitude and longitude coordinates, in meters.
altitude_accuracy int No Accuracy level of the altitude coordinate, in meters.
turn_rate float No Turn rate in degrees per second.
remarks string No Free-text comments (maximum 255 characters).
operation_area string No For beacons with activity status, a GeoJSON string representing the declared area of activity.

Status Values

The status field reflects the current operational state of a beacon:

Value Description
AIRBORNE The beacon is in flight.
GROUNDED The beacon is on the ground (taxiing, parked, or pre-flight).
INACTIVE The beacon has not transmitted recently and is considered inactive.
SAR Search and rescue operation.

Example Beacon Object (Verbose Format)

{
  "id": "3423C3",
  "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,
  "vertical_rate": 2,
  "accuracy": 0,
  "altitude_accuracy": 0,
  "turn_rate": 0.0,
  "status": "AIRBORNE"
}

Example Beacon Object (Optimised Format)

When the GET /v1/beacons endpoint is called with optimised=true, each beacon is returned as a compact JSON array. The element order corresponds to the field sequence of the verbose model, reducing payload size for high-density viewports.

["3423C3", 1733412793, 0, "AIRBORNE", 48.86584, 2.63723, "IBE06CK", "ADS-B", 10554, 2, 0, 205, 237, 0.0, null, null, "JET"]

Use the verbose format during development for readability. Use optimised=true in production to reduce bandwidth consumption.

2. Status Model

The Status model is returned by the GET /v1/stats/overview endpoint. It provides a snapshot of the current state of the SafeSky network.

Fields

Field Type Description
timestamp long Unix timestamp (seconds since epoch, UTC) for this status snapshot.
active long Total number of currently active beacons.
inactive long Total number of inactive beacons.
grounded long Total number of grounded beacons.
beacon_counts int Total number of beacons tracked by the network.
outdated_beacon_counts int Total number of beacons with stale position data.
transponder_types array Array of objects, each mapping a transponder type name to its count (e.g., {"ADS-B": 6200}).
beacon_types array Array of objects, each mapping an aircraft category to its count (e.g., {"JET": 3200}).

Example Status Object

{
  "timestamp": 1733412793,
  "active": 12540,
  "inactive": 430,
  "grounded": 87,
  "beacon_counts": 13057,
  "outdated_beacon_counts": 212,
  "transponder_types": [
    { "ADS-B": 6200 },
    { "ADS-BI": 4100 },
    { "FLARM": 1800 },
    { "OGN": 740 },
    { "MODE-S": 217 }
  ],
  "beacon_types": [
    { "JET": 3200 },
    { "MOTORPLANE": 2100 },
    { "HELICOPTER": 980 },
    { "GLIDER": 870 },
    { "UAV": 430 },
    { "PARA_GLIDER": 215 },
    { "BALLOON": 47 }
  ]
}

Altitude Reference

All altitude values in the SafeSky Public REST API are expressed in meters AMSL (Above Mean Sea Level), derived from GPS altitude.

Coordinate System

All geographic coordinates use the WGS84 datum:

  • latitude: decimal degrees, positive = North, negative = South
  • longitude: decimal degrees, positive = East, negative = West
  • 4 decimal places of precision are sufficient for all API calls (~11 meters resolution)
Back to top