DEV Community: orbistats

Scaling a Sports Data Consumer for Match-Day Spikes: Queues, Caching and Rate Limits

orbistats — Wed, 07 Oct 2026 16:08:10 +0000

Your sports app works perfectly on a quiet Tuesday.

Then Saturday, 3:00 PM arrives. Dozens of matches kick off within the same minute. Goals land in parallel across several leagues. Ten minutes later, your users are all refreshing at once, and your single-threaded poller is hammering an API that just returned its first 429.

Everything that was "fine in testing" turns out to depend on traffic being polite.

This tutorial builds a sports data consumer that stays up when traffic isn't polite. We'll build it in Python with Redis, and every piece is something you can reuse for any real-time feed, not just sports.

By the end you'll have:

A webhook receiver that verifies signatures and acknowledges in milliseconds
A durable queue (Redis Streams) that absorbs bursts instead of dropping them
Idempotent workers that survive duplicates, retries and out-of-order events
A rate-limited API client with shared budgets, backoff, jitter and Retry-After handling
Cache-aside with single-flight and stale-while-revalidate, so a thousand users cost one API call
A reconciliation poller that heals anything a webhook missed
A spike simulator that proves all of the above actually works

Let's build it.

Why Match Days Break Naive Consumers

Sports traffic isn't smooth. It's synchronized, and synchronization is what kills systems.

Kickoffs cluster. A Premier League Saturday puts a whole slate of matches on the same clock. Fixtures that were quiet for a week become live all at once.
Events cluster. A burst of goals, cards and substitutions across many matches arrives in the same few seconds, then nothing for a minute.
Final whistles cluster. Matches that kicked off together end together, so a wave of match.finished events lands at nearly the same instant.
Your users cluster too. A goal in a big match sends tens of thousands of people to refresh simultaneously.
Sports overlap. A cricket T20 final, a tennis tournament day, and a football slate can all peak together, so the spike isn't confined to one sport.

A naive consumer fails in predictable ways:

Naive approach What breaks on match day
One API call per user request Your users become your rate-limit problem
Poll every match every few seconds Request count scales with matches, not with value
Process events inline in the HTTP handler A slow database write times out the sender
Trust arrival order A retried "goal" lands after the "final score" and flips the match back to live
Retry immediately on 429 You turn a rate limit into a thundering herd
No dedupe Retries double-count goals

Each of those has a boring, well-understood fix. We'll apply them one at a time.

