API Docs

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://api.adsbiq.com/v2/messages/recent

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

Alternative: IP-based auth (no key needed from home network)

Requests from your feeder's IP are automatically authenticated — no header needed:

curl https://api.adsbiq.com/v2/messages/recent

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

Access Tiers

Live data is earned by feeding. Bulk data is free to everyone, always. New here? You get a 3-day full-access trial — then feed to keep the fast lane.

Tier	Who	REST	Live WebSocket
Trial	New user, first 3 days	1 / 20s	2s push
Free	After trial, not feeding	1 / 5 min	150s push
Contributor	Active datalink feeder	1 / 20s	2s push (0.5 Hz)

Each tier also has a fair-use daily data budget. Exceeding a limit returns 429 with a Retry-After header; the response points you to the WebSocket (far lighter than polling) or the free bulk download.

📦 Bulk / research use? The complete dataset is published free, once daily as Parquet — no account, no limits: vdlIQ open data. For most non-realtime use cases it's the better fit anyway.

Feed in 60 seconds to unlock the contributor stream.

📡 Looking for the ADS-B API? It lives on our sister site — full docs at ADSBiq (adsbiq.com/api/docs) ↗

🛰️ VDL2 — Datalink Messages (REST) our priority

What aircraft are saying — OOOI, position, weather, intent. A different shape from position data: timestamped text messages, not lat/lon.

Status: live. VDL2 ingest runs on feed.adsbiq.com:5552 and the read endpoints below serve a hot recent-message window (newest first). Same auth and rate limits as the aircraft API. Want to feed VDL2? See /vdl2.

Endpoints

GET

/v2/messages/recent

The live tail across all aircraft, newest first. Query: ?limit={1-1000}, ?since={unix|ISO-8601}.

GET

/v2/messages/tail/{reg}

Recent datalink messages for an aircraft registration (e.g. N827NN).

GET

/v2/messages/hex/{icao}

Recent messages by ICAO hex (e.g. a12345).

GET

/v2/messages/label/{label}

Messages by ACARS label (e.g. 5Z OOOI, 15 weather). Query: ?since=, ?until=, ?limit=.

GET

/v2/messages/stats

Live volume snapshot: global and per-feeder messages/min, active VDL2 feeder count.

Deep history. The endpoints above serve a hot recent window. Add ?history=1 (with ?since=/?until=) to scan the archived message store instead — bounded, newest-first, with "mode":"archive" and a "truncated" flag when the scan hits its cap.

Example

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.adsbiq.com/v2/messages/recent?limit=20"

# -> { "messages": [ … ], "count": 20, "source": "vdl2" }

Message schema

Each record is the canonical, lossless form written at ingest:

{
  "uuid": "…",                 // globally unique message id
  "timestamp": 1717761600.25,  // unix seconds (UTC)
  "sourceType": "VDL2",
  "icaoHex": "ac2bb1",         // aircraft ICAO address
  "tail": "N827NN",            // registration
  "flightNumber": "AAL1234",
  "label": "H1",               // ACARS label
  "blockId": "4", "msgNum": "M62A", "ack": "!",
  "text": "ENG RPT N1 95.2 EGT 612",
  "frequency": 136975000,      // Hz
  "level": -19.7,              // signal level (dBFS)
  "contentHash": "…"           // receiver-independent dedup key
}
// Receiving-feeder identity (IP / station id) is never exposed — operator privacy.

Backed by the S3 + local-NVMe parquet archive (no Postgres). Coverage and history queries read the canonical parquet; the endpoints above will serve recent windows with low latency.

WebSocket Feed

Real-time push-based aircraft data — no polling needed

Connection

Endpoint	`wss://api.adsbiq.com/ws/`
Auth	IP-based (same as REST API) or Bearer token via query: `wss://api.adsbiq.com/ws/?token=YOUR_API_KEY`
Compression	permessage-deflate (negotiated automatically)
Ping/Pong	Server sends ping every 30s, timeout 10s
Max message size	512 bytes (client → server)

Channels

Subscribe to the live VDL2 datalink channel:

Channel	Interval	Coverage	How to connect
🛰️ VDL2 PRIORITY	Real-time (pushed as decoded)	Live VDL2/ACARS datalink messages from aircraft	`wss://api.adsbiq.com/ws/?channel=vdl2`

The VDL2 channel is unique: a live, compressed (permessage-deflate) stream of decoded aircraft datalink messages — OOOI, position, weather — pushed the moment they're decoded. First frame is {"type":"vdl2_snapshot", "messages":[…]} (recent, oldest-first); thereafter {"type":"vdl2", "messages":[…]} as new messages arrive. Each message is the canonical record (tail, flightNumber, label, text, icaoHex, frequency, level, timestamp); receiver identity (IP/station) is never included. Same feeder auth as the other channels.

# Python: subscribe to the live VDL2 stream
import asyncio, json, websockets
async def main():
    async with websockets.connect("wss://api.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())

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.

API Documentation