Skip to main content

7 - 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 advisory beacons, 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

{
  "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"
}

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 RequiredType Description
timestamp —long long — Unix timestamp (seconds since epoch, UTC) for this status snapshot.
active —long long — Total number of currently active beacons.
inactive —long long — Total number of inactive beacons.
grounded —long long — Total number of grounded beacons.
beacon_counts —int int — Total number of beacons tracked by the network.
outdated_beacon_counts —int int — Total number of beacons with stale position data.
transponder_types —array array — Array of objects, each mapping a transponder type name to its count (e.g., {"ADS-B": 6200}).
beacon_types —array 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