The Architecture
text
┌────────────────────────────┐
│ Orbistats feed │
└──────┬───────────────┬─────┘
webhooks (push)│ │ REST (pull, safety net)
▼ ▼
┌───────────────┐ ┌───────────────┐
│ FastAPI │ │ Reconciliation│
│ receiver │ │ poller │
│ verify+dedupe │ └───────┬───────┘
└───────┬───────┘ │
▼ │
┌───────────────┐ │
│ Redis Stream │ │
│ (durable queue│ │
└───────┬───────┘ │
▼ ▼
┌───────────────────────────────┐
│ Workers (N) → atomic Lua │
│ state: match:{id} + live:ids │──► pub/sub "updates"
└───────────────┬───────────────┘
▼
┌───────────────────────────────┐
│ Read API + SSE (your users) │
│ serves from cache, never from │
│ the upstream API │
└───────────────────────────────┘

The golden rule behind the whole design: your users should never cause a call to the upstream API. Users read from your cache. The upstream API is fed by your workers, at a rate you control.

Choosing How to Receive Data

Before writing code, decide how data gets into your system. The Live Scores API delivers the same events three ways:

Method Best for Trade-off
REST polling Simple jobs, reconciliation Cost scales with poll frequency; always a little late
WebSocket Latency-sensitive live UIs You own reconnect logic and connection limits
Webhooks Event-driven backends You need a public HTTPS endpoint that answers quickly

For match-day scale I recommend webhooks as the primary path with REST as a safety net:

Webhooks are push-based, so your request count doesn't grow with the number of live matches.
They come with the properties a robust consumer needs: signed payloads, automatic retries with backoff, an event_id for dedupe, and a per-match sequence for ordering.
If your endpoint is down for a while, deliveries can be listed and replayed afterwards.

We'll also show the WebSocket variant, since many teams prefer it.

Capacity Math Before You Write Code

Do this on paper first. These numbers are illustrative assumptions, not Orbistats limits:

text
Naive: poll each live match every 10 s
300 live matches ÷ 10 s = 30 requests/second = 1,800 requests/minute

Better: one bulk "live" call per sport every 10 s
13 sports ÷ 10 s ≈ 78 requests/minute

Best: webhooks as primary, bulk poll every 30 s as a safety net
13 sports ÷ 30 s ≈ 26 requests/minute

Your users:
50,000 users refreshing every 10 s = 5,000 reads/second
→ that must hit YOUR cache, not the upstream API

The same data costs 1,800 requests per minute done badly and 26 done well. Plan limits differ by tier, so check the pricing page and the rate-limit headers on real responses, then size your BUDGET_PER_MIN accordingly.

Step 1: Setup
Request an API key on the sign-up page.
Read the documentation for auth and conventions, then try the endpoints in the sandbox so you see real payloads before coding.
Keep the API reference open. It documents the X-RateLimit-* headers, the 429 and Retry-After behaviour, and the standard response envelope (data, meta, errors).

Project layout:

text
matchday/
├── .env
├── docker-compose.yml
├── config.py
├── app.py # webhook receiver + read API + SSE
├── worker.py # stream consumer, idempotent state updates
├── client.py # rate-limited, cached REST client
├── poller.py # reconciliation safety net
├── ws_consumer.py # optional WebSocket ingestion
├── register.py # register the webhook
└── simulate.py # spike simulator + verifier

Install:

bash
python -m venv .venv && source .venv/bin/activate
pip install fastapi uvicorn "redis>=5" requests httpx websockets python-dotenv

docker-compose.yml (Redis 7 is needed for the stream commands we use):

yaml
services:
redis:
image: redis:7-alpine
command: ["redis-server", "--appendonly", "yes"]
ports: ["6379:6379"]
volumes: ["redis-data:/data"]

volumes:
redis-data:

.env:

env
ORBISTATS_API_KEY=your_key_here
WEBHOOK_SECRET=generate_a_long_random_string
REDIS_URL=redis://localhost:6379/0

Stay below your plan's real limit (aim for ~70-80%)

BUDGET_PER_MIN=60

Docs show two live routes; confirm in the sandbox and set one:

{sport}/matches/live (API reference)

{sport}/live (Live Scores page)

LIVE_PATH={sport}/matches/live

Generate a strong webhook secret:

bash
python -c "import secrets; print(secrets.token_urlsafe(32))"

Start Redis:

bash
docker compose up -d
Step 2: Shared Configuration

config.py:

python
import os
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.environ["ORBISTATS_API_KEY"]
WEBHOOK_SECRET = os.environ["WEBHOOK_SECRET"]
REDIS_URL = os.getenv("REDIS_URL", "redis://localhost:6379/0")
BASE_URL = "https://api.orbistats.com/v1"

BUDGET_PER_MIN = int(os.getenv("BUDGET_PER_MIN", "60"))
LIVE_PATH = os.getenv("LIVE_PATH", "{sport}/matches/live")

STREAM = "events" # durable queue of incoming events
GROUP = "workers" # consumer group
DLQ = "events:dead" # events that failed repeatedly
Step 3: The Webhook Receiver (Acknowledge Fast, Do Nothing Else)

The webhook docs set the rule: respond within 5 seconds or the delivery counts as failed and is retried. The lesson is simple: do the minimum in the HTTP handler. Verify, dedupe, enqueue, return 200. Everything slow happens later, in a worker.

Each delivery is a signed POST. The signature is an HMAC-SHA256 of the raw request body using your secret, sent in the X-Orbistats-Signature header. Here's the shape of a payload from the docs:

json
{
"event": "match.finished",
"event_id": "evt_9f2a1c4b",
"delivery_id": "dlv_7c3e08a1",
"sequence": 214,
"match_id": 48213,
"sport": "football",
"final_score": "2-1",
"timestamp": "2026-09-14T16:52:11Z"
}

Two fields matter most for scaling:

event_id is stable across retries, so dedupe on it.
sequence is monotonic per match_id, so order by it, not by arrival time.

app.py:

python
import hashlib
import hmac
import json

import redis.asyncio as aioredis
from fastapi import FastAPI, HTTPException, Request, Response
from fastapi.responses import StreamingResponse

from config import DLQ, GROUP, REDIS_URL, STREAM, WEBHOOK_SECRET

app = FastAPI()
r = aioredis.from_url(REDIS_URL, decode_responses=True)

def valid_signature(raw: bytes, header: str) -> bool:
if not header.startswith("sha256="):
return False
digest = hmac.new(WEBHOOK_SECRET.encode(), raw, hashlib.sha256).hexdigest()
# constant-time comparison avoids timing attacks
return hmac.compare_digest(f"sha256={digest}", header)

@app.post("/webhook")
async def webhook(request: Request):
raw = await request.body() # sign the RAW bytes, never re-serialized JSON

if not valid_signature(raw, request.headers.get("X-Orbistats-Signature", "")):
    raise HTTPException(status_code=401, detail="bad signature")

try:
    event = json.loads(raw)
    event_id = event["event_id"]
except (ValueError, KeyError):
    raise HTTPException(status_code=400, detail="malformed event")

# First writer wins. The key outlives the longest retry window (~1h) by a lot.
key = f"seen:{event_id}"
first_time = await r.set(key, 1, nx=True, ex=86400)

if first_time:
    try:
        await r.xadd(STREAM, {"payload": raw.decode()},
                     maxlen=500_000, approximate=True)
    except Exception:
        # If we failed to enqueue, forget we saw it so the sender's retry works.
        await r.delete(key)
        raise HTTPException(status_code=503, detail="queue unavailable")

return Response(status_code=200)     # duplicates are acknowledged too

Three details worth stealing:

We sign-check before parsing. Never trust a payload you haven't authenticated.
Duplicates get a 200. The sender should stop retrying, even though we ignored the event.
The "forget on failure" branch. Without it, a failed enqueue would mark the event as seen and the retry would be silently discarded. That's data loss disguised as dedupe.

The handler does one SET and one XADD. That's a few milliseconds, comfortably inside the 5-second limit even under heavy load.

Step 4: Idempotent Workers

Webhooks are at-least-once, not exactly-once. That means your worker will see duplicates and out-of-order events, and it must produce the correct state anyway. This property is called idempotency, and it's what makes retries safe.

The classic bug: the event for "goal #3" is retried and arrives after "match finished". A naive worker overwrites the final state and the match looks live again.

The fix is sequence gating: only apply an event if its sequence is higher than the last one applied for that match. And the check-and-write has to be atomic, otherwise two workers can race. A Redis Lua script gives us that:

worker.py:

python
import json
import logging
import sys
import time

import redis

from config import DLQ, GROUP, REDIS_URL, STREAM

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("worker")

r = redis.from_url(REDIS_URL, decode_responses=True)

MAX_ATTEMPTS = 5

One atomic script: gate on sequence, write state, update the live set, publish.

Because it's a single script, state and side effects can never diverge,

even if the worker crashes mid-way.

APPLY_LUA = """
local current = tonumber(redis.call('HGET', KEYS[1], 'seq') or '-1')
local incoming = tonumber(ARGV[1])
if incoming <= current then return 0 end

redis.call('HSET', KEYS[1], 'seq', incoming, unpack(ARGV, 5))

if ARGV[3] == 'finished' then
redis.call('SREM', KEYS[2], ARGV[2])
redis.call('EXPIRE', KEYS[1], 21600)
elseif ARGV[3] == 'in_play' then
redis.call('SADD', KEYS[2], ARGV[2])
end

redis.call('PUBLISH', 'updates', ARGV[4])
return 1
"""
apply_event = r.register_script(APPLY_LUA)

def to_fields(ev: dict) -> dict:
kind = ev["event"]
fields = {
"match_id": ev["match_id"],
"sport": ev.get("sport"),
"last_event": kind,
"updated_at": ev.get("timestamp"),
}
if kind == "match.started":
fields["status"] = "in_play"
elif kind == "match.goal":
fields.update(
status="in_play",
last_goal_team=ev.get("team"),
last_goal_minute=ev.get("minute"),
score=ev.get("score"),
)
elif kind == "match.finished":
fields.update(status="finished", final_score=ev.get("final_score"))
# Unknown event types still update last_event, so new types don't crash us.
return {k: v for k, v in fields.items() if v is not None}

def handle(ev: dict) -> bool:
fields = to_fields(ev)
flat = [x for pair in fields.items() for x in pair]
payload = json.dumps({"match_id": ev["match_id"], **fields})
applied = apply_event(
keys=[f"match:{ev['match_id']}", "live:ids"],
args=[int(ev["sequence"]), ev["match_id"], fields.get("status", ""), payload, *flat],
)
return bool(applied) # False = stale or duplicate, safely ignored

def process(msg_id: str, data: dict) -> None:
try:
handle(json.loads(data["payload"]))
r.xack(STREAM, GROUP, msg_id)
except Exception:
log.exception("failed processing %s", msg_id)
# Leave it pending; reclaim() retries it. After MAX_ATTEMPTS, park it.
pending = r.xpending_range(STREAM, GROUP, min=msg_id, max=msg_id, count=1)
if pending and pending[0]["times_delivered"] >= MAX_ATTEMPTS:
r.xadd(DLQ, data)
r.xack(STREAM, GROUP, msg_id)
log.error("moved %s to dead-letter stream", msg_id)

def reclaim(consumer: str) -> None:
"""Pick up messages a crashed worker never acknowledged."""
start = "0-0"
while True:
start, claimed, *_ = r.xautoclaim(
STREAM, GROUP, consumer, min_idle_time=30_000, start_id=start, count=100
)
for msg_id, data in claimed:
process(msg_id, data)
if start == "0-0":
break

def main(consumer: str) -> None:
try:
r.xgroup_create(STREAM, GROUP, id="0", mkstream=True)
except redis.ResponseError as exc:
if "BUSYGROUP" not in str(exc):
raise

log.info("worker %s started", consumer)
last_reclaim = 0.0
while True:
    if time.time() - last_reclaim > 15:
        reclaim(consumer)
        last_reclaim = time.time()

    resp = r.xreadgroup(GROUP, consumer, {STREAM: ">"}, count=100, block=2000)
    for _, messages in resp or []:
        for msg_id, data in messages:
            process(msg_id, data)

if name == "main":
main(sys.argv[1] if len(sys.argv) > 1 else "worker-1")

Why this design holds up:

Consumer groups split the stream across workers, so scaling out is just launching another process with a different name.
Ack-after-success means a worker crash leaves the message pending, and reclaim() retries it later. Nothing is lost.
A dead-letter stream catches poison messages, so one bad event can't block the queue forever.
The Lua script makes "check sequence, then write" a single atomic step, so concurrency can't corrupt a match.

Scaling workers on match day is literally:

bash
python worker.py w1 &
python worker.py w2 &
python worker.py w3 &
Step 5: A Rate-Limit-Aware, Cached REST Client

Even with webhooks as the primary path, you'll still call the REST API: for fixtures, standings, team data, and the safety-net poller. That client needs to be a good citizen.

Most rate-limit failures come from four mistakes: ignoring the headers, retrying instantly, retrying in lockstep, and letting many processes each think they own the whole budget. We'll fix all four.

The API reference documents these building blocks:

X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset on every response
429 with a Retry-After header
Safe-to-retry 500 and 503 responses
403 for "your plan doesn't include this" (do not retry that)

client.py:

python
import json
import logging
import random
import time

import redis
import requests

from config import API_KEY, BASE_URL, BUDGET_PER_MIN, REDIS_URL

log = logging.getLogger("client")
r = redis.from_url(REDIS_URL, decode_responses=True)

session = requests.Session()
session.headers.update({"Authorization": f"Bearer {API_KEY}"})

class ApiError(Exception):
pass

def backoff(attempt: int, cap: float = 30.0) -> float:
"""Exponential backoff with FULL jitter, so clients don't retry in lockstep."""
return random.uniform(0, min(cap, 2 ** attempt))

def acquire() -> float:
"""Shared budget across ALL worker processes. Returns seconds to wait (0 = go)."""
now = time.time()

# A global pause (set after a 429 or a nearly-empty budget) beats everything.
pause_until = r.get("rl:pause_until")
if pause_until and float(pause_until) > now:
    return float(pause_until) - now

key = f"rl:{int(now // 60)}"
used = r.incr(key)
if used == 1:
    r.expire(key, 120)
return 0.0 if used <= BUDGET_PER_MIN else 60 - (now % 60)

def pause_everyone(seconds: float) -> None:
until = time.time() + min(seconds, 60)
r.set("rl:pause_until", until, ex=int(seconds) + 2)

def api_get(path: str, params: dict | None = None, retries: int = 4) -> dict:
url = f"{BASE_URL}/{path.lstrip('/')}"

for attempt in range(retries + 1):
    while wait := acquire():
        time.sleep(wait + random.uniform(0, 0.5))

    try:
        resp = session.get(url, params=params, timeout=(3, 10))
    except requests.RequestException as exc:
        log.warning("network error on %s: %s", path, exc)
        time.sleep(backoff(attempt))
        continue

    # Back off *before* we hit the wall, for every worker at once.
    remaining = resp.headers.get("X-RateLimit-Remaining")
    reset = resp.headers.get("X-RateLimit-Reset")
    if remaining is not None and reset and int(remaining) <= 2:
        pause_everyone(max(0, float(reset) - time.time()))

    if resp.status_code == 429:
        delay = float(resp.headers.get("Retry-After", backoff(attempt, cap=60)))
        log.warning("429 on %s, pausing all workers for %.1fs", path, delay)
        pause_everyone(delay)
        time.sleep(delay + random.uniform(0, 1))
        continue

    if resp.status_code >= 500:
        time.sleep(backoff(attempt))
        continue

    if resp.status_code in (400, 401, 403, 404):
        # Retrying won't fix a bad key, a plan limit, or a typo.
        raise ApiError(f"{resp.status_code} on {path}: {resp.text[:200]}")

    resp.raise_for_status()
    return resp.json()

raise ApiError(f"gave up on {path} after {retries + 1} attempts")

The two ideas that matter most:

pause_everyone. When one worker sees a 429, all workers stop. Otherwise ten workers each discover the limit independently and each one retries into it.
Full jitter. random.uniform(0, 2**attempt) spreads retries out. Plain exponential backoff makes every client retry at the same instant, which recreates the spike you were avoiding.
Cache-Aside, Single-Flight, Stale-While-Revalidate

Now the part that protects you from your own users. Add this to client.py:

python
def cached_get(path: str, params: dict | None = None, ttl: int = 10, stale_ttl: int = 600):
"""
- Fresh hit: return immediately (no upstream call).
- Miss: exactly ONE caller fetches; others get stale data or wait briefly.
- Upstream failing: serve stale data instead of an error.
"""
key = f"http:{path}:{json.dumps(params or {}, sort_keys=True)}"

fresh = r.get(key)
if fresh:
    r.incr("stats:cache_hit")
    return json.loads(fresh)
r.incr("stats:cache_miss")

owns_lock = bool(r.set(f"lock:{key}", 1, nx=True, ex=10))

if not owns_lock:
    stale = r.get(f"{key}:stale")
    if stale:
        return json.loads(stale)            # serve old data, don't pile on
    for _ in range(20):                      # wait up to ~2s for the leader
        time.sleep(0.1)
        fresh = r.get(key)
        if fresh:
            return json.loads(fresh)
    # Leader never delivered; fall through and fetch ourselves.

try:
    body = api_get(path, params)
    payload = json.dumps(body)
    pipe = r.pipeline()
    pipe.set(key, payload, ex=ttl)
    pipe.set(f"{key}:stale", payload, ex=ttl + stale_ttl)
    pipe.execute()
    return body
except Exception:
    stale = r.get(f"{key}:stale")
    if stale:
        log.warning("upstream failed for %s, serving stale", path)
        return json.loads(stale)
    raise
finally:
    if owns_lock:
        r.delete(f"lock:{key}")

What each part buys you:

Single-flight (the lock): if 5,000 requests miss the cache in the same millisecond, one goes upstream. This prevents the "cache stampede" that takes down systems right when the cache expires.
Stale-while-revalidate: callers get slightly old data instantly while one caller refreshes it. For sports scores, "8 seconds old" is better than "an error".
Stale-on-error: if the upstream is rate-limiting or down, you keep serving the last good answer.
Pick TTLs by how fast the data actually changes

The API reference marks fixtures as cacheable and the live endpoint as not cached. Use that to set your own policy:

Data Suggested TTL Stale window Why
Fixtures / schedules 5 min 1 hour Rarely change once published
Standings 60 s (on match day) 10 min Change only after a result is confirmed
Live matches (bulk) 8 s 2 min Fast-moving, but one call serves everyone
Teams, competitions 24 h 24 h Effectively static

These are starting points. Measure your cache hit ratio (we expose it later) and tune.

Step 6: The Reconciliation Poller (Your Safety Net)

Webhooks are excellent, but no push system is perfect. Your endpoint might be down during a deployment. A network blip might swallow a delivery. A bug on your side might drop an event.

A reconciliation poller quietly compares reality with your state and repairs gaps. It runs slowly because it's a safety net, not the primary path.

poller.py:

python
import logging
import time
from datetime import datetime

from client import cached_get, r
from config import LIVE_PATH

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("poller")

The 13 sports. Confirm exact slugs in the documentation.

SPORTS = [
"football", "basketball", "american-football", "cricket", "tennis",
"baseball", "esports", "combat-sports", "volleyball", "handball",
"ice-hockey", "golf", "horse-racing",
]

def parse_ts(value):
return datetime.fromisoformat(value.replace("Z", "+00:00")) if value else None

def reconcile(sport: str) -> int:
body = cached_get(LIVE_PATH.format(sport=sport), ttl=8, stale_ttl=120)
items = body.get("data", body) if isinstance(body, dict) else body
if isinstance(items, dict): # some responses return a single object
items = [items]

repaired = 0
for m in items or []:
    match_id = m.get("fixture_id") or m.get("match_id")
    if not match_id:
        continue

    key = f"match:{match_id}"
    ours = r.hgetall(key)
    api_ts, our_ts = parse_ts(m.get("updated_at")), parse_ts(ours.get("updated_at"))

    missing = not ours
    behind = bool(api_ts and our_ts and api_ts > our_ts)
    if not (missing or behind):
        continue

    score = m.get("score") or {}
    fields = {
        "match_id": match_id,
        "sport": sport,
        "status": m.get("status", "in_play"),
        "minute": m.get("minute"),
        "score": f"{score.get('home')}-{score.get('away')}" if score else None,
        "updated_at": m.get("updated_at"),
        "source": "poll",
    }
    # We deliberately never touch 'seq', so a later webhook still wins.
    r.hset(key, mapping={k: v for k, v in fields.items() if v is not None})
    r.sadd("live:ids", match_id)
    repaired += 1

return repaired

def main(interval: int = 30) -> None:
while True:
started = time.time()
for sport in SPORTS:
try:
n = reconcile(sport)
if n:
log.warning("repaired %d %s matches (webhooks missed something)", n, sport)
except Exception:
log.exception("reconcile failed for %s", sport)
time.sleep(max(0, interval - (time.time() - started)))

if name == "main":
main()

Notice the log line. If the poller repairs things often, your webhook path has a problem. The poller is both a safety net and an early-warning system.

One improvement worth making later: skip sports with no matches today (check fixtures once, cached for five minutes), so quiet sports cost you zero requests.

Also remember that the poller shares the same rate budget as everything else, via acquire(). It can't starve the rest of your system.

Step 7: Serve Your Own Users From Cache

Now the payoff. Add two endpoints to app.py that read only from Redis:

python
@app.get("/matches/live")
async def live_matches():
ids = await r.smembers("live:ids")
pipe = r.pipeline()
for match_id in ids:
pipe.hgetall(f"match:{match_id}")
rows = await pipe.execute()
return [row for row in rows if row]

@app.get("/stream")
async def stream():
"""Server-Sent Events: one Redis subscription per client, zero upstream calls."""
async def events():
pubsub = r.pubsub()
await pubsub.subscribe("updates")
try:
async for msg in pubsub.listen():
if msg["type"] == "message":
yield f"data: {msg['data']}\n\n"
finally:
await pubsub.unsubscribe("updates")
await pubsub.aclose()

return StreamingResponse(events(), media_type="text/event-stream")

@app.get("/healthz")
async def healthz():
try:
groups = await r.xinfo_groups(STREAM)
group = next((g for g in groups if g["name"] == GROUP), {})
except Exception:
group = {}
return {
"stream_length": await r.xlen(STREAM),
"pending": group.get("pending"),
"lag": group.get("lag"),
"dead_letters": await r.xlen(DLQ),
"live_matches": await r.scard("live:ids"),
}

Browsers can consume the stream with three lines:

javascript
const es = new EventSource("/stream");
es.onmessage = (e) => updateScoreboard(JSON.parse(e.data));

Whether you have 50 users or 50,000, your upstream API usage is identical. Scaling users now only costs Redis reads, which are cheap and scale horizontally.

Run it:

bash
uvicorn app:app --workers 2 --port 8000
Can't be bothered to build the fan-out yourself?

If you only need to display scores and don't need custom logic, you can skip this whole layer. The platform's Widgets embed a live scoreboard, match center or odds board with a script tag, powered by the same live feed. Building fan-out infrastructure is only worth it when your product needs control over data, UI or logic that a widget can't give you.

Step 8: Register the Webhook (and Replay After Outages)

Your endpoint must be reachable over HTTPS. During development, use any tunnelling tool to expose localhost:8000. Then register it:

python
import requests
from config import API_KEY, BASE_URL, WEBHOOK_SECRET

resp = requests.post(
f"{BASE_URL}/webhooks",
headers={"Authorization": f"Bearer {API_KEY}"},
json={
"url": "https://your-domain.example/webhook",
"events": ["match.started", "match.goal", "match.finished"],
"secret": WEBHOOK_SECRET, # optional: auto-generated if omitted
# "sport": "football", # optional: limit to one sport
},
timeout=15,
)
resp.raise_for_status()
print(resp.json())

Subscribe only to the events you actually use. Every unused event type is traffic you pay to receive and process.

What happens when you're down?

The docs describe an automatic retry schedule: an immediate attempt, then roughly 30 seconds, 2 minutes, 10 minutes, and 1 hour, after which the delivery is marked failed. Any non-2xx response or a timeout triggers a retry.

That covers short blips. For longer outages, nothing is lost: missed deliveries can be listed and replayed.

python
def replay_missed(webhook_id: str) -> None:
headers = {"Authorization": f"Bearer {API_KEY}"}
base = f"{BASE_URL}/webhooks/{webhook_id}"

print(requests.get(f"{base}/deliveries", headers=headers, timeout=15).json())
requests.post(f"{base}/replay", headers=headers, timeout=15).raise_for_status()

Check the docs for any filtering parameters. The important point: replay is only safe because your workers are idempotent. Replayed events carry the same event_id and sequence, so already-applied events are simply ignored. That's the payoff for Step 4.

A good outage runbook:

Fix and redeploy your receiver.
Trigger a replay for the window you missed.
Watch the poller's "repaired N matches" log line fall back to zero.
Step 9: The WebSocket Alternative

If you prefer streaming, the WebSocket API is a drop-in replacement for the ingestion step. Everything downstream (queue, workers, cache, read API) stays exactly the same. That's the benefit of putting a queue between ingestion and processing.

The docs show these behaviours:

Authenticate on connect, then send {"action": "subscribe", "channel": "football.live"}
Optional league and match_id filters per subscription
Heartbeats via ping/pong frames
Close codes: 1000 normal, 4001 invalid or missing key, 4008 rate limit exceeded, 1006 abnormal closure

One catch: the documented WebSocket message has no event_id or sequence. We derive both so the same worker can process it:

ws_consumer.py:

python
import asyncio
import hashlib
import json
import logging
import random
from datetime import datetime

import redis.asyncio as aioredis
import websockets

from config import API_KEY, REDIS_URL, STREAM

log = logging.getLogger("ws")
r = aioredis.from_url(REDIS_URL, decode_responses=True)

Confirm the exact auth parameter (api_key vs token) in the docs/sandbox.

URL = f"wss://stream.orbistats.com/v1?api_key={API_KEY}"
CHANNELS = ["football.live", "cricket.live"]

def normalise(msg: dict) -> dict:
"""Give a WebSocket message the same shape the worker expects."""
ts = msg["timestamp"]
fingerprint = f'{msg["match_id"]}|{msg["event"]}|{msg.get("minute")}|{msg.get("team")}|{ts}'
dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
return {
**msg,
"event_id": "ws_" + hashlib.sha1(fingerprint.encode()).hexdigest()[:16],
"sequence": int(dt.timestamp() * 1000), # ordering by event time
}

async def run() -> None:
attempt = 0
while True:
forced_delay = None
try:
async with websockets.connect(URL, ping_interval=20, ping_timeout=20) as ws:
attempt = 0
for channel in CHANNELS:
await ws.send(json.dumps({"action": "subscribe", "channel": channel}))
log.info("connected, subscribed to %s", CHANNELS)

            async for raw in ws:
                msg = json.loads(raw)
                if "match_id" not in msg or "event" not in msg:
                    continue                    # skip acks and housekeeping frames
                await r.xadd(STREAM, {"payload": json.dumps(normalise(msg))},
                             maxlen=500_000, approximate=True)

    except websockets.ConnectionClosed as exc:
        code = exc.rcvd.code if exc.rcvd else 1006
        if code == 4001:
            raise SystemExit("API key rejected (close code 4001)")
        forced_delay = 60 if code == 4008 else None   # rate limited: back off hard
        log.warning("connection closed (%s)", code)
    except OSError as exc:
        log.warning("network error: %s", exc)

    attempt += 1
    await asyncio.sleep(forced_delay or (min(30, 2 ** attempt) + random.random()))

if name == "main":
asyncio.run(run())

Two cautions:

Don't use webhooks and WebSockets as co-equal primary sources for the same match. Their ordering fields come from different schemes (a server counter versus a timestamp), so mixing them breaks sequence gating. Pick one primary source and keep REST as the safety net.
This path skips the receiver's dedupe. That's fine here, because the worker's sequence gate already ignores duplicates (same timestamp means same sequence, which is not greater than the stored one).

Also read the close-code handling carefully. 4001 is fatal (retrying will never help), 4008 means you're being rate limited (back off for a long time), and 1006 is an ordinary drop (reconnect with jittered exponential backoff).

Step 10: Prove It With a Spike Simulator

Everything above is theory until you test it. This simulator generates a worst-case match day:

300 matches with 6 events each
20% duplicate deliveries (retries)
Fully shuffled arrival order (so "finished" often arrives before "goal")
Hundreds of concurrent, properly signed requests

simulate.py:

python
import asyncio
import hashlib
import hmac
import json
import random
import time

import httpx
import redis

from config import REDIS_URL, STREAM, WEBHOOK_SECRET

URL = "http://localhost:8000/webhook"
MATCHES, PER_MATCH = 300, 6
r = redis.from_url(REDIS_URL, decode_responses=True)

def sign(raw: bytes) -> str:
return "sha256=" + hmac.new(WEBHOOK_SECRET.encode(), raw, hashlib.sha256).hexdigest()

def build_batch() -> list[dict]:
events = []
for m in range(MATCHES):
match_id = 60000 + m
for seq in range(1, PER_MATCH + 1):
last = seq == PER_MATCH
events.append({
"event": "match.finished" if last else "match.goal",
"event_id": f"evt_{match_id}{seq}",
"delivery_id": f"dlv{match_id}_{seq}",
"sequence": seq,
"match_id": match_id,
"sport": "football",
**({"final_score": "3-2"} if last else {"team": "Home", "minute": seq * 10}),
"timestamp": "2026-09-14T16:52:11Z",
})
retries = random.sample(events, len(events) // 5) # duplicate deliveries
batch = events + retries
random.shuffle(batch) # out-of-order arrival
return batch

async def blast(batch: list[dict], concurrency: int = 100) -> None:
sem = asyncio.Semaphore(concurrency)

async with httpx.AsyncClient(timeout=5) as client:
    async def send(ev: dict) -> int:
        raw = json.dumps(ev).encode()
        async with sem:
            resp = await client.post(
                URL, content=raw,
                headers={"X-Orbistats-Signature": sign(raw),
                         "Content-Type": "application/json"},
            )
        return resp.status_code

    t0 = time.time()
    codes = await asyncio.gather(*(send(e) for e in batch))
    elapsed = time.time() - t0

ok = sum(c == 200 for c in codes)
print(f"sent {len(batch)} deliveries in {elapsed:.1f}s "
      f"({len(batch) / elapsed:.0f}/s), {ok} acknowledged with 200")

def verify(timeout: int = 30) -> None:
deadline = time.time() + timeout
while time.time() < deadline:
good = sum(
1 for m in range(MATCHES)
if (h := r.hgetall(f"match:{60000 + m}")).get("status") == "finished"
and int(h.get("seq", 0)) == PER_MATCH
)
if good == MATCHES:
break
time.sleep(1)

print(f"matches in correct final state: {good}/{MATCHES}")
print(f"unique events enqueued: {r.xlen(STREAM)} (expected {MATCHES * PER_MATCH})")
print(f"live set size: {r.scard('live:ids')} (expected 0)")
print(f"dead letters: {r.xlen('events:dead')} (expected 0)")

if name == "main":
asyncio.run(blast(build_batch()))
verify()

Run it (with Redis, the receiver, and at least one worker already running):

bash
python simulate.py

What a healthy run looks like:

All 300 matches end in the correct final state, even though events arrived shuffled
Unique events enqueued equals 1,800, which proves the 20% duplicates were dropped at the door
The live set is empty, because every match ended
Dead letters is zero

If you want to re-run, clear state first so the "seen" keys don't suppress your events:

bash
redis-cli FLUSHDB

Try breaking things on purpose. Kill a worker mid-run and watch reclaim() finish its work. Stop all workers, send the batch, then start them and watch the backlog drain. That's the queue doing its job.

Observability: What to Watch on Match Day

You can't fix what you can't see, and on match day you won't have time to dig. Watch these:

Signal Where it comes from Why it matters
Queue lag / pending /healthz (lag, pending) Rising lag means workers can't keep up; add workers
Dead letters /healthz (dead_letters) Anything above zero is a bug to investigate
Webhook ack time (p95) Receiver logs / APM Must stay well under the 5-second limit
429 count Log line from api_get Your budget is too high or something is polling wildly
Cache hit ratio stats:cache_hit vs stats:cache_miss Low ratio means TTLs too short or keys too varied
Poller repairs Poller warning log Frequent repairs mean webhooks are being lost
Redis memory Redis INFO memory The stream and caches grow during peaks

A tiny cache-ratio helper:

python
hits = int(r.get("stats:cache_hit") or 0)
misses = int(r.get("stats:cache_miss") or 0)
print(f"cache hit ratio: {hits / max(1, hits + misses):.1%}")

Sensible starting alerts: consumer lag staying above a few hundred for more than a minute, any dead letters, and any sustained run of 429 responses. When your own error rates climb unexpectedly, check the Orbistats status page before you start debugging your own stack. Knowing it's upstream saves a lot of wasted panic.

Failure Modes and What Actually Happens
Failure Behaviour in this design
Worker crashes mid-event Message stays pending; reclaim() retries it; the atomic script prevents half-applied state
Duplicate delivery (retry) Dropped at the receiver by event_id, or ignored by the sequence gate
Out-of-order delivery Sequence gate keeps the newest state
Upstream returns 429 All workers pause; Retry-After honoured; stale cache served meanwhile
Upstream returns 5xx Jittered exponential backoff; stale cache served
Your endpoint down for hours Retries exhaust; use replay; poller repairs the gap
Redis restarts AOF persistence preserves the stream; consumers resume from their group position
Poison event Retried 5 times, then moved to the dead-letter stream
Sudden user surge Reads hit Redis only; upstream load is unchanged
Bad signature Rejected with 401, never enqueued
Match-Day Checklist

Run through this the day before a big fixture list:

Budget set below your real plan limit, using the headers you observe
Webhook subscribed only to events you use
Receiver deployed behind HTTPS with more than one process
At least two workers running, with a way to add more quickly
Poller running on a relaxed interval
Dead-letter alert configured
Redis persistence on and memory headroom confirmed
Spike simulator run against staging in the last week
Replay procedure written down, so nobody improvises during an outage
Stream maxlen large enough that a long outage can't trim unprocessed events
Secrets (API key, webhook secret) kept out of git
Ideas to Extend This Project

Once the foundation holds, there's a lot you can build on top of it:

Odds-movement pipeline. Subscribe to odds.moved and feed it through the same queue and workers. The Odds API uses the same delivery model, so the architecture carries over almost unchanged.
Low-latency pricing tools. If sub-second reaction matters, the pattern here is the same one Trading Desks rely on: a persistent stream, an atomic state layer, and no slow work in the hot path.
Live match centers for newsrooms. Publishers get the most from the cache-first read API and SSE stream. The Media & Publishers page describes that use case.
Per-sport tuning. Different sports spike differently. Cricket has long quiet stretches and sudden bursts, tennis has many parallel matches, and football clusters at fixed kickoff times. Give each its own TTLs and worker pool.
Backpressure and load shedding. When lag grows past a threshold, drop low-value events (like minute ticks) and keep goals and final results.
Autoscaling workers based on consumer lag rather than CPU.
Multi-region read replicas for the read API if your audience is global.
Wrapping Up

We took a consumer that works on a quiet Tuesday and made it survive a synchronized Saturday:

Acknowledge fast. The receiver verifies, dedupes and enqueues. Nothing slow happens inline.
Queue everything. Redis Streams absorb bursts, and consumer groups scale workers horizontally.
Make processing idempotent. Sequence gating and an atomic script make duplicates and reordering harmless.
Share the rate budget. One pause signal across all workers, jittered backoff, and Retry-After respected.
Cache like you mean it. Single-flight, stale-while-revalidate, and stale-on-error mean users never cost an upstream call.
Keep a safety net. A slow reconciliation poller and webhook replay mean "missed" doesn't mean "lost".
Test the ugly case. The simulator proves it with duplicates, shuffled order and concurrency.

If you remember one principle, make it this: decouple the rate at which data arrives from the rate at which you process it, and the rate at which users read from the rate at which you fetch. Queues and caches are just that idea applied twice.

If you build on this (an autoscaler, a metrics dashboard, a multi-sport version), share it in the comments. And if the sandbox returns a payload shape that differs from the examples here, paste it below and I'll help adapt to_fields().

Happy scaling! ⚡

Backtesting a Betting Strategy with Historical Odds Data in Python

orbistats — Wed, 07 Oct 2026 16:02:36 +0000

Every betting strategy sounds brilliant until you test it.

"Always back the home favourite." "Bet the draw when the match looks tight." "Fade the longshots." You can hear people argue about rules like these in any group chat. Almost nobody checks them against thousands of past matches.

In this tutorial we'll do exactly that. We'll build a complete backtesting pipeline in Python that:

Pulls multi-season historical results and closing odds from an API
Converts odds into implied probabilities and strips out the bookmaker's margin
Tests several strategies and reports ROI, hit rate and drawdown
Checks whether the results are statistically meaningful (or just luck)
Splits data by time, so you don't fool yourself with overfitting

I'll be honest up front: most simple strategies lose money once you test them properly. That isn't a failure of the tutorial. It's the main lesson. A backtest that tells you "don't bet this" has saved you real money.

Why Backtesting Matters

A backtest replays a rule against history and asks, "What would have happened if I had followed this rule mechanically?"

It's valuable because human memory is terrible at statistics. We remember the three times the underdog won and forget the forty times it didn't. A backtest forgets nothing.

It also teaches you the core ideas behind pricing and modelling:

Odds are prices with a margin built in. You pay that margin on every bet.
Returns are noisy. A strategy can look profitable over 100 bets and be pure luck.
The data you test on must not leak into the rule you design. This is called look-ahead bias, and it ruins more backtests than any bug.

Teams doing this professionally (trading desks, analytics teams, researchers) rely on exactly this workflow, just at larger scale.

What You'll Need
Python 3.10+
A free API key from Orbistats
Basic familiarity with pandas
About 45 minutes
Choosing a data source

Backtests are only as good as the history underneath them. The usual problems are shallow archives (two or three seasons), inconsistent team names, and a different format for history than for live data, so your model breaks the moment you deploy it.

I'm using the Orbistats Historical Sports Data API because it addresses those problems directly. It provides multi-season archives (football goes back to 2000+, most other sports to 2005 or 2010), including results, statistics, lineups and closing odds, all in the same schema as the live feed. That last point matters. A model trained on 2018 data reads identically to a match happening today, with no mapping layer in between.

Coverage differs by sport, so here's the depth the product page lists for all 13 sports:

Sport History from
Football 2000+
Basketball 2005+
American Football 2005+
Cricket 2005+
Tennis 2005+
Baseball 2010+
Combat Sports 2010+
Volleyball 2010+
Handball 2010+
Ice Hockey 2010+
Golf 2010+
Horse Racing 2010+
Esports 2015+

Treat that table as a ceiling, not a promise. Depth varies by league, and the coverage matrix in the API reference shows what's live per sport today. Check it before you pick a sport to test.

For this walkthrough I'll use English Premier League football, since it has the deepest archive and the cleanest three-way (home/draw/away) market.

Step 1: Get Your API Key and Explore
Create an account on the sign-up page and copy your key.
Read the documentation and the quickstart to see the auth and response conventions.
Try a few calls in the sandbox before writing code, so you can see the real JSON.

Authentication is a bearer token:

http
Authorization: Bearer YOUR_API_KEY

Base URL: https://api.orbistats.com/v1/

Every response uses a consistent envelope:

json
{
"data": [],
"meta": { "pagination": {}, "generated_at": "2026-08-28T10:00:00Z" },
"errors": []
}

A free key lets you explore recent seasons. Deeper archives, bulk export and higher limits sit on paid plans, so check the pricing page for what your tier includes.

Step 2: Project Setup
bash
mkdir odds-backtest && cd odds-backtest
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install requests pandas numpy matplotlib python-dotenv

Create .env:

env
ORBISTATS_API_KEY=your_key_here

And add it to .gitignore right now, before you forget:

text
.env
data_cache/
Step 3: Fetch Historical Odds and Results

Create backtest.py. First the configuration and the API client:

python
import os
import json
import time
import logging
from pathlib import Path

import numpy as np
import pandas as pd
import requests
import matplotlib.pyplot as plt
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.environ["ORBISTATS_API_KEY"]
BASE_URL = "https://api.orbistats.com/v1"

SPORT = "football"
LEAGUE = "premier-league"
SEASON_FROM = "2019-2020"
SEASON_TO = "2024-2025"

The docs show two historical routes. Confirm which one your key uses

in the sandbox, then set it here:

"history/matches" (API reference)

"historical/results" (Historical Data page; season= instead of a range)

HISTORY_PATH = "history/matches"

CACHE = Path("data_cache") / f"{SPORT}{LEAGUE}{SEASON_FROM}_{SEASON_TO}.json"
CACHE.parent.mkdir(exist_ok=True)

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("backtest")

session = requests.Session()
session.headers.update({"Authorization": f"Bearer {API_KEY}"})

Now the fetcher. Historical queries return a lot of rows, so it needs pagination, and it needs to behave when it hits a rate limit:

python
def fetch_history(sport, league, season_from, season_to, per_page=100):
url = f"{BASE_URL}/{sport}/{HISTORY_PATH}"
params = {
"league": league,
"season_from": season_from,
"season_to": season_to,
"per_page": per_page,
}
rows, page = [], 1

while True:
    resp = session.get(url, params=params, timeout=30)

    if resp.status_code == 429:
        wait = int(resp.headers.get("Retry-After", 30))
        log.warning("Rate limited, sleeping %ss", wait)
        time.sleep(wait)
        continue

    resp.raise_for_status()
    body = resp.json()
    batch = body.get("data") or []
    rows.extend(batch)
    log.info("Fetched %d rows (total %d)", len(batch), len(rows))

    pagination = (body.get("meta") or {}).get("pagination") or {}
    cursor = pagination.get("next_cursor")

    if cursor:                                   # cursor overrides page
        params["cursor"] = cursor
    elif batch and pagination.get("total") and len(rows) < pagination["total"]:
        page += 1
        params["page"] = page
    else:
        break

return rows

The reference recommends cursor pagination for large historical pulls and caps per_page at 100. Five Premier League seasons is about 1,900 matches, so that's roughly 19 requests. That's tiny compared with a 100-requests-per-minute limit, but it adds up fast if you loop over many leagues or sports.

Cache the raw response. You'll rerun your analysis dozens of times, and there's no reason to re-download history each time:

python
def load_raw():
if CACHE.exists():
log.info("Loading cached data from %s", CACHE)
return json.loads(CACHE.read_text())
raw = fetch_history(SPORT, LEAGUE, SEASON_FROM, SEASON_TO)
CACHE.write_text(json.dumps(raw))
return raw
Step 4: Turn Raw JSON into a Clean DataFrame

The API's sample match looks like this:

json
{
"fixture_id": 41207,
"home_team": "Arsenal",
"away_team": "Chelsea",
"final_score": { "home": 2, "away": 1 },
"closing_odds": { "home": 1.95, "draw": 3.60, "away": 3.80 },
"kickoff": "2024-10-27T15:30:00Z"
}

I always isolate the "messy to tidy" step in one function, so if a field name changes, there's exactly one place to edit:

python
def flatten(m: dict) -> dict | None:
try:
odds = m["closing_odds"]
score = m["final_score"]
return {
"fixture_id": m["fixture_id"],
"kickoff": m["kickoff"],
"home_team": m["home_team"],
"away_team": m["away_team"],
"home_goals": score["home"],
"away_goals": score["away"],
"odds_home": odds.get("home"),
"odds_draw": odds.get("draw"),
"odds_away": odds.get("away"),
}
except (KeyError, TypeError):
return None # skip matches with no odds or no final score

def build_frame(raw: list[dict]) -> pd.DataFrame:
rows = [r for r in map(flatten, raw) if r]
df = pd.DataFrame(rows)

df["kickoff"] = pd.to_datetime(df["kickoff"], utc=True)
for col in ("odds_home", "odds_draw", "odds_away"):
    df[col] = pd.to_numeric(df[col], errors="coerce")

df = (
    df.dropna(subset=["odds_home", "odds_away"])
      .drop_duplicates("fixture_id")
      .sort_values("kickoff")
      .reset_index(drop=True)
)

df["result"] = np.select(
    [df.home_goals > df.away_goals, df.home_goals < df.away_goals],
    ["home", "away"],
    default="draw",
)
return df

Always sanity check before you trust anything:

python
df = build_frame(load_raw())
print(len(df), "matches")
print(df["kickoff"].min(), "->", df["kickoff"].max())
print(df["result"].value_counts(normalize=True).round(3))

For a Premier League sample you should see roughly 380 matches per season, and home wins should outnumber away wins. If you see 40 matches or wildly odd percentages, something is wrong with the fetch, not the strategy.

Step 5: Understand Odds, Implied Probability and the Margin

This is the most important concept in the whole tutorial, so let's slow down.

Decimal odds convert to an implied probability:

text
implied probability = 1 / odds

Odds of 2.00 imply 50%. Odds of 4.00 imply 25%. (The glossary has plain-English definitions of these and related terms if you want a refresher.)

Now take the sample match: home 1.95, draw 3.60, away 3.80.

text
1/1.95 = 0.513
1/3.60 = 0.278
1/3.80 = 0.263
Total = 1.054

The three probabilities add up to 105.4%, not 100%. That extra 5.4% is the bookmaker's margin (the "overround" or "vig"). It's the fee you pay on every bet.

To get margin-free "fair" probabilities, divide each implied probability by the total:

text
fair home = 0.513 / 1.054 = 48.7%

Here's the consequence for backtesting. If you blindly bet every outcome at a book with a 5% margin, your expected ROI isn't zero. It's about:

text
1 / 1.05 - 1 = -4.8%

That's your baseline. A strategy has to beat roughly minus the margin just to look average. Keep this number in your head when you read the results below.

Step 6: Reshape into One Row per Selection

Here's a design decision that pays off later. Instead of one row per match with three odds columns, build a long table with one row per selection (match plus outcome). Then every strategy becomes a simple filter, and the same code works for sports with two outcomes (tennis, basketball) or three.

python
OUTCOMES = ("home", "draw", "away")

def to_selections(df: pd.DataFrame) -> pd.DataFrame:
frames = []
for o in OUTCOMES:
col = f"odds_{o}"
part = df[["fixture_id", "kickoff", "home_team", "away_team", "result", col]]
part = part.rename(columns={col: "odds"}).assign(outcome=o)
frames.append(part)

sel = pd.concat(frames).dropna(subset=["odds"])

sel["implied"] = 1 / sel["odds"]
sel["overround"] = sel.groupby("fixture_id")["implied"].transform("sum")
sel["fair_p"] = sel["implied"] / sel["overround"]
sel["won"] = sel["outcome"] == sel["result"]
# rank 1 = shortest price = the favourite
sel["rank"] = sel.groupby("fixture_id")["odds"].rank(method="first")
sel["profit"] = np.where(sel["won"], sel["odds"] - 1, -1.0)   # 1-unit flat stake

return sel.sort_values(["kickoff", "fixture_id"]).reset_index(drop=True)

sel = to_selections(df)
print("Average margin: {:.2%}".format(sel.groupby("fixture_id")["overround"].first().mean() - 1))

That last line tells you the typical margin in your dataset. Use it to compute your baseline ROI from Step 5.

Step 7: Define Strategies as Simple Rules

Each strategy is just a function that returns a boolean mask over the selections table:

python
def is_underdog(s):
return s["rank"] == s.groupby("fixture_id")["rank"].transform("max")

STRATEGIES = {
"Always home": lambda s: s["outcome"] == "home",
"Always draw": lambda s: s["outcome"] == "draw",
"Always away": lambda s: s["outcome"] == "away",
"Favourite": lambda s: s["rank"] == 1,
"Underdog": is_underdog,
"Longshots (p<12%)": lambda s: s["fair_p"] < 0.12,
"Tight games: draw": lambda s: (s["outcome"] == "draw") & (s["fair_p"] > 0.27),
}

These aren't meant to be winners. They're a spread of the kinds of rules people actually believe in, so you can see how the margin treats each one.

Step 8: Run the Backtest and Measure Results
python
def run_strategy(sel: pd.DataFrame, mask) -> pd.DataFrame:
bets = sel[mask(sel)].copy().sort_values("kickoff")
bets["cum"] = bets["profit"].cumsum()
return bets

def summarize(bets: pd.DataFrame) -> dict:
n = len(bets)
if n == 0:
return {"bets": 0}
peak = np.maximum(bets["cum"].cummax(), 0)
return {
"bets": n,
"hit_rate_%": round(100 * bets["won"].mean(), 1),
"avg_odds": round(bets["odds"].mean(), 2),
"profit_units": round(bets["profit"].sum(), 1),
"roi_%": round(100 * bets["profit"].mean(), 2),
"max_drawdown": round((bets["cum"] - peak).min(), 1),
}

results = {name: run_strategy(sel, rule) for name, rule in STRATEGIES.items()}
report = pd.DataFrame({name: summarize(b) for name, b in results.items()}).T
print(report.sort_values("roi_%", ascending=False))
How to read the table
bets: sample size. Be suspicious of any strategy with fewer than a few hundred.
hit_rate_%: how often it wins. Meaningless without the average odds next to it.
avg_odds: a 25% hit rate at average odds of 4.5 is a very different story from 25% at 2.5.
roi_%: profit divided by total staked. The number everyone cares about.
max_drawdown: the worst peak-to-trough fall in units. This is the pain you'd have to sit through, and it's what actually makes people abandon strategies.

Expect most rows to land near your baseline (minus the margin) with some noise. That's the market being reasonably efficient. If a strategy shows a big positive ROI, don't celebrate yet. Move to the next step.

Step 9: Is It Skill or Luck? Bootstrap the ROI

A strategy that made +6% over 300 bets might simply have gotten lucky. A bootstrap estimates how much the ROI could wobble by resampling your bets with replacement:

python
def bootstrap_roi(bets: pd.DataFrame, n_boot: int = 2000, seed: int = 42):
rng = np.random.default_rng(seed)
p = bets["profit"].to_numpy()
means = rng.choice(p, size=(n_boot, len(p)), replace=True).mean(axis=1) * 100
low, high = np.percentile(means, [2.5, 97.5])
return round(low, 2), round(high, 2)

for name, bets in results.items():
if len(bets) >= 100:
lo, hi = bootstrap_roi(bets)
print(f"{name:<22} 95% CI for ROI: [{lo:>6}%, {hi:>6}%]")

The rule of thumb: if the 95% interval includes zero (or your baseline), you cannot claim the strategy has an edge. Nearly every simple strategy fails this test, and learning to see that is half of what makes a good analyst.

Step 10: Check Calibration (Where Edges Actually Hide)

Instead of testing random rules, ask the data a sharper question: are the market's probabilities well calibrated? If outcomes priced at 10% really win 10% of the time, there's no free lunch. If they win 12%, there might be.

python
def calibration(sel: pd.DataFrame) -> pd.DataFrame:
bins = [0, .05, .10, .15, .20, .30, .40, .50, .60, .80, 1.0]
s = sel.copy()
s["bin"] = pd.cut(s["fair_p"], bins=bins)
return (
s.groupby("bin", observed=True)
.agg(n=("won", "size"),
fair_p=("fair_p", "mean"),
actual=("won", "mean"),
roi_pct=("profit", lambda x: 100 * x.mean()))
.round(3)
)

print(calibration(sel))

Compare fair_p to actual in each row. A well-known pattern in betting markets is the favourite-longshot bias: very long shots are often overpriced and heavy favourites slightly underpriced. Whether it shows up in your sample, and whether it survives the margin, is exactly the kind of thing a backtest can tell you. It's also a much better starting point for a model than a gut feeling.

Step 11: Avoid the #1 Backtesting Mistake (Overfitting)

Here's how people fool themselves. They try 50 rules, pick the one with the best ROI, and report it. But if you test 50 rules on the same data, a few will look great by pure chance.

The fix is simple: tune on the past, judge on the future.

python
cut = sel["kickoff"].sort_values().iloc[int(len(sel) * 0.6)]
train, test = sel[sel["kickoff"] <= cut], sel[sel["kickoff"] > cut]

best_thr, best_roi = None, -999
for thr in [0.06, 0.08, 0.10, 0.12, 0.15, 0.18]:
roi = 100 * train.loc[train["fair_p"] < thr, "profit"].mean()
print(f"train fair_p < {thr:.2f}: ROI {roi:6.2f}%")
if roi > best_roi:
best_thr, best_roi = thr, roi

test_roi = 100 * test.loc[test["fair_p"] < best_thr, "profit"].mean()
print(f"\nChosen threshold: {best_thr} train ROI {best_roi:.2f}% test ROI {test_roi:.2f}%")

If the test ROI collapses compared with the train ROI, you found noise, not an edge. That gap is the honest measure of how much a strategy is worth.

For something stricter, try walk-forward testing: tune on seasons 1 to 3, test on season 4, then tune on seasons 1 to 4, test on season 5, and so on. It mimics how you'd actually use the rule in real life.

Step 12: Visualize the Equity Curves

Numbers are great, but a picture of the drawdowns makes the risk feel real:

python
def plot_curves(results: dict):
fig, ax = plt.subplots(figsize=(11, 6))
for name, bets in results.items():
if len(bets):
ax.plot(bets["kickoff"], bets["cum"], label=name, linewidth=1.4)
ax.axhline(0, color="grey", linewidth=0.8)
ax.set_title("Cumulative profit by strategy (1-unit flat stakes)")
ax.set_ylabel("Profit (units)")
ax.legend(fontsize=8)
fig.tight_layout()
fig.savefig("equity_curves.png", dpi=150)

plot_curves(results)

You'll almost certainly see lines that drift downward at roughly the rate the margin predicts, with some noisy detours. Strategies that look profitable for six months and then fall off a cliff are the classic shape of a fluke.

Step 13: Simulate a Real Bankroll

Flat one-unit stakes are clean for analysis, but real money compounds. Here's a quick bankroll simulation staking a fixed percentage:

python
def simulate_bankroll(bets: pd.DataFrame, start=1000.0, pct=0.01) -> pd.Series:
bankroll, path = start, []
for _, b in bets.iterrows():
stake = bankroll * pct
bankroll += stake * (b["odds"] - 1) if b["won"] else -stake
path.append(bankroll)
return pd.Series(path, index=bets["kickoff"].values)

curve = simulate_bankroll(results["Favourite"])
print(f"Start 1000 -> End {curve.iloc[-1]:.0f}")

A note on Kelly staking: the formula f = (p*odds - 1) / (odds - 1) is popular, but it requires your own estimate of the true probability p. Plugging in the market's probability just gives you zero or negative stakes. Kelly is only as good as your model, and most people overestimate their model. Fractional Kelly (a quarter or half) is far safer.

Step 14: Run the Whole Thing

Add the entry point at the bottom of backtest.py:

python
if name == "main":
df = build_frame(load_raw())
sel = to_selections(df)

results = {n: run_strategy(sel, r) for n, r in STRATEGIES.items()}
report = pd.DataFrame({n: summarize(b) for n, b in results.items()}).T
print(report.sort_values("roi_%", ascending=False).to_string())

print("\nCalibration:")
print(calibration(sel).to_string())

plot_curves(results)

bash
python backtest.py
Pulling Much More Data: Bulk Export

REST pagination is fine for a few thousand matches. If you want ten seasons across several leagues, the historical product page documents a bulk export that returns whole seasons as a compressed file, instead of paging through thousands of calls. The documented request body looks like this:

http
POST /v1/football/historical/export

{
"league": "premier-league",
"seasons": ["2020", "2021", "2022", "2023", "2024"],
"include": ["results", "statistics", "odds"],
"format": "json"
}

Check your plan's access and the exact response behaviour in the docs before relying on it, since bulk export is listed as an upgraded feature.

Taking It to Other Sports

Because the historical data uses one schema for every sport, our to_selections design carries over with almost no changes. A few notes:

Two-way markets like tennis have no draw, so odds_draw is simply missing and the code drops it. Remember that "favourite" strategies behave very differently when the favourite wins 70% of the time.
Basketball is high-scoring and usually has no draw, so margins and calibration look different from football.
Cricket has formats (Test, ODI, T20) with different draw probabilities. Test each format separately rather than mixing them.
Coverage varies. The coverage matrix currently shows historical data for most sports, but not every one. Verify before building around a specific sport.

For the thirteen sports Orbistats lists, the same pipeline works wherever history exists: football, basketball, American football, cricket, tennis, baseball, esports, combat sports, volleyball, handball, ice hockey, golf and horse racing. Start with the deepest archives (football, basketball) while you learn.

Closing Line Value: A Better Test Than ROI

ROI over a few hundred bets is mostly noise. Professionals often use a different yardstick: closing line value (CLV). The idea is that the closing price is the market's most informed estimate. If you consistently bet at prices better than the close, you're probably finding real information, even before the profits show up.

To measure CLV you need an opening or intermediate price and the close. The historical odds documentation mentions closing lines on all plans and full line-movement history on higher plans, which is what makes this kind of analysis possible. If you're building something for a trading team, that's the data to look at; the Trading Desks page describes the use case, and the Analytics & Data Science page covers research-style workloads.

Common Backtesting Pitfalls (Read This Twice)
Look-ahead bias. Never use information that wasn't available at bet time. Final scores, end-of-season standings and post-match statistics are all off-limits for pre-match decisions.
Closing-odds optimism. You usually can't bet at the exact closing price, and stake limits and price changes apply. Treat closing-odds backtests as an upper bound.
Ignoring the margin. Always compare results to the baseline from Step 5, not to zero.
Tiny samples. Under a few hundred bets, almost anything can look good.
Data snooping. Every extra rule you try inflates the chance of a false discovery. Keep a held-out test set and touch it once.
Survivorship and coverage gaps. Check that every season has about the right number of matches, and look for leagues or periods with missing odds.
Ignoring drawdowns. A strategy with great ROI and a 60-unit drawdown is one you will probably abandon at the worst moment.
Ideas to Extend This Project
Fit a simple model (Elo ratings, Poisson goals, logistic regression) and compare its probabilities against the market's
Test Asian handicap, totals and over/under markets, not just 1X2
Add team form and statistics as features using the statistics endpoints
Compare strategies by season to see if an edge decays over time
Link this to a live system: backtest a rule, then feed it with the Odds API (note it requires an upgraded plan) so the live and historical data share the same schema
Wrapping Up

In one script we built a real backtesting pipeline:

Fetched multi-season results and closing odds via a paginated, rate-limit-aware client
Cleaned the data into a tidy DataFrame
Converted odds into implied and margin-free probabilities
Tested several strategies as simple filters
Measured ROI, hit rate and drawdown
Stress-tested the findings with bootstrap confidence intervals
Validated with a time-based train/test split

If you remember one thing, make it this: the goal of a backtest isn't to find a winner. It's to find out cheaply whether something deserves your trust. Most ideas won't. The few that survive an honest test are the only ones worth taking further.

If you build something on top of this (a walk-forward tester, a calibration dashboard, a multi-sport comparison), share it in the comments. And if the sandbox returns a different JSON shape than the sample I used, paste it below and I'll help adapt the flatten() function.

Happy testing! 📊

Build an Odds Movement Alert Bot in Python (Telegram & Discord)

orbistats — Wed, 07 Oct 2026 15:59:12 +0000

If you have ever watched a price move on a betting market and thought, "I wish I had known five minutes earlier," this tutorial is for you.

Odds don't change randomly. A sharp drop on the home side can mean injury news, lineup leaks, or heavy money. Traders, analysts, and fantasy players all care about that signal. Almost none of them want to stare at a dashboard all day.

So in this guide we'll build a Python bot that watches odds, detects meaningful movement, and pushes an alert to Telegram and Discord the moment it happens.

By the end you'll have:

A polling loop that fetches odds from a REST API
A movement detector with configurable thresholds
Telegram and Discord notifications
Duplicate-alert protection and sane rate-limit handling
A clear upgrade path to WebSockets for real-time use

Let's build it.

Why Odds Movement Matters

Odds are a market price. Like any price, the change is often more informative than the level.

Football: a 1X2 home price falling from 2.10 to 1.85 within an hour often signals confirmed lineups or sharp money.
Tennis: a sudden drift on a favourite can mean an injury or a fitness doubt before it's public.
Basketball and American Football: spread and total movements reflect late injury reports.
Cricket: toss results and pitch conditions swing prices quickly.

The same logic applies in every sport. A bot that watches these moves for you is simple to build, and it's a good project for learning API polling, state tracking, and notification design.

What You'll Need
Python 3.10+
A free API key from Orbistats
A Telegram account (for a bot token) and/or a Discord server (for a webhook)
About 30 minutes
Choosing a data source

An alert bot is only as good as its data. The painful part of odds data is that every bookmaker has its own format, so you end up writing and maintaining a different parser for each. A normalized odds feed removes that work: one schema, one parser.

That's why I'm using the Orbistats Odds API. It returns pre-match and live odds (1X2, moneyline, spreads, totals, and more) in one consistent structure. It also covers 13 sports: football, basketball, American football, cricket, tennis, baseball, esports, combat sports, volleyball, handball, ice hockey, golf, and horse racing. So the bot we build works across all of them with almost no changes.

The free tier is enough for this tutorial, and I'll show how to stay inside its limits.

Step 1: Get Your API Key
Create an account on the sign-up page.
Copy your API key from the dashboard.
Skim the documentation and the quickstart.

Authentication is a standard bearer token:

http
Authorization: Bearer YOUR_API_KEY

The base URL is:

text
https://api.orbistats.com/v1/

If you'd like to experiment before writing any code, the sandbox lets you fire requests and inspect the JSON directly.

Step 2: Project Setup
bash
mkdir odds-alert-bot && cd odds-alert-bot
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install requests python-dotenv

Create a .env file:

env
ORBISTATS_API_KEY=your_key_here

TELEGRAM_BOT_TOKEN=123456:ABC-your-token
TELEGRAM_CHAT_ID=your_chat_id

DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

SPORT=football
MARKET=1X2
MOVE_THRESHOLD_PCT=5
POLL_SECONDS=600

Getting the Telegram values:

Message @botfather, send /newbot, and copy the token.
Send any message to your new bot.
Open https://api.telegram.org/bot/getUpdates and read chat.id from the response.

Getting the Discord webhook: Server Settings → Integrations → Webhooks → New Webhook → Copy URL.

Step 3: Fetch Odds

Create bot.py. We'll start with configuration and the API client.

python
import os
import time
import logging
import requests
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.environ["ORBISTATS_API_KEY"]
BASE_URL = "https://api.orbistats.com/v1"

SPORT = os.getenv("SPORT", "football")
MARKET = os.getenv("MARKET", "1X2")
THRESHOLD = float(os.getenv("MOVE_THRESHOLD_PCT", "5"))
POLL_SECONDS = int(os.getenv("POLL_SECONDS", "600"))

TG_TOKEN = os.getenv("TELEGRAM_BOT_TOKEN")
TG_CHAT = os.getenv("TELEGRAM_CHAT_ID")
DISCORD_URL = os.getenv("DISCORD_WEBHOOK_URL")

logging.basicConfig(
level=logging.INFO,
format="%(asctime)s %(levelname)s %(message)s",
)
log = logging.getLogger("odds-bot")

session = requests.Session()
session.headers.update({"Authorization": f"Bearer {API_KEY}"})

def fetch_odds(sport: str, market: str) -> list[dict]:
"""Fetch current odds for one sport/market.

NOTE: confirm the exact path and query params in the API Reference.
"""
url = f"{BASE_URL}/{sport}/odds"
resp = session.get(url, params={"market": market}, timeout=15)
resp.raise_for_status()
payload = resp.json()
# Some APIs wrap results in {"data": [...]}; handle both shapes.
return payload.get("data", payload) if isinstance(payload, dict) else payload

The path and parameters above follow the pattern used in the docs examples (/v1/football/...). Check the API reference for the exact odds route and field names, and adjust the one function above if they differ.

Step 4: Normalize the Data

Even with a normalized API, I like to add one more layer in my own code: a function that converts whatever the API returns into a small internal shape. If the response format ever changes, you only edit this one function.

python
def normalize(item: dict) -> dict | None:
"""Turn one API item into {key, label, prices}.

Expected input resembles:
{
  "match_id": "match_50231",
  "home": {"name": "Manchester City"},
  "away": {"name": "Arsenal"},
  "market": "1X2",
  "odds": {"home": 1.91, "draw": 3.40, "away": 4.20}
}
"""
try:
    match_id = item["match_id"]
    home = item["home"]["name"] if isinstance(item["home"], dict) else item["home"]
    away = item["away"]["name"] if isinstance(item["away"], dict) else item["away"]
    prices = {k: float(v) for k, v in item["odds"].items()}
except (KeyError, TypeError, ValueError):
    return None

return {
    "key": f"{match_id}:{item.get('market', MARKET)}",
    "label": f"{home} vs {away}",
    "prices": prices,
}

Step 5: Detect Odds Movement

This is the heart of the bot. We store the last seen price for every outcome and compare each new reading against it.

We use percentage change rather than absolute change. A move from 1.20 to 1.30 is very different from 8.00 to 8.10, and percentages handle both fairly.

python
last_seen: dict[str, dict[str, float]] = {}

def pct_change(old: float, new: float) -> float:
return (new - old) / old * 100

def detect_moves(match: dict) -> list[dict]:
"""Compare current prices to the previous snapshot."""
key, prices = match["key"], match["prices"]
previous = last_seen.get(key)
moves = []

if previous:
    for outcome, new_price in prices.items():
        old_price = previous.get(outcome)
        if old_price is None or old_price == 0:
            continue
        change = pct_change(old_price, new_price)
        if abs(change) >= THRESHOLD:
            moves.append({
                "outcome": outcome,
                "old": old_price,
                "new": new_price,
                "pct": change,
            })

# Always update the snapshot so the next poll compares to now.
last_seen[key] = prices
return moves

Notice that the first poll produces no alerts. It only records a baseline. That's intentional: you can't call something a "movement" without a before and an after.

Reading the direction
Odds shortening (price falls): the market considers the outcome more likely.
Odds drifting (price rises): the market considers it less likely.

We'll show this with an arrow in the message so it reads at a glance.

Step 6: Send Telegram Alerts
python
def format_alert(match: dict, move: dict) -> str:
arrow = "📉 shortened" if move["pct"] < 0 else "📈 drifted"
return (
f"⚡ Odds movement: {match['label']}\n"
f"Outcome: {move['outcome'].upper()}\n"
f"{move['old']:.2f} → {move['new']:.2f} "
f"({move['pct']:+.1f}%) {arrow}"
)

def send_telegram(text: str) -> None:
if not (TG_TOKEN and TG_CHAT):
return
url = f"https://api.telegram.org/bot{TG_TOKEN}/sendMessage"
r = requests.post(url, json={"chat_id": TG_CHAT, "text": text}, timeout=10)
if not r.ok:
log.warning("Telegram failed: %s %s", r.status_code, r.text[:200])
Step 7: Send Discord Alerts

Discord webhooks are even simpler. There's no bot account and no OAuth, just a POST.

python
def send_discord(text: str) -> None:
if not DISCORD_URL:
return
r = requests.post(DISCORD_URL, json={"content": text}, timeout=10)
if not r.ok:
log.warning("Discord failed: %s %s", r.status_code, r.text[:200])

def notify(text: str) -> None:
send_telegram(text)
send_discord(text)

Want richer messages? Discord supports embeds, with colors, fields, and timestamps. A green embed for shortening and a red one for drifting looks great in a trading channel.

Step 8: The Main Loop (With Rate-Limit Awareness)

Here's the part many tutorials skip. Polling costs requests. On the free tier you get a limited number per day (150 at the time of writing, per the docs, so always double-check your plan on the pricing page).

Do the math before choosing an interval:

text
86,400 seconds/day ÷ 600 seconds = 144 requests/day

A 10-minute interval for a single sport fits inside 150 requests per day. If you poll five sports every minute, you'll burn through the limit in minutes.

python
def run_once() -> int:
alerts = 0
for raw in fetch_odds(SPORT, MARKET):
match = normalize(raw)
if not match:
continue
for move in detect_moves(match):
notify(format_alert(match, move))
alerts += 1
return alerts

def main() -> None:
log.info("Starting odds bot: sport=%s market=%s threshold=%s%%",
SPORT, MARKET, THRESHOLD)
backoff = 1
while True:
try:
sent = run_once()
log.info("Poll complete, alerts sent: %d", sent)
backoff = 1
time.sleep(POLL_SECONDS)
except requests.HTTPError as e:
status = e.response.status_code if e.response is not None else "?"
if status == 429:
wait = min(backoff * 60, 900)
log.warning("Rate limited. Sleeping %ss", wait)
time.sleep(wait)
backoff *= 2
else:
log.error("HTTP error: %s", e)
time.sleep(30)
except requests.RequestException as e:
log.error("Network error: %s", e)
time.sleep(30)

if name == "main":
main()

Run it:

bash
python bot.py

On the first poll you'll see a baseline. After the next one, any outcome that moved beyond your threshold fires an alert in both channels.

Step 9: Avoid Alert Spam (Cooldowns)

A price can wobble around your threshold and fire repeatedly. Add a cooldown so each outcome alerts at most once per window:

python
COOLDOWN_SECONDS = 1800
last_alert_at: dict[str, float] = {}

def should_alert(match_key: str, outcome: str) -> bool:
k = f"{match_key}:{outcome}"
now = time.time()
if now - last_alert_at.get(k, 0) < COOLDOWN_SECONDS:
return False
last_alert_at[k] = now
return True

Then in run_once:

python
for move in detect_moves(match):
if should_alert(match["key"], move["outcome"]):
notify(format_alert(match, move))
alerts += 1
Step 10: Make It Work for All 13 Sports

Because the data is normalized, supporting more sports is mostly configuration. Loop over a list:

python
SPORTS = ["football", "basketball", "tennis", "cricket"]

Then call fetch_odds(sport, MARKET) for each. Keep the request math in mind. Four sports at 10 minutes means 576 calls a day, which exceeds the free tier but fits comfortably on a paid plan.

Each sport has its own coverage details and quirks, so browse the sport pages for what's available:

Football and Basketball for the highest-volume markets
Cricket and Tennis for fast-moving live prices
Esports and Horse Racing if you want niche markets with less competition

One tip: different sports suit different thresholds. Tennis moves quickly, so use a higher threshold (8 to 10%). Football 1X2 is steadier, so 4 to 5% is a good start. Store a threshold per sport in a dict.

Going Real-Time: From Polling to WebSockets

Polling has one fundamental weakness: you only see the market every N minutes. A move that happens and reverses between two polls is invisible.

For true real-time alerts, switch from request/response to a persistent connection. The WebSocket API pushes updates to you as they happen, so you stop polling and stop worrying about request quotas.

The change to our bot is small. Everything after the data arrives (normalize, detect_moves, notify) stays identical. Only the source changes:

python

Conceptual sketch, check the WebSocket docs for the real URL and message format

import json, websocket

def on_message(ws, message):
data = json.loads(message)
match = normalize(data)
if match:
for move in detect_moves(match):
if should_alert(match["key"], move["outcome"]):
notify(format_alert(match, move))

ws = websocket.WebSocketApp(
"wss://",
header={"Authorization": f"Bearer {API_KEY}"},
on_message=on_message,
)
ws.run_forever(reconnect=5)

If you'd rather not hold a connection open yourself, webhooks are the third option. The provider calls your URL when something changes, so you can host a tiny Flask or FastAPI endpoint and let the events come to you.

Which should you pick?

Method Best for Trade-off
REST polling Learning, low-volume, free tier Delayed, uses quota
WebSocket Live odds, trading-style alerts Needs reconnect logic
Webhooks Server-side event handling Needs a public endpoint
Add Historical Context (Optional but Powerful)

Here's a trick that makes alerts far more useful: attach context. Is a 6% move big or normal for this market?

Historical data lets you answer that. If you store past movement per market, you can alert only on moves that exceed the typical volatility, instead of using one fixed number. The Historical Sports Data API provides multi-season archives, including closing odds, which are ideal for backtesting your thresholds before you trust them with real decisions.

If you want to go deeper, the Sports Statistics API lets you combine movement with form and team stats, so an alert reads "Home price shortened 6% and they are unbeaten in five" instead of just a number.

Deploying the Bot

A bot on your laptop stops when your laptop sleeps. A few easy options:

A small VPS (any $5/month box) with systemd keeping the script alive
Docker on a home server or Raspberry Pi
A free-tier cloud VM for light usage

A minimal systemd unit:

ini
[Unit]
Description=Odds Movement Alert Bot
After=network-online.target

[Service]
WorkingDirectory=/opt/odds-alert-bot
ExecStart=/opt/odds-alert-bot/.venv/bin/python bot.py
Restart=always
RestartSec=10
EnvironmentFile=/opt/odds-alert-bot/.env

[Install]
WantedBy=multi-user.target

Then:

bash
sudo systemctl enable --now odds-bot
journalctl -u odds-bot -f
Production Checklist

Before you rely on this, run through the list:

Persist state. Right now last_seen lives in memory, so a restart means a fresh baseline. Use SQLite or Redis if you care about continuity.
Never commit .env. Add it to .gitignore.
Handle API changes. Check the changelog and the status page when something looks off.
Log everything. When an alert doesn't fire, logs tell you why.
Respect quotas. Track your own request count and log it daily.
Treat alerts as information, not advice. Odds movement is a signal. It isn't a guarantee of anything.
Ideas to Extend This Project

Once the basics work, there's a lot of room to grow:

Slash commands (/watch Arsenal) so users choose what to track
Multi-bookmaker comparison, alerting when one price diverges from the rest
Charts, rendering a mini odds-history image with matplotlib and attaching it to the alert
Per-user thresholds stored in a database
Steam-move detection, flagging when several outcomes move together
A web dashboard built on top of the same detector

If you want ready-made code for each endpoint, the examples page and the SDKs are worth a look, and the guides cover related topics.

Full Project Structure
text
odds-alert-bot/
├── .env
├── .gitignore
├── bot.py
└── requirements.txt

requirements.txt:

text
requests
python-dotenv
websocket-client # only if you add the WebSocket version
Wrapping Up

We built a complete alert pipeline in under 150 lines:

Fetch odds from a normalized API
Normalize them into your own small shape
Detect percentage movement against the last snapshot
Filter with thresholds and cooldowns
Notify through Telegram and Discord

The architecture is deliberately modular. Swap polling for WebSockets, add more sports, or bolt on statistics, and the core logic barely changes. That's the real advantage of building on a clean, normalized data layer: your effort goes into your product, not into parsing.

If you build something with this, I'd love to hear about it in the comments. And if you hit a snag, drop your error message below and I'll help debug.

Happy building! 🚀

Disclaimer: This tutorial is for educational and informational purposes. Odds data is not financial or betting advice. Please follow the laws and regulations in your region.

Build a Live Odds Comparison Dashboard with React and WebSockets in One Evening

orbistats — Wed, 07 Oct 2026 15:55:27 +0000

Liquid syntax error: Variable '{{% raw %}' was not properly terminated with regexp: /\}\}/

