Read aircraft.json without fooling yourself

A snapshot is not a flight history

A decoder's aircraft.json describes recently known aircraft at a particular snapshot time. It is not automatically a complete history or an authoritative record of every aircraft nearby. Readsb documents the timestamp, fields and their units; implementations and versions differ. [1]

Begin with the current specification for the producer you actually use. An attractive example from another API is not a schema. Keep raw input separate from your interpretation, especially when you are building charts or forwarding data.

A deliberately invented example

{
  "now": 1700000000,
  "aircraft": [{
    "hex": "abcdef",
    "type": "adsb_icao",
    "lat": 53.4,
    "lon": -6.2,
    "seen_pos": 2,
    "seen": 0.4,
    "alt_baro": 12000,
    "gs": 230
  }]
}

This is synthetic data, not a recorded flight. Its fixed timestamp is deliberately old. The interactive inspector can generate a separate synthetic example stamped at the time you click.

In the documented readsb format, now is a Unix time in seconds. Position age is relative to that snapshot, not relative to the moment you happen to open the file. seen describes the last message; seen_pos describes the last position update. [1]

Keep units and absence visible

Use the producer's field definitions. Do not convert a missing coordinate to zero. Do not turn a missing altitude into "on the ground." A valid zero and an absent value must remain different in your code.

Readsb's barometric altitude field uses feet and can contain the string ground. Ground speed uses knots. Geometric and barometric altitude use different references; neither field should casually be labelled height above the viewer's garden. [1]

Store units and conversion decisions alongside derived values. Keep a named "unknown" state in the interface. A blank field with a good explanation is more honest than a precise-looking number manufactured from a default.

Age the observation, not the upload

For a well-formed snapshot, a useful diagnostic calculation is:

position_age_now = inspection_time - snapshot_time + seen_pos

All three time quantities must use seconds and compatible clock references. A future snapshot timestamp is a clock or input warning, not fresh data by definition. A recent snapshot can contain an older position.

Our inspector labels a user-chosen freshness threshold. It does not duplicate Skylark's server validation or any other network's full acceptance policy. It also flags mixed-source fields rather than pretending that a source label proves a pure local observation.

Build consumers that explain themselves

Keep observed, calculated and enriched fields distinct. Record the original timestamp and source rather than flattening everything into a single "live aircraft" object. When data becomes stale, say so and stop treating it as current.

For an exported graph, include the observation interval, units, local or aggregated source, excluded records and gaps. For a prediction, keep the prediction time and uncertainty separate from the last observation. A curve that looks smooth is not a validation method.

Use pyModeS and The 1090 Megahertz Riddle when you want to work below the JSON layer. Inspecting a decoder's JSON and decoding radio messages are different projects. [2] [3]