Skip to content

Livematches in play

Demo: Matchboard, opens in a new tab

Live now matches in play

Real-time delivery · WebSocket · Webhooks

A real-time sports data API that pushes every change

The DataSportsAPI real-time sports data feed reaches you in two ways: a WebSocket that sends a snapshot and then every change as a small delta, and signed webhooks that POST score and status events to your server. Both carry the Fixture shape the REST API already returns, for all 24 sports, so each change is a partial object to merge into the copy you hold.

  • Snapshot, then deltas
  • 5-minute replay
  • Signed webhooks
  • Frames are not requests
Stream openapi.datasportsapi.com · livescores
  1. { "type": "snapshot", "channel": "livescores", "data": [ … ] }
  2. { "type": "delta", "id": 480112, "sport": "football", "changes": { "homeScore": { "current": 2 } } }
  3. { "type": "delta", "id": 481004, "sport": "basketball", "changes": { "awayScore": { "current": 86 } } }
  4. { "type": "delta", "id": 481220, "sport": "tennis", "changes": { "status": { "description": "Set 3" } } }

Snapshot, then deltasExample frames

Delivery

Two ways to receive every change

Use the stream for anything a person watches as it happens. Use webhooks when a server should react to a goal or a final whistle without holding a connection open.

WebSocket stream

Business and up

One connection to wss://api.datasportsapi.com, many channels. Each subscription opens with the full current state and then only sends what changed, so a busy Saturday of football is a trickle of small frames rather than a flood of repeated lists. Matches that kick off while you are connected arrive whole; matches that finish leave with one last delta saying why.

  1. snapshot
  2. delta · 101
  3. delta · 102
  4. delta · 103
  5. delta · 104
  • livescoresEvery match in play, all sports
  • sport:{slug}One sport's matches in play
  • fixture:{id}One match in depth: events, statistics, lineups
  • league:{id}One competition
  • team:{id}One team, home or away
  • odds:{id}One match's betting markets
  • tracking:{id}One match's ball, tracked events, live timeline and NBA player positionsEnterprise
  • race:{id}A motorsport or cycling race

Webhooks

Business and up

Register a public HTTPS endpoint and we POST each event to it in its own request, signed with HMAC-SHA256. Narrow an endpoint by event type, sport, league id and fixture id; an empty filter lets everything through. The body's data.changes is shaped exactly like a WebSocket delta, so one merge function serves both.

  • fixture.scoreOne side's score changed
  • fixture.statusThe start, each new period or break, the final whistle, a postponement or a cancellation
  • fixture.eventsGoals with scorers, cards and substitutions, for the fixtures you name
  • fixture.lineupsThe official teams, typically some 90 minutes ahead of the start, for the fixtures you name

A failed delivery is retried six times over about nine hours. An endpoint whose every attempt fails for 24 hours is paused until you switch it back on.

One session

From ticket to merged state in five moves

  1. Mint a ticket

    POST /v2/stream/ticket with your secret key returns a URL holding a single-use ticket, valid for 30 seconds. Minting it is one ordinary request.

  2. Connect, read welcome

    The first frame names the protocol, the heartbeat interval, how many channels one connection may hold and whether replay is on.

  3. Subscribe

    Send subscribe with a channel name and a snapshot comes back: the channel's whole current state, stamped with a sequence number.

  4. Merge what follows

    A fixture frame adds a match that has just kicked off. Each delta is a partial Fixture to deep-merge into your copy, nested objects included.

  5. Watch the sequence

    seq rises by one per frame on a channel. On a gap, send resync; after a drop, reconnect with lastSeq and up to five minutes are replayed.

In code

Subscribe in a few lines

The SDK clients wrap the whole session: they mint the ticket, subscribe, answer heartbeats, reconnect with lastSeq after a drop and keep a merged copy of every fixture on each channel. You handle the frames you care about and read the current state whenever you need it.

Writing your own client? The cURL tab shows the two steps underneath, and the WebSocket guide ends with a complete client in plain TypeScript.

# 1. A single-use ticket, valid for 30 seconds
curl -X POST "https://api.datasportsapi.com/v2/stream/ticket" \
  -H "Authorization: Bearer $DATASPORTSAPI_API_KEY"

# 2. Open data.url with any WebSocket client, then send:
#    { "type": "subscribe", "channel": "livescores" }
Frames on the wire
← { "type": "welcome", "protocol": 4, "heartbeatMs": 30000, "maxChannels": 50, "replay": true }
→ { "type": "subscribe", "channel": "livescores" }
← { "type": "snapshot", "channel": "livescores", "seq": 1762790400000,
    "ts": 1762790400000, "data": [ Fixture, … ] }
← { "type": "delta", "channel": "livescores", "seq": 1762790400001,
    "ts": 1762790463120, "id": 480112, "sport": "football",
    "changes": { "homeScore": { "current": 2, "periods": { "period2": 1 } } } }
// period1 is untouched: merge, never replace

Webhooks

Check the signature, then trust the event

Each delivery carries DSA-Signature, DSA-Event and DSA-Event-Id headers. Verify the signature on the raw body before you parse it, answer with a 2xx inside ten seconds, and do the slow work afterwards.

Delivery order is not guaranteed and a retry repeats an event you may already have handled, so keep the ids you have seen for longer than the retry window and drop the duplicates.

import { createHmac, timingSafeEqual } from "node:crypto";

// header: the DSA-Signature value · rawBody: the body exactly as received
export function verify(header: string, rawBody: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300; // refuse old timestamps
  const given = Buffer.from(parts.v1 ?? "");
  return fresh && given.length === expected.length && timingSafeEqual(given, Buffer.from(expected));
}

