Connect
Endpoint: wss://adsbiq.com/mqtt/. Use MQTT 5 or 3.1.1 over WebSockets, your feeder UUID as the username, and your ADSBiq API key as the password.
import os, paho.mqtt.client as mqtt
client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2,
protocol=mqtt.MQTTv5, transport="websockets")
client.username_pw_set(os.environ["ADSBIQ_FEEDER_UUID"],
os.environ["ADSBIQ_API_KEY"])
client.tls_set()
client.ws_set_options(path="/mqtt/")
client.connect("adsbiq.com", 443)
client.subscribe("adsbiq/v1/aircraft/+")
client.loop_forever()Retained delta topic model
Each current aircraft occupies one retained topic: adsbiq/v1/aircraft/<hex>. The JSON payload is a complete public state object, not a sparse patch. Only new or changed aircraft are republished. A zero-byte retained message is a tombstone: delete that hex from local state. Subscribe to adsbiq/v1/meta for protocol version, sequence, fleet total, and cycle change counts.
Bootstrap and recovery
A wildcard subscriber receives the broker's retained current fleet immediately, then changed topics at the bounded five-second publisher cadence. Treat the retained metadata sequence as observational rather than transactional; reconnect and rebuild from retained topics after a prolonged disconnect. Topic state persists across broker restarts.
Safety and limits
Feeder identities are read-only and may access only adsbiq/v1/#; the internal publisher is write-only. Anonymous access is disabled. The publisher is capped at 2,500 aircraft, individual MQTT packets at 64 KiB, broker connections at 100, and WebSocket connections at five per source IP. Delivery uses QoS 0 because newer real-time state supersedes older state.
Credential handling
Keep the API key in an environment variable or secret store. Never put it in a URL, source file, browser storage, or logs. A five-minute production synchronizer hashes active feeder credentials into Mosquitto's password file and regenerates least-privilege ACLs atomically.
Troubleshooting
- Authentication failure: verify both feeder UUID and API key.
- No initial data: confirm the subscription includes retained messages and uses
adsbiq/v1/aircraft/+. - Unexpected disappearance: process zero-byte retained tombstones.
- For one-second geographic updates, use the WebSocket API instead.