Developer guide · Python · WebSocket

Low-latency China METAR push with Python WebSockets

Skyviewor actively pushes new METAR/SPECI reports from supported Chinese airports over WebSocket when they reach the service. Subscribe once instead of repeatedly polling HTTP. This Python client sends heartbeats, restores the latest state after a disconnect, and retries transient failures.

1. Run the stream

Use Python 3.11 or later. Download the complete WebSocket example script, install its dependencies and set your key as an environment variable. The command runs for three minutes; increase --seconds up to 3600 for a longer test.

Shell

python -m pip install httpx "websockets>=15"
export SKYVIEWOR_API_KEY="YOUR_API_KEY"
python china_metar_websocket.py --airports ZBAA,ZSPD --seconds 180

The client connects to wss://data.skyviewor.io/v1/ws/metar with the key in the Authorization header. It keeps one connection open for both airports. The same key can be used for the HTTP snapshot.

2. Distinguish health from a new report

Every 20 seconds, the script sends a JSON ping and waits up to 15 seconds for a pong. A heartbeat proves the connection is responding; it does not mean a new weather report exists. A new observation is delivered as a new_metar_arrived message such as this illustrative event:

Illustrative update

{"type":"new_metar_arrived","data":[{"icao":"ZBAA","raw_metar":"METAR ...","obs_time":"...","report_type":"METAR","arrived_at":"..."}]}

If the demo ends with only heartbeat lines, leave a longer test running or wait for an actual airport report. Do not count an idle but healthy stream as proof that an update arrived.

3. Recover after a disconnect

After a connection opens, the script calls /v1/metar/latest to restore the latest state. WebSocket messages can queue while that short HTTP request completes. Before each retry, the old reader and heartbeat tasks are cancelled and the old connection is closed. Retries are serial, use capped exponential backoff with jitter, and stop after eight interruptions or quota rejections.

Authentication failures (401/403) require a valid key or renewed access; the script stops instead of retrying them. A handshake 429 may mean another client is using one of the key's connection slots, including a briefly held lease from an abrupt disconnect. Check other clients sharing the key if the bounded retries fail.

For a first HTTP request and response example, see the Python METAR guide. Protocol details, connection limits and subscription operations are in the WebSocket reference.