How to Debug "Laggy" Live Scores: Finding Where Your Latency Is Actually Coming From

orbistats — Tue, 06 Oct 2026 16:09:39 +0000

Your users say the live score is "laggy". Your first instinct is probably to blame the API. Your API provider's first instinct is to blame your code. Both of you may be wrong.

"Laggy" is not a measurement. It's a feeling, and that feeling can come from at least eight different places: DNS, TLS handshakes, a polling interval, a CDN cache, a blocked main thread, a backgrounded browser tab, a slow webhook queue, or the broadcast itself being 20 seconds behind the stadium (more on that last one later).

This post is a practical debugging playbook. We'll instrument every hop between "something happened on the pitch" and "a pixel changed on screen", then use the numbers to find the real culprit. Code examples use the Orbistats Live Scores API, but the technique works with any provider.

Note on numbers: I don't quote benchmark results in this post. Every table is a template you fill with your own measurements.

Table of contents
First, define "laggy" precisely
Map the pipeline
Step 1: Rule out the network layer with curl
Step 2: Check your polling interval math
Step 3: Add per-hop timestamps
Step 4: Fix your clocks before trusting any number
Step 5: Measure delivery over WebSocket
Step 6: Catch main-thread and render lag in the browser
Step 7: Webhook pipelines and queue delay
The "not actually lag" cases
A diagnostic decision tree
Build a staleness monitor
Final checklist and next steps

