Map an ADS-B Aircraft Report

Automatic Dependent Surveillance—​Broadcast (ADS-B) lets aircraft broadcast their identity, position, altitude, and velocity for tracking. This example maps an aircraft snapshot to an Object in [R]DP. Position and motion support map display, while aviation fields preserve airspeed, guidance settings, surveillance quality, and transponder status for consumers that need them.

Source data

A snapshot collects values from several radio messages into one aircraft record. This input combines direct ADS-B and Mode S messages from the aircraft’s transponder, its surveillance radio. addressType: "icao" and surveillanceSource: "adsb_icao_transponder" distinguish this source from rebroadcast or calculated positions.

Coordinates use WGS-84, the geographic reference used by GPS. This example assumes all supplied measurements are valid and current at observedAt. The readsb field reference describes comparable measurements.

WDM uses meters for altitude and meters per second for airspeed, ground speed, and climb rate.

{
  "icao24": "a1b2c3",
  "addressType": "icao",
  "surveillanceSource": "adsb_icao_transponder",
  "callsign": "DEMO123",
  "latitudeDegrees": 38.0,
  "longitudeDegrees": -77.0,
  "barometricAltitudeFeet": 30000.0,
  "groundSpeedKnots": 250.0,
  "trackDegreesTrue": 90.0,
  "barometricVerticalRateFeetPerMinute": 640.0,
  "geometricAltitudeHaeFeet": 30100.0,
  "trueHeadingDegrees": 88.0,
  "magneticHeadingDegrees": 98.0,
  "rollDegrees": 2.0,
  "trackRateDegreesPerSecond": 0.2,
  "geometricVerticalRateFeetPerMinute": 608.0,
  "indicatedAirspeedKnots": 220.0,
  "trueAirspeedKnots": 280.0,
  "mach": 0.47,
  "altimeterSettingHpa": 1013.25,
  "selectedAltitudeMcpFeet": 32000.0,
  "selectedAltitudeFmsFeet": 34000.0,
  "selectedHeadingDegrees": 95.0,
  "selectedHeadingReference": "magnetic",
  "navigationModesValid": true,
  "navigationModes": [
    "autopilot",
    "vnav",
    "lnav"
  ],
  "adsbVersion": 2,
  "emitterCategory": "A3",
  "adsbQuality": {
    "nic": 8,
    "nicBaro": 1,
    "nacP": 9,
    "nacV": 2,
    "sil": 3,
    "silBasis": "per_hour",
    "gva": 2,
    "sda": 2
  },
  "horizontalContainmentRadiusMeters": 185.2,
  "acasOperational": true,
  "squawk": "1200",
  "alert": false,
  "specialPositionIdentification": true,
  "emergency": "none",
  "verticalMode": "climbing",
  "observedAt": "2026-10-01T12:00:00Z",
  "receivedAt": "2026-10-01T12:00:02Z",
  "reportId": "adsb-report-001"
}

Identity and position

The ICAO 24-bit address is the aircraft’s radio identifier under the International Civil Aviation Organization’s scheme. Using it as the Object’s identity connects successive positions to one aircraft. Separate altitude fields preserve how height was measured, because pressure, sea level, ground level, and Earth’s modeled surface give different values.

Source WDM field Explanation

icao24: "a1b2c3"

id, identities, transponderCodes.modeSAddress

The address gives every observation of this aircraft the same ID, mode_s:A1B2C3. Uppercase letters give differently cased inputs the same identity.

callsign

name, typeInfo.aviation.flightNumber

DEMO123 is the display name and flight identifier; it can change without creating another aircraft Object.

Declared direct ADS-B ICAO source

typeInfo.aviation.surveillanceSource

AVIATION_SURVEILLANCE_SOURCE_ADSB_ICAO identifies direct broadcasts from an ICAO-addressed transponder. It does not identify which sensor measured the position.

Latitude and longitude

location.position

Valid latitude and longitude copy directly into the map position.

barometricAltitudeFeet

location.position.altitudePressureMeters

Pressure altitude uses standard atmospheric pressure, keeping it separate from geometric height and the selected altimeter setting.

geometricAltitudeHaeFeet

location.position.altitudeHaeMeters

