API Documentation

Authentication

Every feeder gets a unique API key. Use it from any IP — your laptop, VPS, phone, scripts.

curl -H "Authorization: Bearer YOUR_API_KEY" https://adsbiq.com/api/v2/all

Your API key is shown on the join page and your feeder dashboard after install.

curl https://adsbiq.com/api/v2/all

Not a feeder? Install in 60 seconds to get access.

Connection

Channels

The WebSocket serves three channels on the same endpoint — the VDL2 datalink stream (our priority) plus two ADS-B position channels. Choose based on your use case:

# Python: subscribe to the live VDL2 stream
import asyncio, json, websockets
async def main():
    async with websockets.connect("wss://adsbiq.com/ws/?channel=vdl2") as ws:
        async for frame in ws:
            for m in json.loads(frame).get("messages", []):
                print(m["timestamp"], m.get("tail"), m.get("label"), m.get("text"))
asyncio.run(main())

Breaking change: The default (global) channel now updates every 10s instead of 1s. If you need 1-second updates, switch to zone mode by adding ?lat=X&lon=Y to your connection URL.

Client Messages

Clients can switch channels mid-session by sending JSON messages:

Message Types

The first message after connect is a full snapshot. Subsequent messages are deltas containing only changes. Every message includes a channel field ("global" or "zone").

Full Snapshot

{
  "type": "full",
  "channel": "zone",
  "seq": 42,
  "now": 1774187176.0,
  "messages": 6505606,
  "total": 51,
  "ctime": 1774187176.3,
  "ptime": 1774187175.9,
  "ac": [ ... ]
}

Delta Update

{
  "type": "delta",
  "channel": "zone",
  "seq": 43,
  "now": 1774187177.0,
  "messages": 6505620,
  "total": 52,
  "ctime": 1774187177.3,
  "ptime": 1774187176.9,
  "new": [
    {"hex": "c99aab", "flight": "SWA789  ", "lat": 42.0, "lon": -72.0, "alt_baro": 30000, ...}
  ],
  "update": [
    {"hex": "ad5d5c", "lat": 26.3, "alt_baro": 34000}
  ],
  "remove": ["a1b2c3"]
}

Delta Fields

Client-Side Merge Pattern

update objects are sparse — they contain only hex plus fields that actually differ from the previous message. Merge them into your local state, do not replace:

// JavaScript — global channel (10s updates, all aircraft)
const ws = new WebSocket("wss://adsbiq.com/ws/");

// JavaScript — zone channel (1s updates, 250nm radius)
// const ws = new WebSocket("wss://adsbiq.com/ws/?lat=40.7&lon=-74.0");

const aircraft = {};
let lastSeq = 0;

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);

  // Sequence gap detection — reconnect if we missed a frame
  if (msg.type === "delta" && msg.seq !== lastSeq + 1) {
    ws.close(); // reconnect logic will get a fresh full
    return;
  }
  lastSeq = msg.seq;

  if (msg.type === "full") {
    for (const k in aircraft) delete aircraft[k];
    for (const ac of msg.ac) aircraft[ac.hex] = ac;
  } else {
    for (const ac of msg.new    || []) aircraft[ac.hex] = ac;
    for (const ac of msg.update || []) Object.assign(aircraft[ac.hex], ac);
    for (const hex of msg.remove || []) delete aircraft[hex];
  }

  // Consistency check — total must match local state
  if (Object.keys(aircraft).length !== msg.total) {
    ws.close(); // state drift — reconnect for fresh full
  }
};

// Switch to zone mid-session:
// ws.send(JSON.stringify({action: "set_zone", lat: 40.7, lon: -74.0}));

// Switch back to global:
// ws.send(JSON.stringify({action: "set_global"}));

Trigger Fields

Deltas are triggered by changes to: lat, lon, alt_baro, alt_geom, gs, ias, tas, mach, track, track_rate, roll, mag_heading, true_heading, baro_rate, geom_rate, squawk, emergency, flight, nav_qnh, nav_altitude_mcp, nav_altitude_fms, nav_heading, category, r, t, route_origin, route_dest.

Volatile fields (rssi, seen, seen_pos, messages) alone do not trigger an update, but are included in the sparse object if they changed alongside a trigger field.

Example Code

Get started quickly with a working Flask demo that queries every endpoint:

git clone https://github.com/adsbiq/adsbiq-api-demo.git
cd adsbiq-api-demo
pip install -r requirements.txt
python app.py

View on GitHub — includes REST and WebSocket examples.