Choosing

Polling, streaming or webhooks?

TopicREST pollingWebSocketWebhooks
PlansEvery planBusiness and upBusiness and up
How changes arriveYou ask againA snapshot, then deltas pushed to youOne HTTPS POST per event to your server
Counts against quotaEvery callOnly the ticket per connectionNothing: deliveries are not requests
ScopeA board, a match, a dayEight channel types, mixed freelyFilters by event type, sport, league and fixture
After a gapCall againReconnect with lastSeq: five minutes of replayRetries over about nine hours
Best forPrototypes, small sites, scheduled jobsScore apps, tickers, match centres, dashboardsAlerts, notifications, settling contests

Before you go live

  1. One socket, fanned out

    Connect from your server and serve your users from there. An account holds 3 connections at once on Business and 5 on Enterprise, shared by every key.

  2. Handle fixture frames

    A match that starts while you are connected comes in whole, as a fixture frame. Skip that frame type and the match never reaches you.

  3. Deep-merge every delta

    Merge field by field, nested objects included: a delta that carries period2 must leave period1 alone. A clock that changed arrives whole.

  4. Watch for silence

    A ping frame comes every heartbeatMs. If 2.5 heartbeats pass with no frame at all, the socket is dead without a close: reconnect with lastSeq.

  5. Compare seq per channel

    Treat it as opaque, since it starts from a server clock rather than zero. Only the step of one between frames matters.

  6. Verify every webhook

    Recompute the signature on the raw body, compare in constant time and refuse old timestamps before you act on anything.

  7. Expect repeats and reordering

    Deduplicate webhook events on their id, also sent as DSA-Event-Id, and use createdAt rather than arrival order.

Plans

Push delivery starts on Business

Every plan reads live data over REST. The WebSocket stream, with replay, and webhooks come with Business and Enterprise; the tracking channel is Enterprise only.

  1. Free

    Not included

    $0 a month

    • 1,000 requests / day
    • 10 requests a minute
    • Last 7 days of history

    Poll the live board up to 10 times a minute. No stream or webhooks.

    Free plan details
  2. Starter

    Not included

    $49 a month

    • 250,000 requests / month
    • 120 requests a minute
    • Last 30 days of history

    Poll from your server up to 120 times a minute. No stream or webhooks.

    Starter plan details
  3. Pro

    Not included

    $199 a month

    • 1,000,000 requests / month
    • 600 requests a minute
    • Last 6 months of history

    Faster polling and widgets that refresh themselves in the browser. No stream or webhooks.

    Pro plan details
  4. Business

    Included

    $1,500 a month

    • 5,000,000 requests / month
    • 3,000 requests a minute
    • Last 12 months of history

    The WebSocket stream with replay on every channel but tracking:{id}, 3 connections at once, plus webhooks.

    Business plan details
  5. Enterprise

    Included

    $2,500 a month

    • 10,000,000 requests / month
    • 6,000 requests a minute
    • Full history

    All eight channels, tracking:{id} included, 5 connections at once, plus webhooks.

    Enterprise plan details

Questions

Real-time sports data, answered

Anything else? The full FAQ covers quota, plans and the data in general.

Which plan includes the WebSocket stream and webhooks?

Business and Enterprise. On the other plans the ticket request answers 403 ws_not_available. One channel is held back: tracking:{id}, with the ball, the tracked events, the live basketball, ice hockey and darts timelines and the NBA player positions, opens on Enterprise only, and a Business connection that subscribes to it gets channel_forbidden. REST reads of the same data work on every plan, and the live state in a REST response is current to the second it is served, so you can start by polling and switch to the stream later without changing your data model.

Do WebSocket frames and webhook deliveries count as requests?

No. They are pushes, not /v2 calls, so they never touch your quota or your per-minute rate. The one thing that counts is the ticket you mint for each new connection, which is a normal request.

What happens when my WebSocket connection drops?

Mint a new ticket, reconnect and subscribe again with lastSeq set to the last sequence number you hold. The server keeps five minutes of frames per channel and replays what you missed, then confirms with a subscribed frame. If the gap is older, you simply get a fresh snapshot. A close with code 1012 means the server is restarting: reconnect at once the same way. A socket can also die silently, after a laptop sleeps or a phone changes network: if no frame at all, not even the ping sent every heartbeatMs, has arrived for 2.5 heartbeats, drop it and reconnect the same way. The official clients do all of this for you.

Can I stream a single match, team or league?

Yes. Subscribe to fixture:{id}, team:{id}, league:{id} or sport:{slug} instead of the whole live board, and combine as many as the maxChannels figure in the welcome frame allows on one connection. A fixture:{id} channel also carries events, statistics and lineups and, in some sports, play by play, momentum, shot maps, win probability and AI commentary.

How do I check that a webhook really came from you?

Every request carries a DSA-Signature header of the form t=<unix seconds>,v1=<hex>. Recompute HMAC-SHA256 over <t>.<raw body> with the endpoint's signing secret, compare the two in constant time, and refuse a t more than a few minutes old. Answer with a 2xx within 10 seconds; anything else is retried after 10 s, 1 min, 5 min, 30 min, 2 h and 6 h.

Can I get real-time sports data on a plan below Business?

Yes, by polling. /v2/livescores and every endpoint that returns fixtures apply the live state as they answer, on every plan. Free lets you poll 10 times a minute and Starter 120; the quota sets how long you can keep that pace. Poll from your server and share the result with your users, rather than from each browser.

Stop polling. Start listening.

Build on REST for free today, then switch the same model to the stream from Business up.