Height above ellipsoid (HAE) uses Earth’s modeled reference surface; it differs from height above sea level or ground.

horizontalContainmentRadiusMeters: 185.2

location.positionIntegrity.horizontalContainmentRadiusMeters

This radius bounds position error under the source’s integrity definition. Keeping it separate from geometry prevents treating it as the aircraft’s physical size.

ONTOLOGY_CATEGORY_PLATFORM classifies the aircraft as a vehicle. Registration, model, and affiliation stay unset because the source supplies none; its broad emitter category does not establish them.

The source supplies no SIDC (Symbol Identification Code) or agreed military symbol mapping, so symbology stays unset.

Motion and airspeed

Course over ground is the direction of travel; heading is where the nose points. Wind can make them differ. True heading uses geographic north, while magnetic heading uses compass north.

Indicated airspeed is the instrument reading; true airspeed measures motion through the air, and ground speed measures motion over Earth. WDM keeps these distinct.

Source WDM field Explanation

groundSpeedKnots, trackDegreesTrue

motion.speedMps, motion.courseOverGroundDegrees

Ground speed and course describe the aircraft’s movement across Earth’s surface.

trackRateDegreesPerSecond: 0.2

motion.courseRateDegreesPerSecond

The course changes clockwise at 0.2 degrees per second; the sign preserves the turn direction.

trueHeadingDegrees: 88, magneticHeadingDegrees: 98, rollDegrees: 2

location.orientation.headingDegrees, magneticHeadingDegrees, rollDegrees

The two headings retain their north references. Roll describes the bank angle; positive 2 degrees means right wing down.

Barometric and geometric vertical rates

motion.barometricVerticalRateMps, motion.geometricVerticalRateMps

Separate fields retain which altitude measurement produced each climb rate. Positive values mean climbing.

Indicated and true airspeeds

typeInfo.aviation.indicatedAirspeedMps, trueAirspeedMps

These aviation fields distinguish the instrument’s indicated airspeed from true airspeed and ground speed.

mach: 0.47, verticalMode: "climbing"

typeInfo.aviation.mach, verticalMode

Mach describes speed relative to the local speed of sound. The reported vertical mode corresponds to VERTICAL_MODE_CLIMBING.

Guidance and transponder status

Guidance fields hold selected targets and automation modes, letting clients distinguish measured flight from what the aircraft’s controls are set to do. The Mode Control Panel or Flight Control Unit (MCP/FCU) supplies cockpit selections; the Flight Management System (FMS) supplies flight-computer selections.

Source WDM field Explanation

altimeterSettingHpa

typeInfo.aviation.altimeterSettingHpa

The pressure setting stays separate from reported altitude because it describes the altimeter’s configuration.

Selected MCP and FMS altitudes

typeInfo.aviation.selectedAltitudes[]

Source labels distinguish cockpit selections from flight-computer targets.

Selected heading 95, reference "magnetic"

typeInfo.aviation.selectedLateralTarget

The angle, target type, and north reference describe a selected heading of 95 degrees magnetic. A heading target differs from a selected direction of travel, which uses TRACK_ANGLE.

Valid modes "autopilot", "vnav", "lnav"

typeInfo.aviation.navigationStatus

The reported modes map to WDM’s autopilot, vertical-navigation (VNAV), and lateral-navigation (LNAV) values. valid: true tells clients these indicators are usable.

squawk: "1200"

transponderCodes.mode3a

A squawk is a code used by air traffic control, written in base eight (octal). It stays separate from the aircraft address.

alert: false, specialPositionIdentification: true

transponderCodes.alert, specialPositionIdentification

false explicitly reports no alert, while true reports the identification indicator active. Both carry information.

emergency: "none"

typeInfo.aviation.emergency

EMERGENCY_STATUS_NONE reports a known absence of emergency; an unknown status remains unspecified.

An unknown heading reference stays unspecified because the angle alone cannot establish it. For navigation status, valid: true with no active modes means all modes are inactive; valid: false means clients ignore the modes. Omitted validity is unknown.

ADS-B quality

Quality fields let clients judge position and motion beyond the measurements themselves. Accuracy describes estimated measurement error; integrity describes the risk of an error exceeding its stated bound. These are ADS-B categories, so the mapping preserves their codes and version rather than treating them as distances or percentages.