First, define "laggy" precisely

Before touching code, get a reproducible complaint. Ask for or capture:

Which match, which event (goal, card, score change)?
What time did they see it, and what did a reference source show?
Which device, browser and network (Wi-Fi, mobile data)?
Is the lag constant, or does it spike?

"Constant 10 seconds late" and "occasionally 3 seconds late" are different bugs. Constant offset usually means a polling interval or caching layer. Spikes usually mean reconnects, garbage collection, a throttled tab or network jitter.

Map the pipeline

Every live score travels through the same stages:

text
Real-world event
↓ (A) data source / provider ingestion
Provider system
↓ (B) provider delivery: REST / WebSocket / Webhook
Network
↓ (C) your ingest server
Your backend (parse, cache, fan-out)
↓ (D) your delivery to clients
Network again
↓ (E) browser/app receives bytes
Client JS (parse, state update)
↓ (F) render
Pixel on screen

Providers control A and B. You control C through F. Your goal is to put a timestamp at every arrow so you can subtract and see which segment is fat. Orbistats positions its live feed as a sub-50ms system, and it has written about what sub-50ms actually requires, end to end. That claim concerns the provider side. Everything after it is yours.

Here's the table to fill in:

Segment What it covers Your measured p50 Your measured p95
A→B Event → provider emits ? ?
B→C Provider → your server ? ?
C→D Your server → your fan-out ? ?
D→E Your server → client bytes ? ?
E→F Client bytes → pixel ? ?

Step 1: Rule out the network layer with curl

Start with the cheapest test. curl can break a single request into its phases:

bash
cat > curl-format.txt <<'EOF'
dns: %{time_namelookup}s
tcp: %{time_connect}s
tls: %{time_appconnect}s
ttfb: %{time_starttransfer}s
total: %{time_total}s
size: %{size_download} bytes
EOF

curl -s -o /dev/null -w "@curl-format.txt" \
-H "Authorization: Bearer $ORBISTATS_KEY" \
https://api.orbistats.com/v1/football/matches/live

How to read it (the values are cumulative, so subtract neighbours):

dns high → resolver problem; try a different DNS or cache lookups.
tcp − dns → raw network distance to the server.
tls − tcp → handshake cost. If this appears on every request, you're not reusing connections.
ttfb − tls → server think time plus the first-byte trip.
total − ttfb → payload download time; large for big responses.

Run it 20 times, not once:

bash
for i in $(seq 1 20); do
curl -s -o /dev/null -w "%{time_starttransfer}\n" \
-H "Authorization: Bearer $ORBISTATS_KEY" \
https://api.orbistats.com/v1/football/matches/live
done | sort -n

The sorted list gives you a feel for median and tail. If the first request is slow and the rest are fast, that's connection setup, which you can fix with keep-alive.

Fix: reuse connections

In Node 20+, the built-in fetch (undici) already pools connections, but a naive script that spawns a new process per poll never benefits. If you're on an older HTTP client, enable keep-alive explicitly:

js
import https from "node:https";
const agent = new https.Agent({ keepAlive: true, maxSockets: 10 });
// pass { agent } to your requests

Not sure about the exact live endpoint for a given sport? The API reference lists every route, and the Sandbox lets you try requests in the browser first.

Step 2: Check your polling interval math

If you poll, the single biggest source of "lag" is simply the interval. It's arithmetic, not a bug:

Average added delay = interval / 2
Worst case = interval
Poll interval Average staleness Worst case
30 s 15 s 30 s
10 s 5 s 10 s
5 s 2.5 s 5 s
1 s 0.5 s 1 s

Now stack the layers. This is the classic trap:

text
Your frontend polls your backend every 10 s
Your backend polls the provider every 10 s
↓
Worst case staleness = 10 s + 10 s = 20 s
Average = 5 s + 5 s = 10 s

Two chained pollers add their staleness. If users report "about 10 seconds behind", check for exactly this setup before suspecting anything exotic.

Also check request budgets. A plan with a daily request cap (see the pricing page for current limits) can't sustain a 1-second poll for long. If you silently hit a 429 and your code keeps showing the last cached score, the UI looks frozen. Log every non-200:

js
const res = await fetch(url, { headers });
if (!res.ok) {
console.warn("poll failed", res.status, res.headers.get("retry-after"));
}

Step 3: Add per-hop timestamps

Now we instrument. The idea is to stamp the message at every hop and carry the stamps forward, so the browser can compute every segment.

js
// ingest.js - runs on YOUR server when data arrives from the provider
function stampIngest(providerMsg) {
return {
...providerMsg,
_t: {
// provider's own event time, if present in the payload (check the docs for the field name)
provider: providerMsg.timestamp ?? null,
ingest: Date.now(), // when YOUR server received it
},
};
}

// gateway.js - just before sending to browsers
function stampEmit(msg) {
msg._t.emit = Date.now(); // when YOUR server sent it to clients
return msg;
}

And in the browser:

js
// client.js
socket.onmessage = (e) => {
const msg = JSON.parse(e.data);
msg._t.recv = Date.now(); // bytes arrived

requestAnimationFrame(() => {
paint(msg);
msg._t.paint = Date.now(); // pixel updated (approx.)
report(msg._t);
});
};

function report(t) {
const seg = {
provider_to_ingest: t.provider ? t.ingest - t.provider : null,
ingest_to_emit: t.emit - t.ingest,
emit_to_recv: t.recv - t.emit, // network + client clock skew!
recv_to_paint: t.paint - t.recv,
total: t.paint - (t.provider ?? t.ingest),
};
navigator.sendBeacon("/metrics/latency", JSON.stringify(seg));
}

Ship these segments to whatever metrics store you use (even a simple log line works) and aggregate p50 / p95 / p99 per segment. The fattest segment is where you look next.

Don't average. If p50 is fine and p99 is terrible, users remember the p99.

Step 4: Fix your clocks before trusting any number

This is the step that makes or breaks the whole exercise. emit_to_recv compares a server clock with a browser clock. If those disagree by 400 ms, your "network latency" is off by 400 ms, and could even go negative.

Estimate the client's offset against your server with an NTP-style handshake. Use your own endpoint that returns milliseconds (the HTTP Date header only has one-second resolution, which is too coarse):

js
// server: GET /time -> { now: Date.now() }
app.get("/time", (_req, res) => res.json({ now: Date.now() }));
js
// client
async function estimateOffset(samples = 8) {
const results = [];
for (let i = 0; i < samples; i++) {
const t0 = Date.now();
const { now: serverNow } = await (await fetch("/time", { cache: "no-store" })).json();
const t1 = Date.now();
const rtt = t1 - t0;
const offset = serverNow - (t0 + rtt / 2); // assumes symmetric path
results.push({ rtt, offset });
}
// Trust the sample with the smallest RTT: least queueing noise.
results.sort((a, b) => a.rtt - b.rtt);
return results[0].offset;
}

const offset = await estimateOffset();
// later: serverTimeNow ≈ Date.now() + offset

Then correct your measurements: emit_to_recv = (recv + offset) - emit.

On your servers, make sure NTP/chrony is running. Two machines with drifting clocks will produce phantom latency between your ingest and gateway nodes too.

Step 5: Measure delivery over WebSocket

If you already stream, "lag" usually has a different set of suspects than polling. Check these in order:

(a) Is the socket actually alive? A half-open TCP connection looks connected but delivers nothing, for minutes. Use heartbeats and a "last message seen" watchdog:

js
let lastMsgAt = Date.now();

ws.on("message", () => { lastMsgAt = Date.now(); });

setInterval(() => {
if (Date.now() - lastMsgAt > 30_000) {
console.warn("socket silent for 30s, forcing reconnect");
ws.terminate(); // triggers your reconnect logic
}
}, 5_000);

During live play on a busy match, 30 seconds of silence is already suspicious. Tune the threshold to your sport: a golf round has long quiet stretches, while a basketball game rarely does.

(b) Are you applying backpressure correctly? If your handler does slow work (database writes, heavy JSON) inside the message callback, messages queue up behind it and every later update looks "late". Keep the handler tiny:

js
ws.on("message", (raw) => {
const msg = JSON.parse(raw);
latestState.set(msg.match_id, msg); // O(1) state write
scheduleBroadcast(); // defer everything else
});

(c) Did you miss updates after a reconnect? After any reconnect, fetch a REST snapshot, then resume the stream. Otherwise the score stays wrong until the next change arrives. Connection and subscribe details are on the WebSocket API page.

(d) Are you flooding the client? Ten updates in one frame should paint once, not ten times:

js
const pending = new Map();
let raf = 0;

Step 6: Catch main-thread and render lag in the browser

Sometimes the data arrives instantly and the UI still feels slow. That's a client problem. The browser can tell you directly.

Find long tasks (anything blocking the main thread for 50 ms or more):

js
new PerformanceObserver((list) => {
for (const e of list.getEntries()) {
console.warn(long task: ${e.duration.toFixed(0)}ms, e);
}
}).observe({ entryTypes: ["longtask"] });

If a long task coincides with each score update, your render path is the problem. Common culprits: re-rendering a whole match list instead of one row, huge unvirtualized lists, synchronous JSON parsing of large payloads, and expensive CSS animations.

Use the Performance panel, not guesses. Record while a live update lands. The flame chart will show whether the time is spent in scripting, layout or paint.

Handle hidden tabs. This one fools a lot of people. Browsers throttle background tabs: timers get delayed, requestAnimationFrame stops firing entirely, and on some browsers the throttling becomes aggressive after a few minutes. A user who switches tabs and comes back sees stale data for a moment. Fix it by listening for visibility and resyncing:

js
document.addEventListener("visibilitychange", async () => {
if (document.visibilityState === "visible") {
const snapshot = await fetch("/api/live-snapshot").then((r) => r.json());
applySnapshot(snapshot); // jump straight to current truth
}
});

Step 7: Webhook pipelines and queue delay

Webhooks give you push-style delivery to your server, but they have their own lag sources, and none of them are visible from the provider's side.

Slow acknowledgements. If your endpoint does heavy work before replying 200, the provider may time out and retry, which creates duplicates and delay.
Queue buildup. If you push events onto a queue and your consumers fall behind during a busy match window (think a full Saturday of football fixtures), queue depth becomes latency. Monitor queue age, not just queue size.
Cold starts. A serverless function that sleeps between goals adds a startup penalty exactly when the goal arrives.
Retries. Out-of-order delivery after a retry can make an old score overwrite a new one.

Guard against the last one by comparing event time or a sequence value before applying an update:

js
function applyIfNewer(state, msg) {
const current = state.get(msg.match_id);
// 'seq' or an event timestamp: use whichever the payload actually provides
if (current && current.seq >= msg.seq) return; // stale, ignore
state.set(msg.match_id, msg);
}

Signature checks, retry behaviour and payload shapes are documented on the Webhooks API page. Always acknowledge first and process after.

The "not actually lag" cases

Before you spend a week optimizing, rule out these:

The broadcast is behind. TV and streaming broadcasts are often many seconds behind the real event, and different services are behind by different amounts. If a user compares your app to a live TV stream, a data feed that is ahead can look like it's "spoiling" rather than lagging, and a feed compared against a faster social post can look slow. Always compare against a consistent reference, ideally the same data source on a stopwatch.

Different definitions of "final". One site updates the score on the goal, another waits for VAR confirmation. Two correct systems can disagree for a minute.

Cache headers. A CDN or browser cache serving a 30-second-old response looks exactly like lag. Check the response headers:

If age is large or cache-control: max-age=30 is set on a live endpoint, you've found it. For live data, use no-store, or a very short s-maxage deliberately.

Region distance. A server in one continent serving users in another adds real round-trip time to every non-streamed request. Measure from where your users actually are.

A diagnostic decision tree

When someone reports lag, walk this tree top to bottom and stop at the first match:

text
Is the score wrong for a long time after a change (many seconds)?
├─ YES → Is there a cache header or CDN in front? → fix caching
│ Is there a poller (frontend or backend)? → check interval math (§4)
│ Did the socket go silent / reconnect? → watchdog + snapshot (§7)
│ Did a request return 429/5xx? → rate limits / status page
└─ NO → Does it update fast but "feel" janky?
├─ Long tasks in the browser? → optimize render (§8)
├─ Only after switching tabs? → visibilitychange resync (§8)
└─ Compared against TV/other site? → reference mismatch (§10)

When you suspect the provider rather than your own stack, check the Status page and the changelog first, so you can separate "an incident is ongoing" from "my code regressed".

Build a staleness monitor

The best defense is catching lag before users do. A staleness monitor tracks "how old is the freshest data for each live match" and alerts when it exceeds a threshold:

js
// monitor.js
const lastUpdate = new Map(); // match_id -> ms timestamp of last data
const LIVE = new Set(); // match_ids currently in play

export function onData(matchId) {
lastUpdate.set(matchId, Date.now());
}

setInterval(() => {
const now = Date.now();
for (const id of LIVE) {
const age = now - (lastUpdate.get(id) ?? 0);
if (age > 20_000) {
alert(match ${id}: no update for ${Math.round(age / 1000)}s);
}
}
}, 5_000);

function alert(msg) {
console.error("[STALENESS]", msg);
// send to Slack / PagerDuty / your logger here
}

Pair it with the per-segment metrics from section 5 and a simple dashboard with three lines per segment (p50, p95, p99). Within a week you'll know your real latency profile instead of arguing about feelings.

Final checklist and next steps Reproduce the complaint with a specific match, event and device curl -w breakdown: DNS, TCP, TLS, TTFB, total Reuse connections (keep-alive) Do the interval math, and check for chained pollers Stamp every hop: provider, ingest, emit, receive, paint Correct clock offset on client and sync servers with NTP Add a "socket silent" watchdog and a REST snapshot after reconnect Coalesce updates with requestAnimationFrame Observe long tasks; resync on visibilitychange Verify cache headers on every live endpoint Alert on staleness, not only on errors Log non-200 responses, especially 429

If you want a clean environment to practice on:

Create a free key on the signup page.
Fire your first request from the Quickstart, then browse the documentation for the full resource list.
Test routes in the Sandbox before wiring them into code.
Skipping custom UI altogether? The embeddable widgets handle rendering for you.
Compare plans and request limits on the pricing page.

Coverage spans 13 sports, so the same debugging approach applies whether you're tracking football or cricket.

What was the weirdest source of "lag" you've ever tracked down? A cached CDN response, a throttled tab, a chained poller? Share it in the comments. I'm collecting war stories.

Building a Sub-100ms Live Odds Ticker: REST vs WebSocket vs Webhooks Compared

orbistats — Tue, 06 Oct 2026 16:04:27 +0000

If you've ever built a live odds screen, you know the feeling. The price on your page says 1.91, the bookmaker's site says 1.85, and a user is already screenshotting it for your support inbox.

Live odds are one of the least forgiving data types you can display. A goal, a red card or a break of serve can move a line within a second. Whether your ticker feels instant or broken depends less on your UI framework and more on how the data reaches your app.

In this guide we'll build a live odds ticker three ways (REST polling, WebSocket and Webhooks) and compare them honestly: latency, cost, complexity and failure modes. Along the way we'll write a reconnect-safe client you can reuse in production.

For the examples I'll use the Orbistats Odds API because it exposes all three delivery methods behind one normalized schema. The patterns apply to any provider, though.

Heads-up: All numbers in the latency tables below are a budget framework, not benchmark results. Run the measurement script in section 6 against your own region and plan before you quote any figure.

Table of contents
What "sub-100ms" actually means
The normalized odds schema we'll consume
Approach 1: REST polling
Approach 2: WebSocket streaming
Approach 3: Webhooks
Measuring your real latency
Head-to-head comparison
The architecture I'd ship
Production checklist
Final thoughts and next steps

What "sub-100ms" actually means

"Sub-100ms" is a vague claim until you say from where to where. A live odds update passes through several hops:

text
Bookmaker price change
↓
Provider ingestion + normalization
↓
Provider delivery (REST / WS / Webhook)
↓
Network travel to YOUR server or browser
↓
Your parsing + business logic
↓
Render on screen

Providers usually quote latency for the second and third hops only. Orbistats, for example, positions its live feed as sub-50ms and has published a piece on what sub-50ms actually requires, end to end. That figure covers their side. Your network distance, TLS handshakes, JSON parsing and rendering come on top.

So when we say sub-100ms, we mean a budget like this:

Stage Example budget
Provider → your edge ~50 ms (provider claim)
Network RTT to your region 10–40 ms
Parse + diff + state update 1–5 ms
Render 8–16 ms (one frame)

The point: delivery method decides whether you even can hit that budget, because polling adds an entirely separate cost called staleness.

The normalized odds schema we'll consume

One of the hardest parts of any odds integration is that every bookmaker formats prices differently. A normalized API removes the need to maintain one parser per bookmaker. Orbistats returns markets in a consistent shape, like this 1X2 example:

json
{
"market": "1X2",
"odds": {
"home": 1.91,
"draw": 3.40,
"away": 4.20
}
}

The same schema family covers moneyline, spreads, handicaps, totals, player props and futures, for both pre-match and live odds, plus line movement. Auth is a standard bearer token against https://api.orbistats.com/v1/:

http
Authorization: Bearer YOUR_API_KEY

You can get a key in a minute from the signup page, and the documentation lists the full resource set (fixtures, results, standings, odds, statistics, lineups, events, teams, players, competitions, countries).

Here is the tiny type we'll use everywhere below:

ts
// types.ts
export interface OddsTick {
matchId: string;
market: string; // e.g. "1X2"
odds: Record;
receivedAt: number; // ms, set by OUR code
}

Approach 1: REST polling

Polling is where everyone starts, and for good reason: it's simple, cacheable and works everywhere.

js
// poll.js (Node 20+, no dependencies)
const BASE = "https://api.orbistats.com/v1";
const KEY = process.env.ORBISTATS_KEY;

let last = new Map();

async function pollOnce(matchId) {
const t0 = performance.now();
// Check the API reference for the exact odds route and params.
const res = await fetch(${BASE}/football/odds?match_id=${matchId}, {
headers: { Authorization: Bearer ${KEY} },
});
if (!res.ok) throw new Error(HTTP ${res.status});
const body = await res.json();
const rtt = performance.now() - t0;

const prev = last.get(matchId);
if (JSON.stringify(prev) !== JSON.stringify(body)) {
last.set(matchId, body);
console.log(CHANGED (rtt ${rtt.toFixed(0)}ms), body);
}
}

setInterval(() => pollOnce("match_50231").catch(console.error), 1000);

Use the API reference for exact route names. The shape above is what matters.

The hidden cost: staleness

Polling latency isn't just request time. If you poll every T milliseconds, a price change lands at a random moment inside the interval:

Average added delay: T / 2
Worst case: T
Poll interval Avg staleness Worst case Requests/day (1 match, 24h)
5 s 2.5 s 5 s 17,280
1 s 500 ms 1 s 86,400
250 ms 125 ms 250 ms 345,600

Two things jump out. You cannot reach sub-100ms by polling without hammering the API at 10+ requests per second per match. And request volume explodes. On a free tier capped at 150 requests per day (check the pricing page for current limits), a 1-second poll burns your whole allowance in about two and a half minutes.

Use REST for: fixtures, standings, historical backfills, pre-match odds and anything where seconds don't matter. For live scores specifically, see the Live Scores API.

Approach 2: WebSocket streaming

A WebSocket keeps one persistent connection open and the server pushes every change. No request overhead, no polling interval, no staleness. This is the path to sub-100ms.

text
REST: Client → Request → Server → Response (repeat forever)
WebSocket: Client ⇄ one persistent connection ⇄ stream of updates

Here's a production-shaped client with heartbeats and reconnection:

js
// ws-client.js
import WebSocket from "ws";

const WS_URL = process.env.ORBISTATS_WS_URL; // copy from the WebSocket docs
const KEY = process.env.ORBISTATS_KEY;

let attempt = 0;
const state = new Map(); // matchId:market -> latest odds

function connect() {
const ws = new WebSocket(WS_URL, {
headers: { Authorization: Bearer ${KEY} },
});

let heartbeat;

ws.on("open", () => {
attempt = 0;
console.log("connected");
// Subscribe message shape: confirm in the WebSocket API docs.
ws.send(JSON.stringify({ action: "subscribe", channel: "odds", sport: "football" }));
heartbeat = setInterval(() => ws.ping(), 20_000);
});

ws.on("message", (raw) => {
const receivedAt = Date.now();
const msg = JSON.parse(raw);
const key = ${msg.match_id}:${msg.market};
state.set(key, { ...msg, receivedAt });
render(key, state.get(key));
});

ws.on("close", () => {
clearInterval(heartbeat);
// Exponential backoff with jitter: 0.5s, 1s, 2s ... capped at 15s
const delay = Math.min(15_000, 500 * 2 ** attempt++) * (0.5 + Math.random() / 2);
console.log(closed, retrying in ${Math.round(delay)}ms);
setTimeout(connect, delay);
});

ws.on("error", (e) => console.error("ws error", e.message));
}

function render(key, tick) {
console.log(key, tick.odds);
}

connect();

The exact endpoint and subscription format live on the WebSocket API page, so treat WS_URL and the subscribe payload above as placeholders.

The gap problem (most tutorials skip this)

When a socket drops, you miss updates. Reconnecting alone leaves your ticker silently wrong. The fix is a simple pattern:

text

