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