Version 2 and emitter category A3, a broad aircraft classification, populate typeInfo.aviation.adsb.version and emitterCategory. The paths below are within typeInfo.aviation.adsb.quality:

Source WDM field Explanation

nic: 8, nicBaro: 1

navigationIntegrityCategory, barometricAltitudeIntegrityCategory

The position and barometric-altitude integrity indicators remain separate, with values 8 and 1.

nacP: 9, nacV: 2

navigationAccuracyCategoryPosition, navigationAccuracyCategoryVelocity

Values 9 and 2 describe position and velocity accuracy; one cannot substitute for the other.

sil: 3, silBasis: "per_hour"

sourceIntegrityLevel, sourceIntegrityBasis

Level 3 keeps its hourly basis, ADSB_SOURCE_INTEGRITY_BASIS_PER_HOUR, so clients can interpret the probability correctly.

gva: 2

geometricVerticalAccuracy

Value 2 describes geometric-altitude accuracy separately from horizontal accuracy.

sda: 2

systemDesignAssurance

Value 2 describes assurance against system failures affecting the reported data.

Time and source retention

observedAt supplies provenance.updatedAt, while receivedAt supplies externalRefs[].capturedAt. The expiry timestamp, ttl, is observation time plus 60 seconds, so delivery delay does not extend validity. A Struct, a protobuf container for JSON-like fields, retains the complete source JSON; original radio-message bytes are unavailable.

WDM Object

The record uses ProtoJSON, protobuf’s JSON representation:

{
  "id": "mode_s:A1B2C3",
  "security": {
    "raw": "UNCLASSIFIED",
    "components": {
      "classification": "UNCLASSIFIED",
      "ownerProducer": [
        "USA"
      ]
    }
  },
  "identities": [
    {
      "system": "mode_s",
      "identifier": "A1B2C3"
    }
  ],
  "flags": {
    "isSimulated": true
  },
  "status": "OBJECT_STATUS_ACTIVE",
  "ttl": "2026-10-01T12:01:00Z",
  "provenance": {
    "id": "adsb-report-001",
    "name": "ADS-B demo source",
    "updatedAt": "2026-10-01T12:00:00Z",
    "producer": "example-adsb-adapter-v1"
  },
  "name": "DEMO123",
  "ontology": {
    "category": "ONTOLOGY_CATEGORY_PLATFORM"
  },
  "typeInfo": {
    "aviation": {
      "flightNumber": "DEMO123",
      "surveillanceSource": "AVIATION_SURVEILLANCE_SOURCE_ADSB_ICAO",
      "emergency": "EMERGENCY_STATUS_NONE",
      "verticalMode": "VERTICAL_MODE_CLIMBING",
      "altimeterSettingHpa": 1013.25,
      "selectedAltitudes": [
        {
          "altitudeMeters": 9753.6,
          "source": "SELECTED_ALTITUDE_SOURCE_MCP_FCU"
        },
        {
          "altitudeMeters": 10363.2,
          "source": "SELECTED_ALTITUDE_SOURCE_FMS"
        }
      ],
      "selectedLateralTarget": {
        "angleDegrees": 95.0,
        "type": "SELECTED_LATERAL_TARGET_TYPE_HEADING",
        "reference": "SELECTED_LATERAL_TARGET_REFERENCE_MAGNETIC_NORTH"
      },
      "navigationStatus": {
        "activeModes": [
          "AVIATION_NAVIGATION_MODE_AUTOPILOT",
          "AVIATION_NAVIGATION_MODE_VERTICAL_NAVIGATION",
          "AVIATION_NAVIGATION_MODE_LATERAL_NAVIGATION"
        ],
        "valid": true
      },
      "adsb": {
        "version": 2,
        "emitterCategory": "A3",
        "quality": {
          "navigationIntegrityCategory": 8,
          "barometricAltitudeIntegrityCategory": 1,
          "navigationAccuracyCategoryPosition": 9,
          "navigationAccuracyCategoryVelocity": 2,
          "sourceIntegrityLevel": 3,
          "sourceIntegrityBasis": "ADSB_SOURCE_INTEGRITY_BASIS_PER_HOUR",
          "geometricVerticalAccuracy": 2,
          "systemDesignAssurance": 2
        },
        "acasOperational": true
      },
      "indicatedAirspeedMps": 113.17777777777778,
      "trueAirspeedMps": 144.04444444444445,
      "mach": 0.47
    }
  },
  "transponderCodes": {
    "modeSAddress": 10597059,
    "mode3a": 640,
    "alert": false,
    "specialPositionIdentification": true
  },
  "location": {
    "position": {
      "latitudeDegrees": 38.0,
      "longitudeDegrees": -77.0,
      "altitudePressureMeters": 9144.0,
      "altitudeHaeMeters": 9174.48
    },
    "orientation": {
      "headingDegrees": 88.0,
      "rollDegrees": 2.0,
      "magneticHeadingDegrees": 98.0
    },
    "positionIntegrity": {
      "horizontalContainmentRadiusMeters": 185.2
    }
  },
  "motion": {
    "speedMps": 128.61111111111111,
    "courseOverGroundDegrees": 90.0,
    "barometricVerticalRateMps": 3.2512,
    "geometricVerticalRateMps": 3.08864,
    "courseRateDegreesPerSecond": 0.2
  },
  "externalRefs": [
    {
      "typeUrl": "type.googleapis.com/google.protobuf.Struct",
      "externalId": "adsb-report-001",
      "sourceSystem": "adsb-demo-source",
      "payload": {
        "@type": "type.googleapis.com/google.protobuf.Struct",
        "value": {
          "@type": "com.example.mapping.v1.DecodedSourceRecord",
          "value": {
            "format": "ADS-B",
            "profile": "Direct ADS-B ICAO aircraft snapshot with Mode S avionics data; normalized fixture contract",
            "mediaType": "application/json",
            "representation": "decoded_record",
            "originalWireDataAvailable": false,
            "record": {
              "icao24": "a1b2c3",
              "addressType": "icao",
              "surveillanceSource": "adsb_icao_transponder",
              "callsign": "DEMO123",
              "latitudeDegrees": 38.0,
              "longitudeDegrees": -77.0,
              "barometricAltitudeFeet": 30000.0,
              "groundSpeedKnots": 250.0,
              "trackDegreesTrue": 90.0,
              "barometricVerticalRateFeetPerMinute": 640.0,
              "geometricAltitudeHaeFeet": 30100.0,
              "trueHeadingDegrees": 88.0,
              "magneticHeadingDegrees": 98.0,
              "rollDegrees": 2.0,
              "trackRateDegreesPerSecond": 0.2,
              "geometricVerticalRateFeetPerMinute": 608.0,
              "indicatedAirspeedKnots": 220.0,
              "trueAirspeedKnots": 280.0,
              "mach": 0.47,
              "altimeterSettingHpa": 1013.25,
              "selectedAltitudeMcpFeet": 32000.0,
              "selectedAltitudeFmsFeet": 34000.0,
              "selectedHeadingDegrees": 95.0,
              "selectedHeadingReference": "magnetic",
              "navigationModesValid": true,
              "navigationModes": [
                "autopilot",
                "vnav",
                "lnav"
              ],
              "adsbVersion": 2,
              "emitterCategory": "A3",
              "adsbQuality": {
                "nic": 8,
                "nicBaro": 1,
                "nacP": 9,
                "nacV": 2,
                "sil": 3,
                "silBasis": "per_hour",
                "gva": 2,
                "sda": 2
              },
              "horizontalContainmentRadiusMeters": 185.2,
              "acasOperational": true,
              "squawk": "1200",
              "alert": false,
              "specialPositionIdentification": true,
              "emergency": "none",
              "verticalMode": "climbing",
              "observedAt": "2026-10-01T12:00:00Z",
              "receivedAt": "2026-10-01T12:00:02Z",
              "reportId": "adsb-report-001"
            }
          }
        }
      },
      "capturedAt": "2026-10-01T12:00:02Z",
      "label": "Decoded ADS-B aircraft snapshot"
    }
  ]
}

See Model a Tracked Platform for the aviation field overview, and Publish Object for how to send this record.