WebSocket Real-Time API

​

Connection

wss://api.sportsapipro.com/v2/football/ws?x-api-key=YOUR_API_KEY

​

Authentication

• Query string (recommended for browser clients): ?x-api-key=YOUR_API_KEY
• Header: x-api-key: YOUR_API_KEY

​

Sport Selection

​

Message Format

{ "action": "subscribe", "channel": "live-scores" }
{ "action": "subscribe", "channel": "match:14109842" }
{ "action": "subscribe", "channel": "match:14109842:incidents" }
{ "action": "unsubscribe", "channel": "match:14109842" }
{ "action": "ping", "channel": "live-scores" }

​

Available Channels

​

Delivery Modes

• NATS push — Data is pushed directly from the real-time feed with no delay
• NATS-triggered fetch — When any match update is detected, detailed data is fetched instantly (no waiting for poll cycle)
• Polling — Data is fetched at regular intervals (used for lineups which rarely change)

​

No updates received?

1. Confirm the match is actually in progress with GET /v2/{sport}/live. This is the authoritative liveness source. The schedule endpoint lists a whole day of fixtures with a status snapshot, so a fixture you read there may already have finished — a finished match emits nothing on match:{matchId} or on live-scores.
2. Check the sport in the welcome frame. live-scores is scoped to it. Connecting on /v2/{sport}/ws sets the scope automatically; the subscribed frame confirms it as live-scores:{sport}.
3. Expect quiet gaps. Frames are emitted on change only. Between deliveries, at a wicket break, at half-time or during a rain delay, a genuinely live match can be silent for a minute or more. Test against a sport-wide live-scores subscription rather than one fixture.
4. Check natsConnected in the welcome frame. If it is false, push channels fall back to their safety-net poll cadence.
5. De-duplicate on changes.changeTimestamp. A single change can arrive two to three times on match:{matchId}, plus once more on live-scores — that is expected, not a bug.

​

What’s delivered on :incidents

​

Response Types

​

welcome

{
  "type": "welcome",
  "message": "SportsAPIData WebSocket v3.1 — All Channels Sub-Second",
  "sport": "football",
  "natsConnected": true,
  "channels": ["live-scores", "match:{matchId}", "..."]
}

​

subscribed

{
  "type": "subscribed",
  "channel": "match:14109842:incidents",
  "mode": "realtime (NATS-triggered fetch, 15000ms safety-net poll)"
}

​

snapshot

{
  "channel": "match:14109842",
  "type": "snapshot",
  "data": { ... },
  "timestamp": 1710729600000
}

​

update

{
  "channel": "match:14109842:incidents",
  "type": "update",
  "data": { ... },
  "source": "nats",
  "timestamp": 1710729600437
}

​

pong

{
  "type": "pong",
  "channel": "live-scores",
  "timestamp": 1710729600000
}

​

Quick Start Examples

const ws = new WebSocket('wss://api.sportsapipro.com/v2/football/ws?x-api-key=YOUR_API_KEY');

ws.onopen = () => {
  // Subscribe to all live football scores
  ws.send(JSON.stringify({ action: 'subscribe', channel: 'live-scores' }));

  // Subscribe to a specific match's incidents (goals, cards, subs)
  ws.send(JSON.stringify({ action: 'subscribe', channel: 'match:14109842:incidents' }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(`[${msg.type}] ${msg.channel}:`, msg.data);
};

import websockets, asyncio, json

async def connect():
    uri = "wss://api.sportsapipro.com/v2/football/ws?x-api-key=YOUR_API_KEY"
    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({"action": "subscribe", "channel": "live-scores"}))
        async for message in ws:
            data = json.loads(message)
            print(f"[{data['type']}] {data.get('channel', '')}")

asyncio.run(connect())

wscat -c "wss://api.sportsapipro.com/v2/football/ws?x-api-key=YOUR_API_KEY"
> {"action":"subscribe","channel":"live-scores"}
> {"action":"subscribe","channel":"match:14109842:incidents"}
> {"action":"ping","channel":"live-scores"}

​

Best Practices