Socket reconnects
Immediately fetch a REST snapshot of current state
Replace local state with the snapshot
Resume applying streamed updates js async function healGap(matchId) { const res = await fetch(https://api.orbistats.com/v1/football/odds?match_id=${matchId}, { headers: { Authorization: Bearer ${process.env.ORBISTATS_KEY} }, }); const snapshot = await res.json(); state.set(matchId, snapshot); }

REST for the truth, WebSocket for the delta. This hybrid is the backbone of nearly every serious live-data system.

Approach 3: Webhooks

Webhooks flip the direction: the provider calls you when something happens.

text
Goal scored → Provider detects event → POST to your URL → Your server reacts

They're ideal for reactions, such as sending a push notification, settling a bet, or updating a database row, rather than for painting a pixel-perfect ticker.

js
// webhook-server.js
import express from "express";
import crypto from "node:crypto";

const app = express();

// Keep the raw body: signature checks must run on the exact bytes received.
app.use("/webhook/sports", express.raw({ type: "application/json" }));

const seen = new Set(); // swap for Redis SET with TTL in production

app.post("/webhook/sports", (req, res) => {
// Header name and algorithm: confirm in the Webhooks docs.
const signature = req.header("x-signature") ?? "";
const expected = crypto
.createHmac("sha256", process.env.WEBHOOK_SECRET)
.update(req.body)
.digest("hex");

const ok =
signature.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
if (!ok) return res.sendStatus(401);

const event = JSON.parse(req.body);

// Idempotency: providers may retry, so never process the same event twice.
if (seen.has(event.id)) return res.sendStatus(200);
seen.add(event.id);

res.sendStatus(200); // ACK fast...
queueMicrotask(() => handle(event)); // ...do the heavy work after
});

function handle(event) {
console.log("event:", event.type, event);
}

app.listen(3000);

Details of payloads, retries and signing are on the Webhooks API page. Webhooks are listed alongside historical data and widgets in the Growth plan positioning, so check the pricing page for what each tier includes.

The three webhook rules:

Verify the signature. Anyone can POST to a public URL.
Be idempotent. Retries mean duplicates.
Acknowledge fast. Return 200 immediately and process asynchronously, or the provider will time out and retry.

Measuring your real latency

Don't trust anyone's numbers, including mine. Measure. Here's a script that records the delay between the moment an update is received and its provider timestamp (if one is included), plus a raw RTT probe:

js
// measure.js
import { performance } from "node:perf_hooks";

const KEY = process.env.ORBISTATS_KEY;

async function rttProbe(n = 50) {
const samples = [];
for (let i = 0; i < n; i++) {
const t0 = performance.now();
await fetch("https://api.orbistats.com/v1/", {
headers: { Authorization: Bearer ${KEY} },
});
samples.push(performance.now() - t0);
await new Promise((r) => setTimeout(r, 200));
}
samples.sort((a, b) => a - b);
const p = (q) => samples[Math.floor(q * (samples.length - 1))].toFixed(1);
console.log({ p50: p(0.5), p95: p(0.95), p99: p(0.99), min: p(0), max: p(1) });
}

rttProbe();

For streamed updates, compute Date.now() - msg.timestamp only if your server clock is NTP-synced; otherwise clock skew will fool you. Always report p50, p95 and p99, because averages hide the tail, and the tail is what users notice.

The Status page is also worth bookmarking so you can separate "my code is slow" from "an incident is ongoing".

Head-to-head comparison REST polling WebSocket Webhooks Direction You pull Provider pushes over open socket Provider pushes to your URL Typical added delay T/2 avg (interval-bound) Near zero (network only) Near zero (network + your server) Sub-100ms feasible ❌ not without extreme polling ✅ yes ⚠️ to your server yes, to browsers needs fan-out Request cost High, grows with matches One connection One POST per event Browser-direct ✅ ✅ (but exposes your key) ❌ needs a public server Failure mode Stale data Silent gaps on drop Duplicates and retries Complexity Low Medium Medium Best for Fixtures, standings, history Live odds, line movement Alerts, settlement, DB sync
The architecture I'd ship

Never put your provider key in the browser, and don't open one upstream socket per user. Open one upstream connection and fan out:

text
Orbistats WebSocket ──► Your ingest service
│
(normalize + diff + dedupe)
│
Redis pub/sub
┌─────────┴─────────┐
▼ ▼
WebSocket/SSE gateway Webhook-style jobs
│ (alerts, DB writes)
▼
Browser tickers

Key decisions:

Diff before broadcast. Only push a tick if the price actually changed. This cuts browser traffic dramatically on quiet markets.
Coalesce on the client. If 10 updates arrive in one animation frame, render only the last one with requestAnimationFrame.
Snapshot on connect. New browser tabs should receive current state immediately, then deltas.
Flash direction, not just value. Green up and red down arrows are what make a ticker feel alive.

A minimal browser-side coalescer:

js
const latest = new Map();
let scheduled = false;

socket.onmessage = (e) => {
const tick = JSON.parse(e.data);
latest.set(${tick.match_id}:${tick.market}, tick);
if (!scheduled) {
scheduled = true;
requestAnimationFrame(() => {
scheduled = false;
for (const tick of latest.values()) paint(tick);
latest.clear();
});
}
};

Production checklist Heartbeats (ping/pong) and dead-connection detection Exponential backoff with jitter on reconnect REST snapshot after every reconnect (gap healing) Webhook signature verification and idempotency keys Rate-limit awareness: back off on 429 instead of retrying instantly Odds-format toggle (decimal / fractional / American) done client-side Pin your API version (/v1/) so breaking changes never surprise you Watch the changelog for additive fields Alert on staleness ("no tick in N seconds for a live match"), not only on errors
Final thoughts and next steps

The short version:

Use REST for everything that isn't time-critical, and for healing gaps.
Use WebSocket for the live ticker itself. It's the only approach that gets you into sub-100ms territory.
Use Webhooks for side effects that must happen once per event.
Combine all three. They aren't competitors, they're roles.

If you want to try this today:

Grab a free key at orbistats.com/signup.
Fire your first request from the Sandbox or the Quickstart.
Browse copy-paste snippets in Examples, or grab an SDK.
Need history for backtesting your pricing models? See the Historical Sports Data API.
Don't want to build UI at all? The drop-in widgets embed a live score or odds board with a snippet.

Coverage spans 13 sports, including football, basketball, cricket and tennis. If you're building for trading teams specifically, the Sportsbooks & Trading page covers the use case in more depth.

What's your current live-odds stack: polling, sockets, or a hybrid? Drop it in the comments. I'd love to compare p95 numbers.

Why I Replaced Polling with Orbistats' WebSocket API (With Before/After Latency Numbers)

orbistats — Tue, 06 Oct 2026 15:51:31 +0000

Polling is the first thing everyone builds and the last thing anyone is proud of. Here's the migration, the code, and a way to measure your own before/after instead of trusting mine.

Every live scoreboard starts the same way. You write a setInterval, hit an endpoint every few seconds, diff the response, and update the screen. It works on day one. It keeps working right up until someone watches a goal on TV and then waits several seconds for your app to catch up.

I moved a live-score feature from polling to the Orbistats WebSocket API, and this post walks through exactly how: the maths of why polling feels slow, a script that measures both approaches side by side, the production-grade WebSocket client, the fan-out server for your own users, and the traps I'd avoid next time.

One promise up front: I'm not going to hand you a universal "X times faster" claim. Your number depends on your interval, your region and your sport. What I will give you is the harness to get your own, plus a results table at the end to fill in.

TL;DR
Polling adds a built-in delay of up to one full interval before you can even see a new event.
A push connection removes that delay. What's left is network time plus your own processing.
Don't open one upstream socket per user. Keep one connection to the provider and fan out to your clients.
The unglamorous parts (reconnects, gap-fill, dedupe, heartbeats) are most of the work.
Keep REST for everything that isn't second-by-second.
First, the maths of why polling feels slow

Say you poll every T seconds. A new event (a goal) happens at a random moment between two polls. How long until you notice?

Best case: almost zero, you polled right after it happened.
Worst case: almost T, you polled right before it happened.
On average: T / 2.

For T = 5 s, that gives:

Percentile Added delay from polling alone
Average ~2.5 s
p95 ~4.75 s
p99 ~4.95 s

That's before request time, your backend, caching and rendering. And you can't buy your way out of it with a faster API, because the delay lives in your own timer.

"Fine," you say, "I'll poll every second." Look at what that costs:

Poll interval Requests per day (one endpoint) Across 13 sports
10 s 8,640 112,320
5 s 17,280 224,640
1 s 86,400 1,123,200

Most of those requests return "nothing changed." You're paying (in quota, bandwidth and server load) to be told nothing. If you're on a free tier with a daily request cap, polling at 5 seconds can burn through it in minutes. Check the pricing page for the current limits and do that arithmetic before you pick an interval.

Orbistats now covers 13 sports, which is exactly why this matters. The moment you add a second or third sport, polling cost multiplies, while a WebSocket subscription just carries more messages over the same connection.

Why WebSocket fixes it

A WebSocket is one long-lived connection. The provider pushes an update the moment it exists. There's no "when do I ask next" gap at all.

Polling: you ──ask──▶ server ──"nothing"──▶ you ──ask──▶ server ──"goal!"──▶ you
(wasted) (found late)

WebSocket: you ◀──────────── goal! (pushed the instant it exists) ──────────── server

The trade is that you now own a connection: reconnects, heartbeats, ordering, and duplicates. That's the real work, and most tutorials skip it. We won't.

The plan
Orbistats WebSocket ──(1 connection)──▶ your server ──(fan-out)──▶ browsers / apps
▲ │
└──── REST snapshot on reconnect ◀──────┘
Measure polling vs WebSocket side by side (so the numbers are yours).
Build a resilient upstream client.
Build a fan-out server so many users share one upstream connection.
Handle the gap after a disconnect.
Re-measure.
Setup

Node 20+ (for global fetch):

bash
mkdir polling-to-ws && cd polling-to-ws
npm init -y
npm i ws

In package.json, add "type": "module".

You'll need an API key. If you don't have one, create a free account. Then:

bash
export ORBISTATS_API_KEY="your_key"
export REST_BASE="https://api.orbistats.com/v1"
export REST_PATH="/football/matches/live"
export WS_URL="wss://REPLACE_WITH_URL_FROM_DOCS"
export WS_SUBSCRIBE='{"REPLACE":"WITH_SUBSCRIBE_MESSAGE_FROM_DOCS"}'

The WebSocket URL, subscribe message and payload shape come from the documentation and the API reference. I've kept those as placeholders on purpose. Don't copy my field names, copy yours from the docs. If it's your first call, the quickstart gets you to a working request fastest, and the sandbox is a good place to look at real payload shapes without spending your quota.

Step 1: the side-by-side harness (this is where your numbers come from)

The trick for a trustworthy comparison: run polling and WebSocket in the same process, on the same machine, at the same time. Record the moment each channel first sees each event. Because both timestamps come from the same clock, there's no clock-sync problem, and the difference tells you exactly how much later polling noticed.

js
// ab_compare.js
import WebSocket from "ws";

const KEY = process.env.ORBISTATS_API_KEY;
const REST_URL = ${process.env.REST_BASE ?? "https://api.orbistats.com/v1"}${process.env.REST_PATH ?? "/football/matches/live"};
const WS_URL = process.env.WS_URL;
const WS_SUBSCRIBE = process.env.WS_SUBSCRIBE;
const POLL_MS = Number(process.env.POLL_MS ?? 5000);

const seen = new Map(); // fingerprint -> { poll?: ms, ws?: ms }

// ADAPT THESE TWO to the real payload shapes in the docs.
// Goal: produce the SAME fingerprint string from a REST match and a WS message
// when they describe the same score change.
const fingerprint = (m) => ${m.match_id}:${m.home?.score}-${m.away?.score};
const extractMatches = (body) => (Array.isArray(body) ? body : body.data ?? []);
const extractMatchFromWs = (msg) => msg.data ?? msg; // adjust to your WS schema

// --- polling side ---
async function pollOnce() {
const res = await fetch(REST_URL, { headers: { Authorization: Bearer ${KEY} } });
if (res.status === 429) {
console.error("Rate limited (429). Increase POLL_MS or stop.");
process.exit(1);
}
if (!res.ok) return;
for (const m of extractMatches(await res.json())) mark(fingerprint(m), "poll");
}
setInterval(() => pollOnce().catch(console.error), POLL_MS);
pollOnce().catch(console.error);

// --- websocket side ---
const ws = new WebSocket(WS_URL, { headers: { Authorization: Bearer ${KEY} } });
ws.on("open", () => WS_SUBSCRIBE && ws.send(WS_SUBSCRIBE));
ws.on("message", (raw) => {
try {
const m = extractMatchFromWs(JSON.parse(raw));
if (m?.match_id) mark(fingerprint(m), "ws");
} catch {}
});

// --- report on Ctrl+C ---
function pct(arr, p) {
if (!arr.length) return NaN;
const s = [...arr].sort((a, b) => a - b);
const k = (s.length - 1) * (p / 100);
const lo = Math.floor(k), hi = Math.min(lo + 1, s.length - 1);
return s[lo] + (s[hi] - s[lo]) * (k - lo);
}

process.on("SIGINT", () => {
// positive = polling noticed AFTER the websocket did
const gaps = [];
for (const { poll, ws } of seen.values()) {
if (poll !== undefined && ws !== undefined) gaps.push(poll - ws);
}
console.log(\nevents seen by both channels: ${gaps.length});
if (gaps.length) {
console.log(polling was later by (ms):);
console.log(p50 ${pct(gaps, 50).toFixed(0)} | p95 ${pct(gaps, 95).toFixed(0)} | p99 ${pct(gaps, 99).toFixed(0)});
}
process.exit(0);
});

Run it during a busy period (several live matches) and let it collect for a while:

bash
POLL_MS=5000 node ab_compare.js

...wait for a good number of score changes, then Ctrl+C

Three honest notes on this harness:

It measures the relative gap, not absolute end-to-end latency. For the absolute provider-to-you number, you'd compare against the provider's emitted timestamp (needs clock sync).
Fingerprint matching is the fragile part. If REST and WebSocket describe the same event differently, your fingerprints won't line up and you'll see zero matches. Fix the two adapter functions first.
Collect enough events. A handful of goals isn't a distribution. Aim for dozens, ideally across a busy evening. Cricket's ball-by-ball cadence in particular gives you lots of events quickly, so a cricket run fills the sample far faster than a low-scoring football night.
Step 2: a WebSocket client you'd actually run in production

The five-line new WebSocket(url) is fine for a demo. In production you need: reconnect with backoff, a heartbeat to catch "zombie" connections, re-subscribe after reconnect, and dedupe (reconnects and retries can replay events).

js
// orbistats-stream.js
import WebSocket from "ws";
import { EventEmitter } from "node:events";

export class OrbistatsStream extends EventEmitter {
constructor({ url, apiKey, subscribeMessage, heartbeatMs = 30_000, dedupeSize = 5000 }) {
super();
this.url = url;
this.apiKey = apiKey;
this.subscribeMessage = subscribeMessage;
this.heartbeatMs = heartbeatMs;
this.dedupeSize = dedupeSize;
this.attempt = 0;
this.everConnected = false;
this.seenIds = new Set();
this.closedByUs = false;
}

start() {
this.closedByUs = false;
this.#connect();
}

stop() {
this.closedByUs = true;
clearInterval(this.hb);
this.ws?.close();
}

#connect() {
this.ws = new WebSocket(this.url, {
headers: { Authorization: Bearer ${this.apiKey} },
});

this.ws.on("open", () => {
  const reconnected = this.everConnected;
  this.everConnected = true;
  this.attempt = 0;
  this.alive = true;
  if (this.subscribeMessage) this.ws.send(this.subscribeMessage); // re-subscribe every time
  this.#startHeartbeat();
  this.emit("open", { reconnected });
  // If we reconnected, we may have missed events. The consumer should re-sync via REST.
  if (reconnected) this.emit("reconnected");
});

this.ws.on("pong", () => { this.alive = true; });

this.ws.on("message", (raw) => {
  let msg;
  try { msg = JSON.parse(raw); } catch { return; }

  // Dedupe: use whatever unique id the docs define. event_id is a placeholder.
  const id = msg.event_id;
  if (id !== undefined) {
    if (this.seenIds.has(id)) return;
    this.seenIds.add(id);
    if (this.seenIds.size > this.dedupeSize) {
      this.seenIds.delete(this.seenIds.values().next().value); // drop the oldest
    }
  }
  this.emit("event", msg);
});

this.ws.on("error", (err) => this.emit("warn", err));

this.ws.on("close", () => {
  clearInterval(this.hb);
  this.emit("closed");
  if (!this.closedByUs) this.#scheduleReconnect();
});

}

#startHeartbeat() {
clearInterval(this.hb);
this.hb = setInterval(() => {
if (!this.alive) {
this.ws.terminate(); // no pong since last ping: connection is dead, trigger reconnect
return;
}
this.alive = false;
this.ws.ping();
}, this.heartbeatMs);
}

#scheduleReconnect() {
this.attempt += 1;
// exponential backoff, capped, with jitter so thousands of clients don't reconnect in sync
const base = Math.min(1000 * 2 ** this.attempt, 30_000);
const delay = base / 2 + Math.random() * (base / 2);
setTimeout(() => this.#connect(), delay);
}
}

What each piece is protecting you from:

Heartbeat + terminate(): a connection can die silently (a NAT timeout, a mobile network switch) without a close event. Without a ping/pong check, you sit there "connected" and receive nothing.
Jittered backoff: if your provider restarts and every client reconnects in the same second, you've built a self-inflicted traffic spike.
Re-subscribe on every open: subscriptions don't survive a reconnect unless the docs say they do.
Dedupe: after a reconnect or a retry, the same event can arrive twice. Showing "GOAL!" twice is a bug users will screenshot.
Step 3: close the gap with a REST snapshot

Here's the part people forget. If your socket drops for 20 seconds, you missed 20 seconds of events. A WebSocket doesn't replay them for you. The fix is the combination everyone eventually lands on: WebSocket for the live deltas, REST for the full state.

js
// state.js
const REST_URL = ${process.env.REST_BASE ?? "https://api.orbistats.com/v1"}${process.env.REST_PATH ?? "/football/matches/live"};

export const liveState = new Map(); // match_id -> latest match object

export async function loadSnapshot() {
const res = await fetch(REST_URL, {
headers: { Authorization: Bearer ${process.env.ORBISTATS_API_KEY} },
});
if (!res.ok) throw new Error(snapshot failed: ${res.status});
const body = await res.json();
const matches = Array.isArray(body) ? body : body.data ?? [];
liveState.clear();
for (const m of matches) liveState.set(m.match_id, m);
return matches;
}

REST stays the right tool for this: schedules, standings and full match state are what the Sports Data API and the Live Scores API are for. The socket just keeps that picture current between snapshots.

Step 4: fan out to your own users (one upstream, many downstream)

The most expensive mistake in this migration: letting every browser open its own connection to the provider. That multiplies your connection count, leaks your API key to the client, and gets you rate-limited. Instead, your server holds one upstream connection and broadcasts.

js
// server.js
import { WebSocketServer } from "ws";
import { OrbistatsStream } from "./orbistats-stream.js";
import { liveState, loadSnapshot } from "./state.js";

const stream = new OrbistatsStream({
url: process.env.WS_URL,
apiKey: process.env.ORBISTATS_API_KEY,
subscribeMessage: process.env.WS_SUBSCRIBE,
});

const wss = new WebSocketServer({ port: 8080 });

function broadcast(payload) {
const data = JSON.stringify(payload);
for (const client of wss.clients) {
if (client.readyState !== 1) continue;
// Back-pressure guard: skip clients that can't keep up instead of buffering forever.
if (client.bufferedAmount > 1_000_000) continue;
client.send(data);
}
}

// New browser connects: send the current state first, then deltas follow.
wss.on("connection", (client) => {
client.send(JSON.stringify({ type: "snapshot", matches: [...liveState.values()] }));
});

stream.on("event", (msg) => {
const m = msg.data ?? msg; // adapt to the real schema
if (m?.match_id) liveState.set(m.match_id, m);
broadcast({ type: "update", match: m });
});

stream.on("reconnected", async () => {
try {
const matches = await loadSnapshot(); // fill the gap we missed while disconnected
broadcast({ type: "snapshot", matches });
} catch (e) {
console.error("gap-fill failed", e);
}
});

stream.on("warn", (e) => console.warn("upstream warning:", e.message));

await loadSnapshot();
stream.start();
console.log("fan-out server on ws://localhost:8080");

And a deliberately tiny browser client:

js
// client.js (browser)
let socket;
let retry = 0;
const state = new Map();

The snapshot-then-deltas pattern means a brand-new visitor, or a returning one after a drop, always starts from a correct picture. No flicker, no "blank scoreboard until the next goal."

Step 5: re-measure and fill in your numbers

Run ab_compare.js again with your final settings (and any polling interval you want to compare against), then drop your own results here:

Polling (5 s)   WebSocket

Added delay, p50 ~2.5 s (theory) / [FILL: measured] [FILL: measured]
Added delay, p95 ~4.75 s (theory) / [FILL: measured] [FILL: measured]
Added delay, p99 ~4.95 s (theory) / [FILL: measured] [FILL: measured]
Requests/day, one endpoint 17,280 0 repeated requests
Upstream connections n/a 1
Wasted "nothing changed" calls most of them none

Read it the way you'd read any benchmark: look at p95 and p99, not the average, run it on a busy night as well as a quiet one, and be suspicious of any single run.

Things that bit me (so they don't bite you)

Clock skew produces negative numbers. If you ever compare against a provider timestamp and get negative latencies, your system clock is off. Fix NTP, don't take absolute values.

Don't merge slow and fast data in one payload. If you wait for odds and scores before showing either, you inherit the slower one's delay. Show scores the moment they arrive. The Odds API is a separate stream with a different update rhythm for exactly this reason.

Quiet isn't broken. A live match can go minutes with no events. Your heartbeat should be at the protocol level (ping/pong), not "I haven't received data for 30 seconds, so reconnect." Otherwise you'll churn connections during a goalless half.

Sports differ. A basketball game produces a steady flood of score updates, so fan-out and back-pressure matter more. Football is sparse and bursty. Test per sport instead of assuming one profile fits all 13.

Cache TTLs between socket and screen. The fastest push connection in the world doesn't help if a CDN or a cache layer serves a "fresh" value that's 10 seconds old.

Log your reconnect rate. A stream that's fast but drops every few minutes isn't fast. Alert on reconnects per hour.

When you should NOT replace polling

Polling isn't evil. It's the right call when:

the data changes slowly (standings, fixtures, historical results)
you only need a refresh every minute or so
you're serving a server-rendered page that's cached anyway
you want the simplest possible thing for a small side project

And if what you really need is "my backend should react when X happens" rather than "my UI should update instantly," look at webhooks. They push to a URL you own, with no open connection to manage. A common healthy setup is WebSocket for the live UI, webhooks for backend actions, and REST for everything else.

Migration checklist
Measure first: run the A/B harness against your current polling setup
Get the WebSocket URL, subscribe message and schema from the docs
Build the upstream client with heartbeat, backoff, re-subscribe and dedupe
Keep a REST snapshot for first load and for gap-fill after reconnects
Put one upstream connection behind a fan-out server
Never expose your API key to the browser
Add back-pressure handling for slow clients
Alert on reconnect rate and message gaps
Keep polling as a fallback for the rare case the socket is down for long
Re-measure and fill in your own before/after table
Wrapping up

Replacing polling with a WebSocket isn't hard in theory and it's fiddly in practice. The win is real and easy to explain: you stop waiting for your own timer. But the part that makes it production-worthy is everything around the happy path: reconnects, gap-fill, dedupe and fan-out.

If you want to try it, start at the Orbistats homepage to see the current sport coverage, and use the free key and sandbox to run the harness above with your own data. Then post your before/after numbers in the comments. I'd genuinely like to see how they compare across different sports.

Measuring Real API Latency: A Benchmark Script for REST, WebSocket and Webhooks

orbistats — Tue, 06 Oct 2026 15:47:50 +0000

"Our API is fast" is a feeling. A p99 in a JSON file is a fact. Let's build the thing that gives you the fact.

Every sports data API says it's fast. Orbistats lists a sub-50ms live feed on its homepage, and plenty of other providers make similar claims. The trouble is that a latency number depends on what you measure and how, and a vendor's number is almost never the number your users experience.

So instead of trusting anyone's page, we're going to build a small benchmark toolkit that measures three different delivery methods the same way:

REST: you ask, the server answers
WebSocket: the server pushes over a persistent connection
Webhooks: the server calls your endpoint

By the end you'll have a repo you can run in about five minutes, plus a way to read the results without fooling yourself. It's written for sports data feeds, but the method works for any streaming or request-based API.

What we're actually measuring

Before any code, get the vocabulary straight, because mixing these up is the most common benchmarking mistake.

Request latency (REST): how long one request takes, from sending it to receiving the full response. You can measure this with a single clock on your machine, so there's no clock-sync problem.
Delivery latency (WebSocket, webhooks): how long after the provider published an event it reached you. This needs the provider's timestamp compared with your clock, so clock accuracy matters.
Staleness (REST polling): even a fast request can return old data. If your polling interval is 5 seconds, a new event waits on average 2.5 seconds before you even ask.

If you want the longer background on why a single "sub-50ms" figure doesn't tell the whole story, the piece on what sub-50ms actually requires end to end is a good companion read. Here we focus on building the measuring tape.

Project setup
latency-bench/
├── config.py
├── stats.py
├── rest_bench.py
├── ws_bench.py
├── webhook_bench.py
├── requirements.txt
└── results/

requirements.txt:

httpx>=0.27
websockets>=13
fastapi>=0.110
uvicorn>=0.29
python-dateutil>=2.9

Install it:

bash
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
mkdir results

You'll need an API key. If you don't have one, sign up for a free key. Then export your settings:

bash
export ORBISTATS_API_KEY="your_key_here"
export REST_BASE="https://api.orbistats.com/v1"
export REST_PATH="/football/matches/live"
export WS_URL="wss://REPLACE_WITH_URL_FROM_DOCS"
export EMITTED_FIELD="emitted_at"

Two of those are placeholders on purpose. The WebSocket URL and the name of the "published at" timestamp field come from the documentation and the API reference. Don't guess them. Check what your plan actually exposes, and set EMITTED_FIELD to whatever the docs call the provider-side timestamp.

Step 1: shared config and stats helpers

config.py just reads environment variables so nothing is hard-coded:

python

config.py

import os

API_KEY = os.environ.get("ORBISTATS_API_KEY", "")
REST_BASE = os.environ.get("REST_BASE", "https://api.orbistats.com/v1")
REST_PATH = os.environ.get("REST_PATH", "/football/matches/live")
WS_URL = os.environ.get("WS_URL", "")
WS_SUBSCRIBE = os.environ.get("WS_SUBSCRIBE", "") # optional JSON string
EMITTED_FIELD = os.environ.get("EMITTED_FIELD", "emitted_at")

AUTH_HEADERS = {"Authorization": f"Bearer {API_KEY}"}

stats.py does the part people usually get wrong: percentiles. Averages hide slow outliers, and slow outliers are the ones users remember.

python

stats.py

import json
import statistics
import time
from datetime import datetime, timezone
from pathlib import Path

from dateutil import parser as dtparser

def percentile(values, p):
"""Linear-interpolated percentile. p in [0, 100]."""
if not values:
return float("nan")
s = sorted(values)
k = (len(s) - 1) * (p / 100)
lo = int(k)
hi = min(lo + 1, len(s) - 1)
return s[lo] + (s[hi] - s[lo]) * (k - lo)

def summarize(name, values_ms):
return {
"name": name,
"n": len(values_ms),
"min_ms": round(min(values_ms), 2) if values_ms else None,
"p50_ms": round(percentile(values_ms, 50), 2),
"p95_ms": round(percentile(values_ms, 95), 2),
"p99_ms": round(percentile(values_ms, 99), 2),
"max_ms": round(max(values_ms), 2) if values_ms else None,
"mean_ms": round(statistics.fmean(values_ms), 2) if values_ms else None,
}

def print_summary(s):
print(f"\n== {s['name']} (n={s['n']}) ==")
for key in ("min_ms", "p50_ms", "p95_ms", "p99_ms", "max_ms", "mean_ms"):
print(f" {key:8s} {s[key]}")
if s["n"] < 100:
print(" note: fewer than 100 samples, treat p99 as a rough hint only")

def save(summary, raw_ms, outdir="results"):
Path(outdir).mkdir(exist_ok=True)
stamp = int(time.time())
path = Path(outdir) / f"{summary['name']}_{stamp}.json"
path.write_text(json.dumps({"summary": summary, "raw_ms": raw_ms}, indent=2))
print(f" saved -> {path}")

def parse_ts_ms(value):
"""Accept epoch seconds, epoch ms, or ISO-8601 strings. Return epoch ms."""
if value is None:
return None
if isinstance(value, (int, float)):
# Heuristic: values below 1e12 are seconds, otherwise milliseconds.
return value * 1000 if value < 1e12 else float(value)
try:
dt = dtparser.isoparse(str(value))
if dt.tzinfo is None:
dt = dt.replace(tzinfo=timezone.utc)
return dt.timestamp() * 1000
except (ValueError, TypeError):
return None

Notice parse_ts_ms accepts three timestamp formats. Providers differ, and a silent unit mix-up (seconds read as milliseconds) will give you absurd numbers that look plausible for about five minutes.

Step 2: benchmark REST

REST is the simplest, so start here. We time each request with time.perf_counter(), which is a monotonic clock built for measuring durations and isn't affected by system clock changes.

Two things matter for fairness. First, cold vs warm: the first request pays for DNS, TCP and TLS setup, later requests on the same connection don't. Real apps usually reuse connections, but your first page load doesn't, so measure both. Second, rate limits: free plans have a daily request cap (at the time of writing the free tier is listed at 150 requests a day, but check the pricing page for current limits), so keep your sample sizes small and don't run this in a loop all afternoon.

python

rest_bench.py

import argparse
import time

import httpx

from config import AUTH_HEADERS, REST_BASE, REST_PATH, API_KEY
from stats import summarize, print_summary, save

def timed_get(client, url):
start = time.perf_counter()
resp = client.get(url, headers=AUTH_HEADERS)
elapsed_ms = (time.perf_counter() - start) * 1000
return resp, elapsed_ms

def main():
ap = argparse.ArgumentParser()
ap.add_argument("--warm", type=int, default=30, help="warm requests (reused connection)")
ap.add_argument("--cold", type=int, default=5, help="cold requests (new connection each)")
ap.add_argument("--gap", type=float, default=1.0, help="seconds between requests")
args = ap.parse_args()

if not API_KEY:
    raise SystemExit("Set ORBISTATS_API_KEY first.")

url = f"{REST_BASE}{REST_PATH}"
cold, warm, errors = [], [], 0

# Cold: brand new client (new TCP + TLS handshake) every time.
for _ in range(args.cold):
    with httpx.Client(timeout=10) as c:
        resp, ms = timed_get(c, url)
    if resp.status_code == 200:
        cold.append(ms)
    else:
        errors += 1
        if resp.status_code == 429:
            raise SystemExit("Rate limited (429). Stop and check your plan limits.")
    time.sleep(args.gap)

# Warm: one client, connection reused.
with httpx.Client(timeout=10) as c:
    timed_get(c, url)  # throwaway request to open the connection
    for _ in range(args.warm):
        resp, ms = timed_get(c, url)
        if resp.status_code == 200:
            warm.append(ms)
        else:
            errors += 1
            if resp.status_code == 429:
                raise SystemExit("Rate limited (429). Stop and check your plan limits.")
        time.sleep(args.gap)

for name, data in (("rest_cold", cold), ("rest_warm", warm)):
    if data:
        s = summarize(name, data)
        print_summary(s)
        save(s, data)
print(f"\nnon-200 responses: {errors}")

if name == "main":
main()

Run it:

bash
python rest_bench.py --warm 30 --cold 5

What to look for: cold should be noticeably slower than warm. If it isn't, your location is very close to the server or something is caching connections for you. If warm is slow and very jittery, the problem is probably your network, not the API.

One more REST caveat: this measures request latency, not freshness. If your product shows live scores via polling, the number that matters is how long an event sits before your next poll picks it up. That's interval / 2 on average and interval at worst. Fast requests won't fix a slow polling loop. REST is the right tool for the non-live side of things, like the fixtures, results and standings that the Sports Data API serves, and a poor fit for second-by-second scoreboards.

Step 3: benchmark WebSocket

WebSocket is where things get interesting, because now we're measuring delivery latency: the gap between the provider publishing an event and your process receiving it. That means comparing the provider's timestamp with your own clock.

This script records four things:

Connect time, meaning how long the handshake takes
Delivery latency for each message, as received - emitted
Inter-arrival gaps, which reveal bursts and stalls
Reconnects, because a fast stream that drops every ten minutes isn't fast
python

ws_bench.py

import argparse
import asyncio
import json
import time

import websockets

from config import AUTH_HEADERS, WS_URL, WS_SUBSCRIBE, EMITTED_FIELD
from stats import summarize, print_summary, save, parse_ts_ms

async def run(target_samples, max_seconds):
deltas, gaps = [], []
connect_ms_list = []
reconnects = 0
skipped = 0
last_arrival = None
deadline = time.monotonic() + max_seconds

while len(deltas) < target_samples and time.monotonic() < deadline:
    try:
        t0 = time.perf_counter()
        # websockets>=14 uses additional_headers; older versions use extra_headers.
        async with websockets.connect(
            WS_URL, additional_headers=AUTH_HEADERS, ping_interval=20
        ) as ws:
            connect_ms_list.append((time.perf_counter() - t0) * 1000)

            if WS_SUBSCRIBE:
                await ws.send(WS_SUBSCRIBE)  # subscription message from the docs

            while len(deltas) < target_samples and time.monotonic() < deadline:
                remaining = max(0.1, deadline - time.monotonic())
                raw = await asyncio.wait_for(ws.recv(), timeout=remaining)
                received_ms = time.time() * 1000
                now = time.perf_counter()

                if last_arrival is not None:
                    gaps.append((now - last_arrival) * 1000)
                last_arrival = now

                try:
                    msg = json.loads(raw)
                except json.JSONDecodeError:
                    skipped += 1
                    continue

                emitted_ms = parse_ts_ms(msg.get(EMITTED_FIELD))
                if emitted_ms is None:
                    skipped += 1
                    continue

                deltas.append(received_ms - emitted_ms)

    except (websockets.ConnectionClosed, OSError):
        reconnects += 1
        await asyncio.sleep(min(2 ** reconnects, 15))  # simple backoff
    except asyncio.TimeoutError:
        break

return deltas, gaps, connect_ms_list, reconnects, skipped

def main():
ap = argparse.ArgumentParser()
ap.add_argument("--samples", type=int, default=300)
ap.add_argument("--max-seconds", type=int, default=600)
args = ap.parse_args()

if not WS_URL:
    raise SystemExit("Set WS_URL (from the docs) first.")

deltas, gaps, connects, reconnects, skipped = asyncio.run(
    run(args.samples, args.max_seconds)
)

if deltas:
    s = summarize("ws_delivery", deltas)
    print_summary(s)
    save(s, deltas)
if gaps:
    print_summary(summarize("ws_inter_arrival", gaps))
if connects:
    print_summary(summarize("ws_connect", connects))

print(f"\nreconnects: {reconnects} | messages skipped (no timestamp/not JSON): {skipped}")
if skipped and not deltas:
    print("No usable timestamps found. Check EMITTED_FIELD against the docs.")

if name == "main":
main()

Run it during a busy period, such as when several matches are live:

bash
python ws_bench.py --samples 300 --max-seconds 900

A few things worth knowing before you interpret the output.

Negative numbers mean clock skew. If you see negative delivery latencies, your clock is behind the provider's. Install NTP or chrony and run again. Don't "fix" it by taking absolute values.

Measure at the right time. A stream during an empty Tuesday tells you nothing about a derby night. If you can, sample during peak load as well, because that's where p99 earns its keep. The WebSocket API page describes how the persistent-connection model is meant to be used.

Check whether it's a stall or a slow stream. The inter-arrival gap distribution is the quiet hero here. A delivery latency that looks fine with huge gaps between messages might just mean a quiet match. A spiky gap pattern with steady delivery latency usually means bursty events, not a slow pipe.

Step 4: benchmark webhooks

Webhooks flip the direction. Instead of you reaching out, the provider calls your server, so the thing you're building is a tiny receiving endpoint that stamps each request the moment it arrives.

python

webhook_bench.py

import time

from fastapi import FastAPI, Request

from config import EMITTED_FIELD
from stats import summarize, parse_ts_ms

app = FastAPI()
deltas = []
skipped = 0

@app.post("/webhook")
async def receive(request: Request):
global skipped
received_ms = time.time() * 1000 # stamp FIRST, before any parsing work

try:
    body = await request.json()
except Exception:
    skipped += 1
    return {"ok": False}

emitted_ms = parse_ts_ms(body.get(EMITTED_FIELD))
if emitted_ms is None:
    skipped += 1
else:
    deltas.append(received_ms - emitted_ms)

# Return fast. Do real work off the hot path in a real app.
return {"ok": True}

@app.get("/stats")
def stats():
return {"summary": summarize("webhook_delivery", deltas), "skipped": skipped}

Start it:

bash
uvicorn webhook_bench:app --host 0.0.0.0 --port 8000

Webhooks need a public URL, so for local testing put a tunnel in front of it. Any of these work:

bash
ngrok http 8000

or

cloudflared tunnel --url http://localhost:8000

Register https://your-public-url/webhook as your webhook target using the steps in the Webhooks API docs, trigger some live events, then open /stats in your browser to read the percentiles.

Two honest caveats here. First, the tunnel adds its own latency, so a laptop plus ngrok will overstate the real delivery time. For a result you can quote, run the receiver on a small cloud VM with a public IP. Second, if your provider signs webhook payloads, verify the signature in production. For benchmarking we skip it, but never ship an unauthenticated webhook endpoint.

Step 5: read the results without lying to yourself

Run all three, then put the numbers next to each other. Here's the mental model for what you're looking at:

What you ran What the number means
rest_warm p50 Typical cost of one request on a reused connection
rest_cold p50 What a first-time visitor pays
ws_delivery p95/p99 How late the unlucky updates are on a push stream
ws_connect Cost of (re)connecting after a drop
webhook_delivery Provider-to-your-server push, including your network path

And a few reading rules that save a lot of embarrassment:

Compare p95 and p99, not means. A p50 of 40ms and a p99 of 900ms is a very different product from a p50 of 60ms and a p99 of 120ms.
Don't compare REST to push directly. One measures a round trip, the other measures one-way delivery. They answer different questions.
Sample size matters. Under about 100 samples, p99 is mostly noise. Collect more before you quote it.
Run it more than once, at different times. One run is an anecdote. Three runs across a quiet hour and a busy hour start to look like evidence.
If numbers look strange, check the status page first. It could be a provider-side incident rather than your setup.
Testing without burning your quota

If you're still developing the benchmark, don't spend your real request budget debugging a bug in your own script. The sandbox lets you try requests and look at real response shapes first. Follow the quickstart for your first call, and if you'd rather not hand-roll HTTP code in your actual product, the SDKs page lists the official clients.

Extending the benchmark

Once the basics work, there's a lot you can bolt on:

Odds latency. If you consume markets, benchmark the Odds API separately. Odds change far more often than scores, so p99 behaviour under load looks different.
Live scores. Point the REST test at the Live Scores API and add a staleness check that compares the match state you get back against what you saw one poll ago.
Per-sport runs. A cricket stream and a tennis stream behave differently. Parametrize the path and compare.
Scheduled runs. Put it in a cron job or a GitHub Action, write the JSON files somewhere, and graph p95 over time. A latency regression you catch in a dashboard is cheaper than one you learn about from users.
Alerting. If p99 crosses a threshold you care about, send a message to your team chat.
Wrapping up

A benchmark you wrote yourself, against your own network, at your own peak hours, is worth more than any number on a landing page, including ours. Three scripts, one stats helper and a bit of discipline about percentiles and clocks is all it takes.

Fork this, point it at whatever feed you're evaluating, and let the data argue. If you want a place to start, grab a free key, run the sandbox, and see what your own p99 looks like.

From Free Tier to Production: Migrating Your App Through Orbistats' Pricing Tiers

orbistats — Mon, 05 Oct 2026 13:12:50 +0000

Disclosure: I work with the Orbistats team. This guide is written to be useful whichever plan you end up on, including staying on the free one.

Every successful API-powered app goes through the same awkward phase. It starts as a weekend prototype on a free key, works beautifully with three test users, and then someone says the dangerous sentence: "Can we launch this next month?"

Suddenly you have real questions. Will the free tier survive real traffic? When exactly do you need to pay? What changes in your code when you move from polling to real time? Do you need historical data now or later? And how do you upgrade without a rewrite or a Friday-night outage?

This post walks through that journey step by step using Orbistats, which covers 13 sports (football, basketball, American football, cricket, tennis, baseball, esports, combat sports, volleyball, handball, ice hockey, golf and horse racing) behind one API. We'll cover:

What each pricing tier is actually for
How to make the free tier last far longer than you think
A request budget tracker you can copy
A cost estimator so you can predict usage before launch
How to move from polling to WebSockets and webhooks
How to backfill historical data safely
A phase-by-phase migration plan with go-live checklists

All code is plain Node.js 18 or newer, so you can drop it into any backend.

The four tiers at a glance

At the time of writing (October 2026), the pricing page lists four tiers. Always confirm current limits there before you plan around them.

Free is $0 and positioned for testing. The documentation describes 150 requests per day on this plan, which is the number that shapes everything in the first half of this article.

Starter is $19 per month and positioned for real-time production use.

Growth is $79 per month and adds historical data, widgets and webhooks.

Enterprise is custom pricing with dedicated infrastructure, for teams with specific volume, support or delivery requirements.

A useful way to read this ladder is that each step unlocks a new capability, not just a bigger number. Free lets you prove the idea. Starter lets you run it live. Growth lets you build a richer product around history, embeds and push delivery. Enterprise lets you run it at serious scale with infrastructure of your own.

Stage 1: Prototype on the free tier

Start here, and don't feel bad about it. A free tier exists so you can find out whether your idea deserves money.

First, create an account and copy your API key. Second, read the quickstart and the documentation. Authentication is a bearer token, and the base URL is:

text
https://api.orbistats.com/v1/

Third, before you write any code, try a few calls in the Sandbox to see what real responses look like. Ten minutes there will save you hours of guessing field names.

Your first request looks like this:

js
// first-call.js
const res = await fetch("https://api.orbistats.com/v1/football/fixtures", {
headers: {
Authorization: Bearer ${process.env.ORBISTATS_API_KEY},
Accept: "application/json",
},
});

console.log(res.status);
console.log(await res.json());

Run it with node first-call.js and a key in your environment. If you see a 200 and some JSON, you are in business.

The important mindset for stage one: treat the daily limit as a design constraint from day one, not as a surprise at launch. Which brings us to the most valuable habit in this whole article.

Why 150 requests per day is enough for a prototype (if you are smart)

150 sounds tiny, but notice what it actually limits. It limits requests from your server to Orbistats. It does not limit how many people use your app.

If ten thousand users open your football page and your server answers all of them from a cache, you make one upstream request, not ten thousand. That single idea is the difference between a prototype that dies at ten users and one that survives a demo day.

The rule: users talk to your cache, and your cache talks to Orbistats.

Different data deserves different cache lifetimes, because different data changes at different speeds:

Live scores change constantly, so they get short lifetimes.
Fixtures change a few times a day.
Standings change after matches finish.
Team and competition lists barely change at all.

Build the client: cache, de-duplication, stale fallback and retries

Here is a small client that does the four things every production integration needs, even on the free plan. It caches by data type, shares one in-flight request between simultaneous callers, serves slightly old data if the API fails, and retries politely.

First, a tier configuration, so your code knows what the current plan allows:

js
// tiers.js
// null means: take the value from the Orbistats docs and set it in your environment.
export const TIERS = {
free: { dailyBudget: 150, realtime: false, historical: false, webhooks: false, widgets: false },
starter: { dailyBudget: null, realtime: true, historical: false, webhooks: false, widgets: false },
growth: { dailyBudget: null, realtime: true, historical: true, webhooks: true, widgets: true },
enterprise: { dailyBudget: null, realtime: true, historical: true, webhooks: true, widgets: true },
};

export const tier = TIERS[process.env.ORBISTATS_TIER ?? "free"];

Notice that the plan is an environment variable. When you upgrade, you change one setting and the rest of your app adapts, which is exactly the migration experience you want.

Next, a request budget tracker. It counts every upstream call and refuses to exceed your plan, so a bug can never burn your whole day's allowance in ten minutes:

js
// budget.js
import { tier } from "./tiers.js";

const today = () => new Date().toISOString().slice(0, 10);

export const budget = {
limit: Number(process.env.ORBISTATS_DAILY_BUDGET) || tier.dailyBudget,
day: today(),
used: 0,

take() {
// Roll the counter over at the start of a new day.
// This assumes a UTC day. Confirm how the reset window works in the docs.
if (this.day !== today()) {
this.day = today();
this.used = 0;
}
if (this.limit && this.used >= this.limit) return false;
this.used += 1;
return true;
},

status() {
return {
used: this.used,
limit: this.limit,
ratio: this.limit ? this.used / this.limit : null,
};
},
};

Now the client itself:

js
// client.js
import { budget } from "./budget.js";

const BASE = "https://api.orbistats.com/v1";
const cache = new Map();
const inflight = new Map();

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function fetchWithRetry(path, attempts = 3) {
for (let attempt = 0; attempt < attempts; attempt++) {
if (!budget.take()) {
throw Object.assign(new Error("Daily request budget used up"), { status: 429 });
}

const res = await fetch(`${BASE}${path}`, {
  headers: {
    Authorization: `Bearer ${process.env.ORBISTATS_API_KEY}`,
    Accept: "application/json",
  },
});

if (res.ok) return res.json();

const retryable = res.status === 429 || res.status >= 500;
if (!retryable || attempt === attempts - 1) {
  throw Object.assign(new Error(`Orbistats ${res.status} on ${path}`), {
    status: res.status,
  });
}

// Exponential backoff: 500ms, 1000ms, 2000ms.
await sleep(500 << attempt);

}
}

export async function getData(path, { ttlMs = 30_000, staleMs = 600_000 } = {}) {
const now = Date.now();
const hit = cache.get(path);

// 1. Fresh cache wins.
if (hit && now - hit.at < ttlMs) return { data: hit.data, source: "cache" };

// 2. If someone is already fetching this path, wait for that request.
if (inflight.has(path)) return inflight.get(path);

// 3. Otherwise fetch, and fall back to slightly old data if it fails.
const job = fetchWithRetry(path)
.then((data) => {
cache.set(path, { at: Date.now(), data });
return { data, source: "live" };
})
.catch((err) => {
if (hit && now - hit.at < staleMs) return { data: hit.data, source: "stale" };
throw err;
})
.finally(() => inflight.delete(path));

inflight.set(path, job);
return job;
}

Why each piece matters:

The in-flight map stops a "thundering herd". When 500 users load a page at the same instant, they share one upstream call.

Stale fallback means that if Orbistats or your network has a brief problem, users see data that is a few minutes old instead of an error page. For standings or fixtures, that is almost always the right trade-off.

Backoff only retries errors that can recover (429 and 5xx). A 401 or 404 won't fix itself, so you fail fast. In production you should also respect a Retry-After header if the API sends one, and add a little random jitter to your delays.

The budget guard turns a silent quota problem into a clear, loggable error.

Using it in a route:

js
// server.js (excerpt)
import "dotenv/config";
import express from "express";
import { getData } from "./client.js";
import { budget } from "./budget.js";

const app = express();

app.get("/api/:sport/live", async (req, res, next) => {
try {
const { data, source } = await getData(/${req.params.sport}/matches/live, {
ttlMs: 600_000, // free-tier friendly: 10 minutes
});
res.set("X-Data-Source", source);
res.json(data);
} catch (e) { next(e); }
});

app.get("/internal/usage", (_req, res) => res.json(budget.status()));

app.listen(3000);

The X-Data-Source header and the /internal/usage endpoint cost nothing and give you instant visibility. Check them while you develop, so you always know whether a response came from cache, from the live API, or from the stale fallback.

Predict your usage before you launch

Guessing is how people get surprised. Because your cache decouples users from requests, you can estimate upstream usage with simple arithmetic. It depends on how many sports you show and how fresh each feed needs to be, not on how many visitors you have.

js
// estimate.js
// Upstream requests per day = for each feed, active seconds divided by cache lifetime.
export function dailyRequests(plan) {
return plan.reduce(
(sum, feed) => sum + Math.floor(feed.activeSeconds / feed.ttlSeconds),
0
);
}

const eagerPlan = [
{ name: "football live", ttlSeconds: 15, activeSeconds: 28_800 }, // 8 hours
{ name: "football fixtures", ttlSeconds: 300, activeSeconds: 86_400 },
{ name: "football standings", ttlSeconds: 600, activeSeconds: 86_400 },
];

const frugalPlan = [
{ name: "football live", ttlSeconds: 600, activeSeconds: 28_800 },
{ name: "football fixtures", ttlSeconds: 3_600, activeSeconds: 86_400 },
{ name: "football standings", ttlSeconds: 21_600, activeSeconds: 86_400 },
];

console.log("eager:", dailyRequests(eagerPlan)); // 2352 per day
console.log("frugal:", dailyRequests(frugalPlan)); // 76 per day

Run it and look at the gap. A single sport with 15-second live caching needs 2,352 requests a day, which is far beyond the free plan. The same sport with relaxed cache times needs 76. That is the real shape of the decision:

If your product is fine with live data that is several minutes old, the free tier can carry a surprising amount.

If your product promises genuinely live scores, you have outgrown the free tier, and that's exactly what the next plan is for.

Multiply the exercise by the number of sports you cover, and you'll know in five minutes which plan you need.

Signals that it's time to upgrade

You don't need a spreadsheet to know when to move. Upgrade when you see these:

Your budget tracker regularly passes 80 percent before the day is half over.
Product asked for live scores that update in seconds, not minutes.
You are caching so aggressively that the data feels stale to your users.
You are covering more sports, and the multiplication no longer fits.
You need history for charts, head-to-head or models.
You need push delivery instead of polling.
You are about to run a campaign, a launch or a tournament that will spike traffic.
You've started charging users or promising an uptime level.

Here is a simple, honest way to think about cost. The Starter tier is $19 per month. If staying on the free plan forces even an hour of extra engineering time per month to squeeze usage, the paid plan is probably the cheaper option. Developer time is the expensive resource, so spend money to save it.

Stage 2: Go live on Starter

Starter is the real-time production step. The big change in your architecture is that you stop polling and start listening.

Polling every 15 seconds is wasteful. Most requests return "nothing changed". A WebSocket keeps one connection open, and updates arrive the moment they happen. Pair that with the Live Scores API for the initial state and you have a proper live experience.

Here is the pattern: load the current state over REST once, then keep it fresh from the stream.

js
// realtime.js
import "dotenv/config";
import WebSocket from "ws"; // npm install ws
import { tier } from "./tiers.js";

const listeners = new Set();
export const onUpdate = (fn) => listeners.add(fn);

export function startRealtime() {
if (!tier.realtime) {
console.log("Real-time is not enabled on this plan, staying on cached polling.");
return;
}

let attempt = 0;

function connect() {
// Get the real URL and subscription message from the WebSocket docs.
const ws = new WebSocket(process.env.ORBISTATS_WS_URL, {
headers: { Authorization: Bearer ${process.env.ORBISTATS_API_KEY} },
});

ws.on("open", () => {
  attempt = 0;
  ws.send(JSON.stringify({ action: "subscribe", sport: "football" }));
});

ws.on("message", (buf) => {
  const event = JSON.parse(buf.toString());
  for (const fn of listeners) fn(event);
});

ws.on("close", () => {
  // Reconnect with exponential backoff, capped at 30 seconds.
  const delay = Math.min(30_000, 1_000 << attempt);
  attempt += 1;
  setTimeout(connect, delay);
});

ws.on("error", (err) => console.warn("WebSocket error:", err.message));

}

connect();
}

Note the first lines of startRealtime. Because the plan is a setting, the very same codebase runs on both the free and the paid tier. On free it politely stays on cached polling. On Starter it switches to the stream. No branches in your business logic, no separate deployment.

To get those events into browsers, forward them with Server-Sent Events:

js
// stream.js
const clients = new Set();

export function mountStream(app) {
app.get("/stream", (req, res) => {
res.set({
"Content-Type": "text/event-stream",
"Cache-Control": "no-cache",
Connection: "keep-alive",
});
res.flushHeaders();
clients.add(res);
req.on("close", () => clients.delete(res));
});
}

export function broadcast(event) {
for (const c of clients) c.write(data: ${JSON.stringify(event)}\n\n);
}

Connect the two pieces with one line, onUpdate(broadcast), and every browser tab updates the moment a score changes.

If your product shows prices, add the Odds API to the same pipeline. It returns normalized odds across bookmakers in one schema, so you don't maintain a parser per bookmaker. If you want richer match pages, the Sports Statistics API adds team and player numbers.

Starter go-live checklist

Environment variable ORBISTATS_TIER switched to starter, and the budget limit set from the docs.
WebSocket reconnect tested by killing the connection on purpose.
REST used for initial state, stream used for changes.
Alert when the budget passes 80 percent.
Error pages tested with the API unreachable, to confirm that the stale fallback works.
The status page added to your monitoring routine.
A dashboard or log line showing the data source (cache, live, stale).

Stage 3: Grow into history, webhooks and widgets

Growth is where your product gets deeper rather than just bigger. At the time of writing it adds historical data, widgets and webhooks.

Historical data

The Historical Sports Data API is a multi-season archive (fixtures, results, statistics, lineups, events and closing odds, with seasons going back as far as 2010 for covered data). It unlocks head-to-head history, season form charts, backtesting and machine learning datasets.

The golden rule with history: fetch it once, store it yourself, and never ask for it again. Old seasons don't change, so a one-time backfill is vastly cheaper than hitting the API on every page view.

js
// backfill.js
import { appendFile, readFile } from "node:fs/promises";
import { getData } from "./client.js";

const OUT = "history.jsonl";
const PROGRESS = "history.progress.json";

async function loadProgress() {
try { return JSON.parse(await readFile(PROGRESS, "utf8")); }
catch { return { done: [] }; }
}

async function saveProgress(p) {
const { writeFile } = await import("node:fs/promises");
await writeFile(PROGRESS, JSON.stringify(p));
}

export async function backfill(sport, seasons) {
const progress = await loadProgress();

for (const season of seasons) {
const key = ${sport}:${season};
if (progress.done.includes(key)) continue; // resume support

// PLACEHOLDER: confirm the exact historical path and parameters in the API reference.
const { data } = await getData(`/${sport}/results?season=${season}`, {
  ttlMs: 0,
});

const rows = Array.isArray(data) ? data : (data.data ?? []);
const lines = rows.map((r) => JSON.stringify({ sport, season, ...r })).join("\n");
if (lines) await appendFile(OUT, lines + "\n");

progress.done.push(key);
await saveProgress(progress);
console.log(`Saved ${rows.length} rows for ${key}`);

}
}

// Example: backfill(...) with the seasons you actually need.
// await backfill("football", [2022, 2023, 2024, 2025]);

A few reasons this script is written the way it is. It saves progress after every season, so if it crashes or you hit a limit, you resume instead of starting over. It goes through the same budget-aware client, so you can't accidentally burn your quota. It writes one JSON object per line, which loads easily into a database, a notebook or a data pipeline later.

Also be mindful of usage terms when you store data. Read the data licensing page before you redistribute or display archived data commercially.

Webhooks

Webhooks flip the direction. Instead of you listening, Orbistats calls your server when something happens. They are ideal for notifications, background jobs and anything that shouldn't depend on a browser being open.

js
// webhook.js
import express from "express";

const seen = new Set(); // use Redis or a database in production

export function mountWebhook(app, handleEvent) {
app.post("/webhook/sports", express.json(), (req, res) => {
// 1. Verify the signature using the method described in the webhook docs.
// 2. Ignore duplicates, because delivery systems can send the same event twice.
const id = req.body?.event_id ?? JSON.stringify(req.body);
if (seen.has(id)) return res.sendStatus(200);
seen.add(id);

// 3. Acknowledge immediately, process afterwards.
res.sendStatus(200);
queueMicrotask(() => handleEvent(req.body));

});
}

Three habits protect you here: verify authenticity, make handlers idempotent so a repeated event is harmless, and answer fast. If your endpoint is slow, senders may retry and you get even more duplicates.

Widgets

If part of your product is content (articles, previews, recaps), you don't need to build every score box yourself. Orbistats Widgets let you embed ready-made components such as live scores, a match center and an odds board. A sensible split is custom UI for the screens that define your product and widgets for the long tail of pages.

Growth go-live checklist

Historical data backfilled once and stored on your side.
Webhook endpoint verified, idempotent and fast.
Duplicate event handling tested by replaying one on purpose.
Widget containers reserve height, so pages don't jump when they load.
Licensing terms read for any commercial display of archived data.
Backups of your stored history.

Stage 4: Enterprise and beyond

Enterprise is for teams whose needs have moved past a published tier: very high volume, dedicated infrastructure, custom feeds, specific support expectations or contractual requirements. There is no code change to talk about here, because if you followed the earlier stages your integration is already plan-agnostic. What you do need is a clear conversation.

Before you contact sales (the address on the site is sales@orbistats.com), prepare answers to these questions:

Which sports and competitions do you need, and how many requests per day or events per second do you expect at peak?
Which delivery methods matter most: REST, WebSocket, webhooks or all three?
What latency do you need, and what are you measuring today?
Do you need historical depth, bulk exports or custom data feeds?
What support, uptime and reporting expectations does your business have?
What will your usage look like at launch, in six months and in twelve?

The estimator script from earlier turns directly into the volume numbers for that conversation. Teams that arrive with data tend to get faster, more useful answers.

A clean way to switch plans without drama

The best migrations are boring. Here is the sequence that keeps them boring.

Create separate keys for development, staging and production, and never share a key across environments.
Keep every plan-specific behaviour behind the tier configuration, so an upgrade is a settings change.
Upgrade in staging first and run your full test flow, including failure cases.
Switch production during a quiet period, not an hour before a big match.
Watch the usage endpoint and the data-source header for the first day.
Keep the old behaviour available as a fallback for a week, so you can roll back by changing one variable.
Only then remove the workarounds you built for the lower tier, such as the extreme cache lifetimes.

Step seven is the one people skip, and it's the satisfying part. After upgrading, relax your caching, lower your live latency and let the product feel the way you originally imagined.

Common mistakes to avoid

Calling the API from the browser, which exposes your key and bypasses your cache.
Using one key for everything, so a staging bug can burn production quota.
Treating the daily limit as a problem to discover at launch instead of a design constraint from day one.
Polling every few seconds for data that rarely changes.
Re-fetching old seasons on every request instead of storing them once.
Building the whole app around one plan's behaviour, which makes upgrading painful.
Skipping the fallback, so one failed request turns into a blank screen.
Upgrading in a panic during a spike instead of planning ahead from your own usage numbers.
Ignoring versioning. Orbistats uses versioned paths such as /v1/, so pin your integration to a version and read the changelog before changing it.

Quick recap

Stay on Free while you validate the idea, and make it last with caching, de-duplication and a request budget.

Move to Starter when you need genuinely live data in production, and switch from polling to WebSockets.

Move to Growth when you need history, push delivery with webhooks, or embeddable widgets.

Talk to sales about Enterprise when your volume, latency or support needs go beyond a published plan.

And through every stage, keep the plan as a configuration setting, keep your key on the server, and keep the browser talking to your own backend.

Where to go next

Read the documentation for authentication, versioning and limits.
Try responses in the Sandbox before you write code.
Explore the API reference for the exact endpoints and parameters.
Compare tiers on the pricing page.

Ready to start? Grab a free API key and run the estimator on your own project today. You'll know in five minutes which stage you're really at.

Over to you: what was the moment you realised your side project needed a real plan, a traffic spike, a client demo, or something else? Share your story in the comments, and tell me which part of the migration you'd like a deeper dive on.

Orbistats Widgets vs Custom UI: Pre-Built Match Center

orbistats — Mon, 05 Oct 2026 13:09:36 +0000

Disclosure: I work with the Orbistats team. This post is meant to help you make an honest build-or-embed decision, including the cases where you should not use our widgets.

Every sports product hits the same fork in the road. You have the data, you have a design in your head, and you have a deadline. Do you spend weeks building a match center from scratch, or do you drop in a pre-built one and ship this afternoon?

Most blog posts answer this with "it depends". This one tries to be more useful. We'll go through a concrete decision framework, a small scoring script you can run on your own project, three working architecture patterns (widget-only, custom-only and hybrid), and the details people forget: SEO, performance, layout shift, content security policy and fallbacks.

By the end you'll know exactly when to embed, when to build, and how to do both without regret.

The two options in plain words

Option A is widgets. Orbistats Widgets are drop-in components such as a live score widget, a match center widget and an odds board widget. Your site embeds them, Orbistats powers the data and the UI, and you write very little front-end code.

Option B is a custom UI. You consume the data yourself through the Sports Data API, the Live Scores API and optionally the Odds API, then design and build every pixel.

Both options sit on top of the same data platform, which across 13 sports means football, basketball, American football, cricket, tennis, baseball, esports, combat sports, volleyball, handball, ice hockey, golf and horse racing. That is important because it means you are not locked in. You can start with widgets and move to custom later, or mix them.

What a match center actually contains

When people say "match center" they usually imagine a scoreboard. In reality, a good one is a small application. Here is what a complete one handles:

The header: teams or players, logos, score, status and match clock
The timeline: goals, cards, substitutions, wickets, sets, rounds, depending on the sport
Statistics: possession, shots, corners, aces, rebounds, and so on
Lineups and formations
Head-to-head history
Odds, if your product shows them
Live updates without a page refresh
Edge states: postponed, delayed, abandoned, extra time, penalties, walkovers, retirements
Mobile layout, dark mode, accessibility and translations

Each item looks small on its own. Together they are the reason "we'll just build it ourselves" quietly becomes a six-week project. This is the hidden iceberg of custom sports UI.

The hidden cost of custom UI

Let's be fair to both sides, starting with the cost of building your own.

Sport differences multiply the work. A football timeline and a tennis timeline share almost nothing. Golf and horse racing don't even have a home and away side. If you cover many sports, you are building many match centers.

Live updates need real engineering. Polling is easy to start and expensive to scale. Doing it properly means a WebSocket connection or webhooks, reconnect logic, de-duplication of events and graceful degradation.

Edge cases arrive after launch. Nobody designs the "match abandoned at 63 minutes" screen on day one. Users find it for you.

Maintenance never ends. Every new competition, data field or sport is a ticket in your backlog.

On the other hand, custom UI gives you total control over design, interaction and how data blends with your own product. For some products that control is the whole point.

The hidden cost of widgets

Widgets are not free of trade-offs either.

You get less design freedom. Even a well-themed widget will not behave exactly like a component designed for your product.

Your own data is harder to mix in. If you want to overlay user predictions, wallet balances, fantasy picks or personalised alerts directly inside the match view, an embed is the wrong tool.

SEO needs care. Content rendered inside an embed may not count as your page's content. We'll fix that below.

Embeds touch your security setup. Third-party scripts and frames need to be allowed in your content security policy, and you should plan for what happens when they fail to load.

Plan limits apply. At the time of writing (October 2026), the pricing page positions Growth at $79/month with historical data, widgets and webhooks, while Free is $0 for testing and Starter is $19/month for real-time production. Check which plan includes the widgets you need before you design around them.

A decision framework you can run in 30 seconds

Here is a simple, honest scorecard. Positive numbers push you toward widgets. Negative numbers push you toward a custom build. It is deliberately small so you can edit the weights for your team.

js
// decide.js
// Positive score leans widget. Negative score leans custom.

const FACTORS = [
{ id: "launchFast", ask: "Must it be live in days, not weeks?", yes: 2 },
{ id: "noFrontendCapacity", ask: "No spare front-end developer time?", yes: 2 },
{ id: "contentSite", ask: "Is this for articles, blogs or editorial pages?", yes: 2 },
{ id: "strictBrand", ask: "Must it match a strict design system exactly?", yes: -2 },
{ id: "customInteractions", ask: "Need betslips, favourites, picks or predictions?", yes: -3 },
{ id: "joinOwnData", ask: "Must it blend with your own users or data?", yes: -2 },
{ id: "nativeApp", ask: "Is the main surface a native mobile app?", yes: -3 },
];

export function decide(answers) {
const score = FACTORS.reduce(
(sum, f) => sum + (answers[f.id] ? f.yes : 0),
0
);

if (score >= 3) return { score, verdict: "Use the pre-built widgets" };
if (score <= -2) return { score, verdict: "Build a custom UI" };
return { score, verdict: "Go hybrid: widgets first, custom where it matters" };
}

// Example: a news site adding match pages to articles
console.log(
decide({ launchFast: true, noFrontendCapacity: true, contentSite: true })
);
// { score: 6, verdict: "Use the pre-built widgets" }

// Example: a fantasy app with picks and user data
console.log(
decide({ customInteractions: true, joinOwnData: true, strictBrand: true })
);
// { score: -7, verdict: "Build a custom UI" }

Run it with node decide.js. It is not science, but it forces the conversation your team needs to have, and it makes the answer visible to non-engineers.

Which audience usually lands where

The Orbistats solution pages are organised by audience, and the pattern holds up in practice.

Media and publishers lean heavily toward widgets. If you run editorial pages, Media and Publishers is the natural fit: live scores and match centers on article pages without a front-end project.

Fantasy and analytics products lean custom. The product is the experience, so Fantasy and AI Data teams usually build their own UI on top of the data API.

Sportsbooks and trading products lean custom with real-time feeds. Branding, bet flows and latency matter, so Sportsbooks and Trading teams generally consume odds directly.

Startups and MVPs lean widgets first. Validate that anyone cares about your match pages before investing in a bespoke component library.

Agencies and client sites lean widgets. Fast delivery, low maintenance, predictable result.

Pattern 1: Widget-only (the afternoon build)

If the scorecard said widget, here is how to embed it properly rather than just pasting a snippet and hoping.

First, get access. Create an account, then open the documentation and the widgets page for the exact embed code, supported options and theming controls. The snippet below uses clearly marked placeholders, so replace them with the real values from the docs.

Here is a loader that does three things most copy-pasted embeds don't: it lazy-loads the widget only when it scrolls into view, it reserves space to prevent layout shift, and it never blocks your page.

html

Manchester City vs Arsenal

Premier League, Sunday 18 October 2026, 16:30 UTC

.match-center-slot {
min-height: 520px; /* reserve space so the page does not jump */
border-radius: 12px;
background: rgb(20, 29, 51);
}

// PLACEHOLDER: copy the real script URL and options from the Orbistats widgets docs
const WIDGET_SRC = "WIDGET_SCRIPT_URL_FROM_DOCS";

const slot = document.getElementById("match-center");

const observer = new IntersectionObserver((entries) => {
if (!entries[0].isIntersecting) return;
observer.disconnect();

const s = document.createElement("script");
s.src = WIDGET_SRC;
s.async = true;
document.head.append(s);
// The widget then mounts into the slot as described in the docs.

}, { rootMargin: "200px" });

observer.observe(slot);

Why this matters: a widget at the bottom of a long article might never be seen, and loading it anyway wastes your user's bandwidth. Lazy-loading with a 200px margin means it is ready just before the reader reaches it.

Pattern 2: Custom-only (when the UI is the product)

If you chose custom, you will build on the data API. The safest architecture is the same one from the multi-sport dashboard approach: a small server that holds your API key, caches responses and normalises shapes.

js
// server.js (excerpt)
import "dotenv/config";
import express from "express";

const app = express();
const BASE = "https://api.orbistats.com/v1";
const cache = new Map();

async function orbistats(path, ttlMs) {
const hit = cache.get(path);
if (hit && Date.now() - hit.at < ttlMs) return hit.data;

const res = await fetch(${BASE}${path}, {
headers: {
Authorization: Bearer ${process.env.ORBISTATS_API_KEY},
Accept: "application/json",
},
});
if (!res.ok) throw Object.assign(new Error("Upstream error"), { status: res.status });

const data = await res.json();
cache.set(path, { at: Date.now(), data });
return data;
}

// The live-scores sample on the Orbistats homepage uses this path shape.
app.get("/api/:sport/live", async (req, res, next) => {
try {
res.json(await orbistats(/${req.params.sport}/matches/live, 15000));
} catch (e) { next(e); }
});

app.listen(3000);

And a score header component that renders safely from untrusted text:

js
// matchHeader.js
export function renderMatchHeader(container, match) {
container.replaceChildren();

const status = document.createElement("div");
status.className = "status";
status.textContent =
match.status === "live" ? LIVE ${match.minute}' : match.status;

const row = document.createElement("div");
row.className = "teams";

for (const side of [match.home, match.away]) {
const el = document.createElement("div");
const name = document.createElement("span");
name.textContent = side.name;
const score = document.createElement("strong");
score.textContent = side.score;
el.append(name, score);
row.append(el);
}

container.append(status, row);
}

Field names such as status, minute, home and away follow the homepage sample, so confirm them against the API reference for each sport you cover. You can also use the SDKs if you would rather not write fetch calls by hand, and the Sandbox is the fastest way to look at real responses.

For true live behaviour, replace polling with the WebSocket API or webhooks. A custom match center that polls every few seconds works in a demo and falls over in production.

Pattern 3: The hybrid (what most teams should do)

Here is the opinion I'd stand behind: for most products, the right answer is hybrid.

Your homepage, your hero scoreboard, your favourite-team feed and your highest-converting flows are where design, speed and your own data matter. Build those custom.

Your long tail is different. A basketball game page nobody visits twice, a handball fixture, a golf leaderboard, a volleyball result: these are valuable for coverage and SEO, but they don't justify a bespoke component each. Use the pre-built match center there.

This gives you full coverage across all 13 sports from day one, and you invest design effort only where it pays back.

A configuration object makes the split explicit and easy to change:

js
// matchMode.js
// Sports where you built your own match center. Everything else uses the widget.
const CUSTOM_SPORTS = new Set(["football", "cricket"]);

export function modeFor(sport) {
return CUSTOM_SPORTS.has(sport) ? "custom" : "widget";
}

Add a resilient fallback

Here is the step that separates a professional hybrid from a fragile one. If the widget script fails to load (an ad blocker, a network blip, a blocked origin), your page should still show something useful. Fall back to your own simple score header, which you already built.

js
// mountMatch.js
import { renderMatchHeader } from "./matchHeader.js";
import { modeFor } from "./matchMode.js";

function loadScript(src) {
return new Promise((resolve, reject) => {
const s = document.createElement("script");
s.src = src;
s.async = true;
s.onload = resolve;
s.onerror = () => reject(new Error("Widget script failed"));
document.head.append(s);
});
}

function withTimeout(promise, ms) {
return Promise.race([
promise,
new Promise((_, reject) =>
setTimeout(() => reject(new Error("Widget timeout")), ms)
),
]);
}

async function renderCustom(slot, sport, matchId) {
const res = await fetch(/api/${sport}/live);
const matches = await res.json();
const match = (matches.data ?? matches).find((m) => m.match_id === matchId);
if (match) renderMatchHeader(slot, match);
else slot.textContent = "Match details are not available right now.";
}

export async function mountMatch(slot) {
const { sport, matchId } = slot.dataset;

if (modeFor(sport) === "custom") {
return renderCustom(slot, sport, matchId);
}

try {
// PLACEHOLDER: use the real widget script URL from the Orbistats docs
await withTimeout(loadScript("WIDGET_SCRIPT_URL_FROM_DOCS"), 4000);
} catch (err) {
console.warn("Falling back to custom header:", err.message);
await renderCustom(slot, sport, matchId);
}
}

The result: widgets do the heavy lifting, but if they fail, users still see the score. That one small function turns an embed from a single point of failure into a progressive enhancement.

Make widgets look like they belong

Whichever pattern you pick, visual consistency decides whether your embed feels native or bolted on. Check the widgets docs for the theming options that are supported, then wrap the slot with your own design tokens so that everything around the widget matches:

css
.match-center-slot {
--surface: rgb(20, 29, 51);
--border: rgb(37, 51, 90);
--accent: rgb(47, 107, 255);

background: var(--surface);
border: 1px solid var(--border);
border-radius: 12px;
padding: 8px;
min-height: 520px;
}

@media (prefers-color-scheme: light) {
.match-center-slot {
--surface: rgb(255, 255, 255);
--border: rgb(220, 226, 240);
}
}

Even if the widget itself has limited styling, a consistent container, spacing and heading typography around it removes most of the "this is a third-party box" feeling.

SEO: do not let the widget be your only content

This is the mistake that costs publishers the most. If your match page is just a title and an embed, search engines may see an almost empty page, because content rendered inside a script or frame often isn't treated as your content.

The fix is simple. Render the essentials yourself as plain HTML (teams, competition, date, venue and a short summary), and describe the event with structured data:

html

Manchester City vs Arsenal: Match Centre

Follow live score, events and statistics for Manchester City vs Arsenal,
Sunday 18 October 2026, kick-off 16:30 UTC.

{
"@context": "https://schema.org",
"@type": "SportsEvent",
"name": "Manchester City vs Arsenal",
"startDate": "2026-10-18T16:30:00Z",
"sport": "Football",
"homeTeam": { "@type": "SportsTeam", "name": "Manchester City" },
"awayTeam": { "@type": "SportsTeam", "name": "Arsenal" }
}

Now the page has real, indexable text and structured data, while the widget provides the live experience on top. For a site with thousands of match pages across multiple sports, this pattern alone can be the difference between pages that rank and pages that don't.

Performance and security checklist for embeds

Reserve height with min-height so the page doesn't shift when the widget loads.
Lazy-load below-the-fold widgets with IntersectionObserver, as shown above.
Never block rendering: use async or defer for the widget script.
Allow the widget origin in your content security policy. Take the real origin from the docs:

text
Content-Security-Policy:
script-src 'self' https://WIDGET_ORIGIN;
frame-src https://WIDGET_ORIGIN;
connect-src 'self' https://WIDGET_ORIGIN

Keep the API key out of the browser. Widgets handle their own access, and your custom UI should always go through your server.
Add a visible fallback message for when scripts are blocked.
Test with an ad blocker on, because it will happen to real users.

What about cost and request limits?

There is a cost dimension that rarely shows up in comparisons. With a custom UI, every visitor interaction can create load on your server and requests against your API plan, which is why caching matters so much. At the time of writing, the documentation describes 150 requests per day on the Free plan, so you cannot run a public match center on it without aggressive caching. The pricing page lays out the tiers.

With widgets, you should confirm how widget traffic is counted against your plan and which plan unlocks them. Ask before you launch, not after your first traffic spike.

A simple way to think about it: widgets trade design control for lower engineering and operating cost, and custom UI trades engineering cost for control.

How to migrate from widget to custom without a rewrite

Starting with widgets and moving later is a legitimate strategy, as long as you plan for it.

Wrap the widget in your own mount function (like mountMatch above), so the rest of your code never calls the widget directly.
Keep a stable slot element and data attributes for sport and match ID. These are the contract between your page and either implementation.
Track real metrics on widget pages, such as engagement, time on page, bounce rate and conversion.
Replace one sport at a time by adding it to CUSTOM_SPORTS. Because modeFor is the only switch, rollout is a one-line change per sport.
Keep the widget as the fallback for sports you haven't customised.

This is the lowest-risk path, and it lets data (not opinions) decide where to invest your design time.

Common mistakes to avoid

Building a custom match center for all 13 sports on day one, when only two sports drive traffic.
Using a widget as your only page content and wondering why it doesn't rank.
Calling the data API directly from the browser and exposing your key.
Polling every second instead of using WebSockets or webhooks.
Ignoring layout shift, so the page jumps as the widget loads.
Forgetting the failure state, so a blocked script leaves a blank box.
Choosing based on what looks fun to build instead of what the product needs.

Quick recap

Use the pre-built widgets when you need speed, you run editorial or content pages, you have limited front-end capacity, or you want broad coverage across many sports with little maintenance.

Build a custom UI when the experience is the product, you need your own interactions and data inside the match view, or you need strict brand control.

Go hybrid when you want the best of both: custom where it differentiates you, widgets for the long tail, and a fallback so users never see an empty box.

Where to go next

Read the documentation and the quickstart to see how auth and the first request work.
Open the Widgets page to see the components available.
Try real responses in the Sandbox before you commit to a custom build.
Compare tiers on the pricing page.

When you're ready, you can grab a free API key and prototype both approaches side by side. Often an hour with each tells you more than a week of debate.

Over to you: are you team widget, team custom, or team hybrid? And what's the nastiest edge case your match center has ever hit? Share it in the comments, I'd love to compare notes.

Build a Multi-Sport Dashboard with Orbistats' 13-Sport API

orbistats — Mon, 05 Oct 2026 13:04:23 +0000

Disclosure: I work with the Orbistats team. The tutorial is hands-on and the code is yours to reuse, but you should know where I'm coming from.

If you've ever built a sports app, you know how it starts: "We'll just add football first." Then someone asks for basketball. Then cricket. Then tennis, because the CEO watches Wimbledon. Six months later you maintain five different data providers, five different JSON shapes, and five different ways to say "this match is live."

In this tutorial we'll build a multi-sport dashboard that covers 13 sports from a single API, with one auth method, one base URL, and one consistent way to ask for fixtures, live scores, standings and odds.

By the end you'll have:

A Node.js and Express backend that keeps your API key safe and caches responses
A single-page dashboard with a tab for each of the 13 sports
Live scores that refresh automatically
Standings and odds panels
A clear path from polling to WebSockets and webhooks
A plan for historical data (charts, backtesting, ML)

No framework required. Just Node 18+ and plain JavaScript, so you can port it to React, Vue or Svelte later.

What is Orbistats, and why use one API for many sports?

Orbistats is a sports data and odds API platform. Instead of selling you one league or one sport, it exposes 13 sports through one REST API: Football, Basketball, American Football, Cricket, Tennis, Baseball, Esports, Combat Sports, Volleyball, Handball, Ice Hockey, Golf and Horse Racing.

For a multi-sport dashboard, that matters for three reasons.

First, one integration. One API key, one Authorization header, one base URL.

Second, one mental model. Fixtures, results, standings, odds and statistics work the same way across sports. Only the sport segment of the URL changes.

Third, one bill. You scale with traffic instead of with the number of vendors.

The platform is split into products you can mix and match:

The Sports Data API covers fixtures, results, standings, teams and competitions.
The Live Scores API covers in-play scores and match events.
The Sports Statistics API covers team and player stats.
The Odds API gives normalized odds from multiple bookmakers.
The Historical Sports Data API gives multi-season archives.
The WebSocket API and Webhooks give push-based delivery.
Widgets are drop-in UI components.

The architecture

Before writing code, here's the shape of what we're building:

text
Browser (dashboard)
| fetch /api/...
v
Your Express server --(cache)--> Orbistats API

hides API key https://api.orbistats.com/v1/
validates sport slug
normalizes JSON

Never call a paid API directly from the browser. Anyone can open DevTools and steal your key. A tiny proxy server fixes that, and it also gives us a place to add caching, which matters a lot on a free tier (more on that later).

Step 0: Get your API key

First, create a free account and copy your API key.

Second, skim the documentation and the quickstart. Authentication is a standard bearer token:

http
Authorization: Bearer YOUR_API_KEY

Third, the base URL is:

text
https://api.orbistats.com/v1/

Fourth, if you want to poke at responses before writing code, use the Sandbox to fire a request and inspect the JSON.

The free plan is enough for this tutorial. At the time of writing (October 2026), the pricing page lists Free at $0, Starter at $19/month for real-time production use, Growth at $79/month (adds historical data, widgets and webhooks), and a custom Enterprise tier.

Step 1: Project setup

bash
mkdir multi-sport-dashboard
cd multi-sport-dashboard
npm init -y
npm install express dotenv

Open package.json and add "type": "module" so we can use import statements.

Create a .env file (and add it to .gitignore):

text
ORBISTATS_API_KEY=your_key_here
PORT=3000

Project structure:

text
multi-sport-dashboard/
server.js
sports.js
normalize.js
public/
index.html
.env
package.json

Step 2: A registry of all 13 sports

Rather than hard-coding sports all over the app, keep one registry. Adding or removing a sport becomes a one-line change.

js
// sports.js
export const SPORTS = [
{ slug: "football", label: "Football", icon: "⚽" },
{ slug: "basketball", label: "Basketball", icon: "🏀" },
{ slug: "american-football", label: "American Football", icon: "🏈" },
{ slug: "cricket", label: "Cricket", icon: "🏏" },
{ slug: "tennis", label: "Tennis", icon: "🎾" },
{ slug: "baseball", label: "Baseball", icon: "⚾" },
{ slug: "esports", label: "Esports", icon: "🎮" },
{ slug: "combat-sports", label: "Combat Sports", icon: "🥊" },
{ slug: "volleyball", label: "Volleyball", icon: "🏐" },
{ slug: "handball", label: "Handball", icon: "🤾" },
{ slug: "ice-hockey", label: "Ice Hockey", icon: "🏒" },
{ slug: "golf", label: "Golf", icon: "⛳" },
{ slug: "horse-racing", label: "Horse Racing", icon: "🏇" },
];

export const SPORT_SLUGS = new Set(SPORTS.map((s) => s.slug));

These slugs mirror the sport pages on the site, such as football, cricket and horse racing. Confirm each slug against the API reference when you wire it up.

Step 3: The proxy server with caching

This is the heart of the app. It does four jobs: attach the bearer token, validate the sport, cache responses, and return clean errors.

js
// server.js
import "dotenv/config";
import express from "express";
import { SPORTS, SPORT_SLUGS } from "./sports.js";
import { normalizeMatches } from "./normalize.js";

const app = express();
const BASE = "https://api.orbistats.com/v1";
const KEY = process.env.ORBISTATS_API_KEY;

if (!KEY) {
console.error("Missing ORBISTATS_API_KEY in .env");
process.exit(1);
}

// tiny in-memory cache
const cache = new Map();

async function orbistats(path, ttlMs = 30_000) {
const hit = cache.get(path);
if (hit && Date.now() - hit.at < ttlMs) return hit.data;

const res = await fetch(${BASE}${path}, {
headers: { Authorization: Bearer ${KEY}, Accept: "application/json" },
});

if (!res.ok) {
const err = new Error(Orbistats ${res.status} on ${path});
err.status = res.status;
throw err;
}

const data = await res.json();
cache.set(path, { at: Date.now(), data });
return data;
}

// validate :sport on every route
app.param("sport", (req, res, next, sport) => {
if (!SPORT_SLUGS.has(sport)) {
return res.status(404).json({ error: Unsupported sport: ${sport} });
}
next();
});

// routes
app.get("/api/sports", (_req, res) => res.json(SPORTS));

app.get("/api/:sport/live", async (req, res, next) => {
try {
const raw = await orbistats(/${req.params.sport}/matches/live, 15_000);
res.json(normalizeMatches(raw));
} catch (e) { next(e); }
});

app.get("/api/:sport/fixtures", async (req, res, next) => {
try {
const raw = await orbistats(/${req.params.sport}/fixtures, 300_000);
res.json(normalizeMatches(raw));
} catch (e) { next(e); }
});

app.get("/api/:sport/standings", async (req, res, next) => {
try {
res.json(await orbistats(/${req.params.sport}/standings, 600_000));
} catch (e) { next(e); }
});

// NOTE: confirm the exact odds path and params in the API reference.
app.get("/api/:sport/odds", async (req, res, next) => {
try {
const q = new URLSearchParams({ match_id: String(req.query.match_id || "") });
res.json(await orbistats(/${req.params.sport}/odds?${q}, 20_000));
} catch (e) { next(e); }
});

// error handler
app.use((err, _req, res, _next) => {
const status = err.status || 500;
const message =
status === 429 ? "Rate limit reached. Try again shortly." : err.message;
res.status(status).json({ error: message });
});

app.use(express.static("public"));
app.listen(process.env.PORT || 3000, () =>
console.log(Dashboard running on http://localhost:${process.env.PORT || 3000})
);

Notice the different cache lifetimes. Live scores get 15 seconds, fixtures get 5 minutes, standings get 10 minutes. Match your cache to how fast the data actually changes. This single habit will save you most of your request budget.

Step 4: One normalizer for 13 very different sports

Here's the part of multi-sport apps that usually hurts. A football match is Home vs Away. A tennis match is Player vs Player. A golf tournament has a field of 150 players. A horse race has runners. If your UI assumes every event has a home and an away, it will break on golf and horse racing on day one.

So we translate everything into a small UI-friendly shape in one place:

js
// normalize.js

// The live-scores sample on the Orbistats homepage looks like:
// { match_id, status, minute, home: { name, score }, away: { name, score } }
// Adjust the field names below to match the API reference for each sport.

function unwrap(raw) {
if (Array.isArray(raw)) return raw;
return raw?.data ?? raw?.matches ?? raw?.fixtures ?? raw?.results ?? [];
}

export function normalizeMatches(raw) {
return unwrap(raw).map((m) => {
const hasSides = m.home && m.away;

return {
  id: m.match_id ?? m.id,
  status: m.status ?? "scheduled",
  clock: m.minute != null ? `${m.minute}'` : (m.period ?? ""),
  kickoff: m.start_time ?? m.kickoff ?? null,
  title: hasSides
    ? `${m.home.name} vs ${m.away.name}`
    : (m.name ?? m.event_name ?? "Event"),
  home: hasSides ? { name: m.home.name, score: m.home.score ?? "-" } : null,
  away: hasSides ? { name: m.away.name, score: m.away.score ?? "-" } : null,
};

});
}

The UI can now render a "versus" card when home and away exist, and a simple event card when they don't (golf, horse racing, some combat sports cards). Every new sport becomes a small mapping change instead of a rewrite.

Step 5: The front-end dashboard

One HTML file. No build step.

html

<!doctype html>

Multi-Sport Dashboard
 :root { color-scheme: dark; } body { margin: 0; font-family: system-ui, sans-serif; background: rgb(11,18,32); color: rgb(232,238,252); } header { padding: 16px 24px; border-bottom: 1px solid rgb(31,42,68); } nav { display: flex; gap: 8px; flex-wrap: wrap; padding: 12px 24px; } nav button { background: rgb(20,29,51); color: inherit; border: 1px solid rgb(37,51,90); padding: 8px 12px; border-radius: 999px; cursor: pointer; } nav button.active { background: rgb(47,107,255); border-color: rgb(47,107,255); } main { display: grid; gap: 16px; padding: 24px; grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); } .card { background: rgb(20,29,51); border: 1px solid rgb(37,51,90); border-radius: 12px; padding: 14px; } .status { font-size: 12px; opacity: .7; text-transform: uppercase; } .live { color: rgb(255,91,91); opacity: 1; } .row { display: flex; justify-content: space-between; margin-top: 6px; } .note { padding: 0 24px; opacity: .7; }

🌍 Multi-Sport Dashboard

Run it:

bash
node server.js

Then open http://localhost:3000 in your browser.

Two details worth copying into your own projects.

We only poll the active tab. If you polled all 13 sports every 30 seconds you'd burn through a free tier in minutes. Fetch what the user is looking at, nothing more.

We use textContent, not innerHTML. Team names come from an external source. Treating them as text means you never have to think about injection.

Step 6: Add standings and odds

Standings are one more route away (we already built /api/:sport/standings). A simple loader:

js
async function showStandings(slug) {
const data = await getJSON(/api/${slug}/standings);
const rows = Array.isArray(data) ? data : (data.data ?? []);
console.table(rows.slice(0, 10)); // replace with your own table component
}

Odds are where a multi-sport API really earns its keep. Every bookmaker formats odds differently, and normally you'd write a separate parser for each one. The Odds API returns normalized markets in one consistent schema (1X2, moneyline, spreads, totals and more), so a market looks like this:

json
{
"market": "1X2",
"odds": { "home": 1.91, "draw": 3.40, "away": 4.20 }
}

A tiny helper turns those decimal odds into an implied probability, which is far more useful on a dashboard than a raw number:

js
// decimal odds to implied probability (percent)
export const implied = (odds) => +(100 / odds).toFixed(1);

const m = { home: 1.91, draw: 3.40, away: 4.20 };
const probs = Object.fromEntries(
Object.entries(m).map(([k, v]) => [k, implied(v)])
);
// { home: 52.4, draw: 29.4, away: 23.8 }

const overround = Object.values(probs).reduce((a, b) => a + b, 0);
// about 105.6, which is the bookmaker margin baked into the market

If the three probabilities add up to more than 100 percent, the extra is the bookmaker's margin. Showing that number is a cheap way to make your dashboard feel genuinely analytical.

A responsible note: odds data is for analytics, comparison and research. If you build anything that touches betting, check the licensing and legal rules for every market you serve.

Step 7: From polling to real time

Polling every 15 to 30 seconds is fine for a prototype. For genuinely live experiences, you want the server to push updates to you. Orbistats offers two ways.

Option A: WebSockets

A WebSocket is one persistent connection that stays open, so updates arrive the moment they happen instead of waiting for your next poll:

text
REST: request, response, request, response, ...
WebSocket: open once, update, update, update, ...

A minimal Node client skeleton (get the exact URL, subscription message and format from the WebSocket docs):

js
// realtime.js
import "dotenv/config";
import WebSocket from "ws"; // npm install ws

const ws = new WebSocket(process.env.ORBISTATS_WS_URL, {
headers: { Authorization: Bearer ${process.env.ORBISTATS_API_KEY} },
});

ws.on("open", () => {
// Subscribe using the message format from the WebSocket docs
ws.send(JSON.stringify({ action: "subscribe", sport: "football" }));
});

ws.on("message", (buf) => {
const event = JSON.parse(buf.toString());
console.log("update:", event);
// forward to browsers (see Server-Sent Events below)
});

ws.on("close", () => setTimeout(() => process.exit(1), 1000)); // let a supervisor restart

In production, add automatic reconnect with exponential backoff and re-subscribe on reconnect.

Option B: Webhooks

With Webhooks, Orbistats calls your server when something happens, for example a goal:

text
Goal scored -> Orbistats -> POST /webhook/sports -> your server -> your UI
js
app.post("/webhook/sports", express.json(), (req, res) => {
// 1. Verify the request is really from Orbistats (see the webhook docs)
// 2. Update your store or notify clients
console.log("event:", req.body);
res.sendStatus(200); // respond fast, do heavy work asynchronously
});

Webhooks are ideal for notifications and background jobs. WebSockets are ideal for live UI.

Getting pushes into the browser

Once your server receives real-time events, forward them to the dashboard with Server-Sent Events, which are much simpler than running a second WebSocket layer for the browser:

js
const clients = new Set();

app.get("/stream", (req, res) => {
res.set({
"Content-Type": "text/event-stream",
"Cache-Control": "no-cache",
Connection: "keep-alive",
});
res.flushHeaders();
clients.add(res);
req.on("close", () => clients.delete(res));
});

export function broadcast(event) {
for (const c of clients) c.write(data: ${JSON.stringify(event)}\n\n);
}
js
// in index.html
const es = new EventSource("/stream");
es.onmessage = (e) => { /* update the matching card */ };

Now each live card updates the moment a score changes, with no polling.

Step 8: Add history for charts and models

A dashboard that only shows "now" is a scoreboard. One that shows how we got here is a product. The Historical Sports Data API provides multi-season archives (fixtures, results, statistics, lineups, events and closing odds, with seasons going back as far as 2010 for covered data), which unlocks things like season form charts per team, head-to-head history on every match card, closing-odds comparisons, and datasets for backtesting and machine learning.

text
Historical data -> feature engineering -> model -> predictions -> your dashboard

If you want team and player numbers like possession, shots, goals, assists or xG on each match page, pair this with the Sports Statistics API.

Step 9: The shortcut, drop-in widgets

Sometimes you don't want to build the UI at all. If you're a publisher who just needs a live score box or a match center on an article page, Orbistats Widgets let you embed ready-made components instead of writing the front-end yourself. Build the custom dashboard where it differentiates your product, and use widgets everywhere else.

Staying inside your rate limits

This is where good multi-sport apps and sad multi-sport apps part ways. The docs list 150 requests per day on the Free plan, so treat requests as a budget.

Cache by data type (15 seconds for live, 5 to 10 minutes for standings), because most data doesn't change every second.
Poll only the active tab: one sport at a time, not 13.
Pause polling when the browser tab is hidden (document.hidden), so you don't make requests for nobody.
Use WebSockets or webhooks for live data, because one connection beats thousands of polls.
Handle 429 responses gracefully: show a friendly message, back off and retry.

The in-memory cache above also means that if ten users open the football tab at once, you make one upstream request, not ten.

Production checklist

Before you ship this beyond localhost:

Keep the API key in environment variables, never in front-end code.
Replace the in-memory cache with Redis if you run more than one server.
Add retry with exponential backoff for 5xx and 429 responses.
Verify webhook signatures.
Reconnect WebSockets automatically.
Pin to /v1/. Orbistats uses versioned paths, so breaking changes would ship under a new version rather than silently changing yours.
Check the status page and changelog as part of your monitoring routine.
Read the data licensing terms if you'll display data commercially.

Where to go next

Browse the full API reference and the SDKs if you'd rather not hand-roll fetch calls. Copy patterns from the examples page. Compare plans on the pricing page when you're ready for real-time production traffic.

A few ideas to extend this project:

Favorites: let users pin teams across sports and build a personal "my teams" feed.
Match center page: click a card to see events, lineups and stats.
Odds movement chart: poll odds and plot line movement over time.
Alerts: use webhooks to send a Telegram or email notification on goals and final results.
Sport-specific layouts: a leaderboard view for golf, a runner list for horse racing, a set-by-set view for tennis.

Wrapping up

The biggest lesson from building multi-sport products is that the hard part isn't the sports, it's the plumbing: auth, schemas, caching, rate limits and real-time delivery. When you get 13 sports from one API, one auth method and one schema, most of that plumbing disappears and you get to spend your time on the product.

You can grab a free API key here and have your first live scoreboard running in under an hour.

Over to you: which sport would you add first, and what's the weirdest edge case you've hit when mixing sports in one UI (I'm looking at you, golf)? Drop it in the comments. 👇

Getting Your First Orbistats API Key: A 5-Minute Quickstart Walkthrough

orbistats — Mon, 05 Oct 2026 12:58:29 +0000

Most "quickstart" guides skip the part that actually trips people up: where exactly to click, what the key looks like, where to put it, and what the very first error message means when you get it wrong. This is a genuinely five-minute walkthrough — sign up, get the key, make one real request, understand your limits, and know where to go next.

What You'll Need
Nothing but a terminal and five minutes
No credit card — Orbistats' free tier doesn't require one
Optional: Node.js or Python if you want to run the code examples instead of just curl
Step 1: Create a Free Account

Go to the sign-up page and create an account. This is a plain email/password-style signup, not a sales form — you land straight in a dashboard, not a "someone will contact you" queue, which is the main thing that separates a self-serve platform like Orbistats from enterprise-only providers in this space.

Once you're in, you'll have access to the login page for future sessions and a dashboard where your API key lives.

Step 2: Copy Your API Key

Your key will be a long alphanumeric string tied to your account's plan and rate limit. Copy it from the dashboard — but before you paste it anywhere, read this next part carefully, because it's the step almost every first-time tutorial gets wrong.

Don't Hardcode It

Never paste your key directly into a script you might commit to Git, share in a screenshot, or paste into a public gist. Store it as an environment variable instead:

macOS or Linux:

bash
export ORBISTATS_API_KEY="your_key_here"

Windows PowerShell:

powershell
$env:ORBISTATS_API_KEY = "your_key_here"

Or in a .env file (most projects use this for local dev):

bash

.env — add this file to .gitignore

ORBISTATS_API_KEY=your_key_here

This isn't a minor hygiene tip — a leaked key on a public GitHub repo gets scraped and abused within hours in practice across most API providers, and you'll find out when your quota is suddenly gone or your account gets flagged.

Step 3: Understand the Authentication Pattern

Orbistats uses a standard Bearer token in the Authorization header — the same pattern you'll recognize from most modern REST APIs:

Authorization: Bearer YOUR_API_KEY

That's it. No OAuth handshake, no signed-request complexity for basic REST calls. Full details live in the API documentation and the API reference if you want every endpoint's exact parameters.

Step 4: Make Your First Request

Here's the moment that matters — your first real call. We'll pull today's football fixtures:

bash
curl https://api.orbistats.com/v1/football/fixtures \
-H "Authorization: Bearer $ORBISTATS_API_KEY"

If everything's set up right, you'll get back JSON with fixture data — match IDs, team names, kickoff times, competition info. If you see a 401, your key or header is wrong; if you see a 403, double-check you're not accidentally sending an expired or revoked key.

Same Request in JavaScript
javascript
const API_KEY = process.env.ORBISTATS_API_KEY;

async function getFixtures() {
const res = await fetch("https://api.orbistats.com/v1/football/fixtures", {
headers: { Authorization: Bearer ${API_KEY} },
});

if (!res.ok) {
throw new Error(Request failed: ${res.status} ${res.statusText});
}

return res.json();
}

getFixtures().then(console.log).catch(console.error);
Same Request in Python
python
import os
import requests

API_KEY = os.environ["ORBISTATS_API_KEY"]

response = requests.get(
"https://api.orbistats.com/v1/football/fixtures",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=10,
)
response.raise_for_status()
print(response.json())

Three languages, same shape: set a header, hit a URL, read JSON back. That consistency is deliberate — Orbistats documents the same /v1/{sport}/{resource} pattern across every sport it covers.

Step 5: Try a Different Sport (Same Shape, Different Path)

This is where the consistent schema actually pays off. Want basketball instead of football? Change one path segment:

bash
curl https://api.orbistats.com/v1/basketball/fixtures \
-H "Authorization: Bearer $ORBISTATS_API_KEY"

Orbistats currently documents coverage across 13 sports: Football, Basketball, American Football, Cricket, Tennis, Baseball, Esports, Combat Sports, Volleyball, Handball, Ice Hockey, Golf and Horse Racing. Each has its own sport landing page listing coverage specifics, and the same resource pattern (fixtures, results, standings, odds, statistics) applies across all of them, with sport-specific data models underneath.

Step 6: Know Your Rate Limit Before You Build Anything

This is the step that saves you a frustrating afternoon later. The free tier has a daily request cap — Orbistats' documentation has described it as roughly 150 requests per day, though you should always check the live pricing page for the current number, since limits and tiers do get revised.

Do the math before you design a feature:

python
def requests_per_day_needed(poll_interval_seconds: int, hours_active: int = 24) -> int:
return (hours_active * 3600) // poll_interval_seconds

Polling every 30 seconds, all day

print(requests_per_day_needed(30)) # 2,880 — way over a 150/day free tier

If your use case needs anything close to live polling, the free tier's daily cap will not get you there — that's exactly what the WebSocket API and Webhooks API exist for, both of which push updates instead of making you poll. Paid tiers (Starter at $19/month, Growth at $79/month per the last published pricing — verify current numbers) raise the daily request ceiling and unlock real-time data, history and streaming delivery.

Step 7: Explore Without Spending a Request

Before you wire the API into real code, it's worth seeing what other endpoints actually return. The public sandbox lets you pick an endpoint, set parameters, and inspect a real JSON response — no signup or key required for that part, which makes it the fastest way to check a response shape before you write code around it.

For a wider tour of what's available beyond fixtures — odds, live scores, statistics, historical data — the documentation hub and quickstart page are the next stop, and worked examples cover common integration patterns end to end.

What People Usually Build First

A few common starting points once the key is working:

A live scoreboard — fixtures plus live scores, often upgraded to WebSocket once polling gets expensive. I covered the full build in Build a Live Sports Scoreboard in 50 Lines of JavaScript with a WebSocket API.
An odds comparison tool — pulling from the Odds API, which returns normalized pricing across bookmakers instead of raw per-book formats.
A fantasy or stats dashboard — built off fixtures plus team/player statistics.
A backtest or research script — using the Historical Sports Data API instead of live endpoints.

If you're still deciding between REST polling and real-time delivery for your use case, REST API vs WebSocket: What's the Difference? (With Code) walks through the tradeoff in more detail, and Sports APIs Explained: How to Get Live Match Data is a good companion piece if you're brand new to sports APIs generally.

Common First-Request Errors and Fixes
Error Likely cause Fix
401 Unauthorized Missing or malformed Authorization header Confirm it's exactly Bearer YOUR_KEY, no extra quotes
403 Forbidden Key revoked, expired, or wrong plan for that endpoint Check your dashboard, regenerate if needed
429 Too Many Requests Daily/rate limit hit Check remaining quota, implement caching
Empty response body Wrong sport/resource path Compare against the API reference
Works in curl, fails in code Env var not actually loaded echo $ORBISTATS_API_KEY to confirm it's set in that shell/process
Checklist Before You Build Anything Real
Key stored as an environment variable, never hardcoded or committed
First request confirmed working via curl before writing application code
You know your daily/rate limit and have roughly calculated your usage pattern against it
You've checked whether your use case needs WebSocket/webhooks instead of REST polling
You've looked at the sandbox to see response shapes for endpoints beyond fixtures
You've read the current pricing page rather than assuming last month's numbers still apply
Where to Go Next

Once your first request works, the natural next steps are: pick a real feature to build (scoreboard, odds tool, stats dashboard), decide REST vs. WebSocket/webhooks based on how live you need the data, and keep an eye on the changelog and status page as you move toward production. The developer hub is the single best bookmark for everything covered here.

Wrapping Up

Five minutes, three steps that actually matter: sign up, store the key safely, make one request to confirm it works. Everything after that — which sport, which resource, REST or WebSocket — is a decision you can make once you've actually seen real data come back, not before. If you hit an error that isn't in the table above, drop it in the comments and I'll help debug it.