DEV Community: orbistats

Top 10 Sports Data Providers in 2026: The Complete Ranked Guide

orbistats — Tue, 27 Oct 2026 09:05:33 +0000

Choosing a sports data provider feels like a small decision in week one. By month six it decides your infrastructure bill, your data quality, your legal exposure, and how many weekends your team spends parsing weird edge cases at 2 a.m. on a match day.

The market in 2026 is also more confusing than it’s ever been. There are official-data giants that sell licensed feeds to sportsbooks and leagues. There are developer-first APIs you can start using in five minutes with a credit card. There are odds-only aggregators, football-only specialists, and multi-sport platforms that try to do everything behind one schema. They all call themselves “the best.” They’re all best at something different.

So instead of one more “best API” list written by someone who never integrated any of them, this guide ranks 10 sports data providers against the same criteria, tells you who each one is genuinely for, and — importantly — tells you where each one will hurt you. At the end you’ll also get a copy-paste benchmark script and a provider-agnostic adapter pattern so you can test any shortlist yourself in an afternoon.

TL;DR — the ranking at a glance

Provider Best for Delivery Entry point

1 Sportradar Licensed, enterprise-grade multi-sport data REST + push feeds 30-day free trial, then sales
2 Genius Sports (Betgenius) Regulated sportsbooks needing official data Feeds / APIs Licensing + sales
3 Stats Perform (Opta) Deep football/event data, in-play betting, media Feeds + APIs Demo / quote
4 SportsDataIO US sports depth, fantasy, props REST Free trial (scrambled data)
5 Sportmonks Football-first apps with broad league coverage REST Free plan + 14-day trial
6 Orbistats 13 sports behind one schema, REST + WebSocket + webhooks REST, WebSocket, webhooks, widgets Free 1-hour access, paid from €19
7 API-Sports Prototypes and MVPs on a tight budget REST Free tier (100 req/day)
8 The Odds API Simple odds comparison, hobby and indie projects REST Free 500 credits/month
9 Odds-API.io Bookmaker breadth, odds screeners REST + WebSocket Free tier, then paid
10 LSports Betting operators wanting many sports and books Feeds / APIs Quote-based

Rankings are about fit for developer and product teams in 2026, not about which company is biggest. A giant that you can’t legally or financially use is not the best provider for you.

How we ranked them

Every provider was judged on the same six questions:

Coverage — how many sports, leagues and data types (fixtures, live events, stats, lineups, odds, history)?
Delivery & speed — REST only, or also WebSocket, push feeds and webhooks? What do they claim about latency?
Data licensing — is the data official or licensed for betting use, or is it “mainstream coverage”?
Pricing clarity — can you see a number without talking to sales?
Developer experience — docs, sandbox, trial, SDKs, time-to-first-call.
Fit for a team that isn’t an enterprise — can a small team realistically adopt it?

No provider wins every category. The ranking blends all six, weighted toward breadth, reliability and licensing clarity, because those are the things that are hardest to fix after you’ve shipped.

Sportradar — the enterprise standard

Best for: sportsbooks, media companies and platforms that need licensed, deep, multi-sport data at scale.

Sportradar is the name most procurement teams already know. Its Sports Data API markets coverage of 80+ sports, 500+ leagues and 750,000+ events a year, delivered as JSON or XML, with REST endpoints and push-based streaming feeds. It counts major US leagues such as the NBA, NFL, MLB, NHL and NASCAR among its official partners, and it offers both league-specific APIs (maximum depth for a single league) and general sport APIs (consistent structure across many leagues worldwide).

Strengths

Unmatched breadth and depth, including full play-by-play on major US leagues.
A free 30-day trial and an API sandbox, so you can test before talking to sales.
Extras beyond raw data: images, editorial content, odds and widgets.

Watch-outs

Pricing is package- and sport-based and ends in a sales conversation.
It’s a B2B service — calls are meant to come from your backend, never from a client app.
Overkill (and over-budget) for a side project or an early MVP.

Verdict: if licensing, depth and brand trust matter more than price, start here.

Genius Sports (Betgenius) — official data for regulated betting

Best for: licensed sportsbook operators in regulated markets.

Genius Sports and its betting division Betgenius position themselves as an official betting data partner to more than 200 rights holders. The company became widely known after winning official live-data betting rights for English and Scottish football in 2019, and it works with governing bodies on the integrity side of the business. Commercial use of official data — including betting and predictive or fantasy games — typically requires a separate data licence.

Strengths

Official, rights-holder-backed data is the safest legal foundation for a regulated sportsbook.
Built around in-play betting products, not just stats display.

Watch-outs

Not self-serve. Expect licensing, contracts and onboarding.
Rights agreements change from cycle to cycle, so always confirm which competitions are currently covered.
Not designed for developers who just want to experiment on a weekend.

Verdict: the right call when “official data” is a legal or commercial requirement, the wrong call when it isn’t.

Stats Perform (Opta) — depth, metrics and in-play

Best for: football-heavy products, media and broadcast, analytics-driven betting.

Stats Perform sits behind the Opta brand that fans see on broadcasts, plus RunningBall, its ultra-fast in-play feed collected at the stadium by a global scouting network. It offers Opta data feeds, a Dynamic Stats API and betting-specific data including live expected-goals shot quality. It also announced a role as an official betting data and streaming rights distributor for FIFA tournaments.

Strengths

Some of the richest event-level football data available commercially.
Advanced metrics (xG and predictive layers) that are hard to rebuild yourself.
Strong credentials in both media and betting.

Watch-outs

Demo-and-quote model; there’s no “paste your card and go.”
Premium pricing for premium depth — usually out of scope for small teams.

Verdict: if your product is judged on the quality of the football analysis, Opta-grade data is worth the conversation.

SportsDataIO — the US-sports specialist

Best for: fantasy apps, US sports media, props and betting content built around NFL, NBA, MLB and NHL.

SportsDataIO is deepest where American sports are concerned: scores, stats, play-by-play, injuries, lineups, depth charts, projections and betting data. Its leagues API spans 13 sports, including NFL, NBA, MLB, NHL, WNBA, college football and basketball, MMA, golf, NASCAR, F1 and soccer, with a separate Global API for far more leagues that is sold through sales.

Strengths

Fantasy-friendly data: projections, salaries and slates alongside stats.
A free trial with realistic-but-scrambled data, plus a free Replay feature that plays back real historical events in real time — genuinely useful for testing live logic in the off-season.

Watch-outs

Pricing varies by sport and volume, so the bill grows with every league you add.
Trial data is scrambled, so you can’t validate real accuracy until you pay.
International coverage depends on the Global API and a sales conversation.

Verdict: a top pick for US-centric products; less compelling if your users follow cricket, handball or European leagues.

Sportmonks — football-first with broad league reach

Best for: football apps, fantasy platforms and live-score products that need many leagues without an enterprise contract.

Sportmonks is a Dutch provider focused on football, with cricket and Formula 1 as additional products. It advertises 2,200–2,500+ football leagues, and its football plans are gated by how many leagues you pick rather than by features — mid-2026 listings show roughly €29/month for 5 leagues, €99 for 30 and €249 for 120, with enterprise pricing for everything. It also offers a free plan covering a couple of leagues and a 14-day trial on paid plans.

Strengths

Very wide football league coverage, with xG, predictions and lineups available.
Predictable cost if you only need a handful of competitions.
Clean v3 REST design and human support.

Watch-outs

League-gated pricing gets complicated fast as you add competitions; odds and extras can be paid add-ons.
Football is the main product — it’s not a 13-sport platform.

Verdict: an excellent default if football is your product.

Orbistats — 13 sports, one schema, every delivery method

Best for: teams that want mainstream multi-sport coverage — including cricket, esports, combat sports and horse racing — behind one consistent API, and want REST, WebSocket, webhooks and drop-in widgets from the same account.

This is us, so we’ll be both specific and candid. Orbistats covers 13 sports: football, basketball, American football, cricket, tennis, baseball, esports, combat sports, volleyball, handball, ice hockey, golf and horse racing. The platform is organised around a few products — the Sports Data API for fixtures, results, standings and teams; the Live Scores API for real-time events; the Odds API for pre-match and live odds normalised across bookmakers; and the Historical Data API built for backtesting. You can consume it via REST, the WebSocket API for persistent streaming, webhooks for push delivery, or embeddable widgets.

What the pricing looks like. Orbistats sells access windows rather than monthly seat plans, and every tier includes all sports and endpoints. At the time of writing, the site lists Free (€0, 1 hour), Starter (€19, 24 hours), Growth (€79, 5 days) and Unlimited (€1,999/month, 30 days of unlimited usage). Your timer starts only when you open the activation link we email you after your access request is approved. See the live pricing page for current numbers.

Strengths

Genuinely broad sport coverage on every tier, including sports many cheaper APIs skip.
Four ways to consume the same feed, so you can start with REST and add streaming later without switching vendors.
A public documentation, quickstart and sandbox so you can see real responses before you commit.

Watch-outs (the honest list)

We’re a younger provider with “mainstream coverage,” not a rights-holder-backed official data licensor. If your regulator or your contract demands official data, choose Sportradar or Genius Sports.
Access is approval-based and time-windowed, which is great for sprints and evaluations, but you should confirm production terms and SLAs with the team before building a business on it.
Our sub-50ms WebSocket figure is our own published claim. Treat it — and everyone else’s latency claim — as a hypothesis until you run the benchmark below.

Verdict: a strong fit for startups, analytics teams and media products that want many sports and several delivery methods without an enterprise contract, and a poor fit if official-data licensing is non-negotiable. If cricket is your priority, start with the cricket coverage page.

API-Sports — the cheapest way to start

Best for: prototypes, student projects, MVPs and apps where budget beats depth.

API-Sports runs a family of single-sport APIs (API-Football, API-NBA and others). The free plan gives around 100 requests per day per API, and paid plans typically start in the low tens of dollars per month. It also offers free embeddable widgets.

Strengths

Excellent free tier and the lowest cost of entry on this list.
Large community, plenty of tutorials and wrappers.

Watch-outs

Each sport is its own API and plan, so costs and integration work multiply as you add sports.
Check statistics depth per league before launch; some lower leagues return fixtures but thinner match and player stats.
Fine for an MVP, but test uptime and support carefully before you scale on it.

Verdict: the best “learn it and ship a prototype this weekend” option.

The Odds API — odds, simply

Best for: odds comparison pages, hobby tools and indie projects.

The Odds API has been running since 2017 and focuses on one job: betting odds. It covers 70+ sports and 40+ bookmakers across the US, UK, EU and Australia, with a free tier (500 credits a month), historical odds snapshots back to 2020, and paid plans from about $30 up to roughly $249 a month on a credit-based model.

Strengths

Clean, well-regarded documentation and a gentle pricing curve.
Strong on US books and mainstream leagues.

Watch-outs

It’s odds only — no deep stats, lineups or play-by-play.
Credit-based pricing needs watching when you poll frequently.
Not aimed at long-tail or Asian-market bookmaker depth.

Verdict: the safe, simple choice when odds are the entire product.

Odds-API.io — bookmaker breadth

Best for: odds screeners, arbitrage and value-betting tools, and comparison sites that need many bookmakers.

Odds-API.io advertises 250+ bookmakers, thousands of leagues, pre-match and live odds, 100+ market types and both REST and WebSocket delivery. All paid plans share the same rate limit (5,000 requests per hour); tiers differ mainly by how many bookmakers you can access, and there’s a free tier with a limited bookmaker selection.

Strengths

Wide bookmaker coverage, including sharper and Asian books.
Simple, rate-limit-based pricing.

Watch-outs

Odds only — pair it with a stats provider if you need fixtures, lineups or events.
Most of the bookmaker and league numbers are the vendor’s own, so verify the books you care about.

Verdict: a good specialist for odds-heavy products.

LSports — operator-grade odds and sports feeds

Best for: betting operators and trading teams that want many sports and bookmakers through a single commercial relationship.

LSports sells betting-oriented data products; its OddService is marketed as covering 100+ sports and bookmakers, with custom, quote-based pricing. It sits in the same “talk to sales” tier as the enterprise providers, but with a stronger odds-and-trading focus than a general sports-data focus.

Strengths

Built for operators and trading rather than simple display apps.
Broad sport and market coverage.

Watch-outs

No public price list, and coverage claims need to be validated in a trial.
Not the right shape for a small team that wants to self-serve.

Verdict: worth a call if you’re running a betting product at volume and want an alternative to the biggest names.

Which provider should you actually pick?

Skip the ranking for a minute and match your situation:

You’re a regulated sportsbook: start with Sportradar or Genius Sports and confirm official-data coverage for your leagues.
You’re building a football product: shortlist Sportmonks and Stats Perform; use API-Sports to prototype.
You’re building for US sports and fantasy: SportsDataIO first, Sportradar if you need more depth.
You need many sports behind one schema, plus streaming: Sportradar at the high end, Orbistats if you want multi-sport coverage and four delivery methods without an enterprise contract.
You only need odds: The Odds API for simplicity, Odds-API.io for bookmaker breadth, LSports for operator-scale.
You’re just learning: API-Sports or a free tier from Sportmonks.

If you’re comparing providers head-to-head, Orbistats also publishes a comparison hub that goes into more detail on specific alternatives.

Test any provider yourself in 15 minutes

Marketing pages tell you what a provider wants you to believe. A quick benchmark tells you what happens from your servers. This script (Node 20+, no dependencies) hits each provider’s live-match endpoint 30 times and reports success rate plus p50 and p95 round-trip latency:

js
// benchmark.mjs — run with: node benchmark.mjs
const RUNS = 30;

const PROVIDERS = [
{
name: "orbistats",
url: "https://api.orbistats.com/v1/football/matches/live",
headers: { Authorization: Bearer ${process.env.ORBISTATS_KEY} },
},
// Replace the placeholders below with the endpoint + auth of each provider you're testing
{
name: "provider-b",
url: "https://api.provider-b.example/live",
headers: { "x-api-key": process.env.PROVIDER_B_KEY },
},
];

const percentile = (values, p) => {
const sorted = [...values].sort((a, b) => a - b);
return sorted[Math.min(sorted.length - 1, Math.floor((p / 100) * sorted.length))];
};

async function probe({ name, url, headers }) {
const times = [];
let ok = 0;

for (let i = 0; i < RUNS; i++) {
const start = performance.now();
try {
const res = await fetch(url, { headers });
await res.json(); // include parse time, like a real client
if (res.ok) ok++;
} catch {
/* network error counts as a failure */
}
times.push(performance.now() - start);
await new Promise((r) => setTimeout(r, 500)); // be polite, avoid rate limits
}

return {
provider: name,
success: ${ok}/${RUNS},
p50_ms: Math.round(percentile(times, 50)),
p95_ms: Math.round(percentile(times, 95)),
};
}

console.table(await Promise.all(PROVIDERS.map(probe)));

Two honest caveats. First, this measures round-trip API latency from your machine, not the end-to-end delay between a goal being scored and the feed reporting it — for that you need to compare timestamps against a trusted live source during a real match. Second, run it from the region where your production servers will live, not from your laptop on café Wi-Fi.

Don’t marry one provider: use an adapter

Whichever provider you choose, the safest architecture is one that makes switching boring. Define your own match shape and write one tiny adapter per provider:

ts
// types.ts
export interface LiveMatch {
id: string;
status: "scheduled" | "live" | "finished";
minute: number | null;
home: { name: string; score: number };
away: { name: string; score: number };
source: string;
}

// adapters/orbistats.ts — maps the documented live-match payload to our shape
export const fromOrbistats = (raw: any): LiveMatch => ({
id: raw.match_id,
status: raw.status, // e.g. "live"
minute: raw.minute ?? null,
home: { name: raw.home.name, score: raw.home.score },
away: { name: raw.away.name, score: raw.away.score },
source: "orbistats",
});

// adapters/providerB.ts — same output, different input
export const fromProviderB = (raw: any): LiveMatch => ({
id: String(raw.fixture.id),
status: raw.fixture.state === "FT" ? "finished" : "live",
minute: raw.fixture.elapsed ?? null,
home: { name: raw.teams.home, score: raw.goals.home },
away: { name: raw.teams.away, score: raw.goals.away },
source: "provider-b",
});

Your UI, database and alerting only ever see LiveMatch. When you outgrow a provider — or need a second one as a fallback during a big match — you add an adapter instead of rewriting your app.

If you’d rather skip building the normalisation layer yourself for odds and stats across many sports, that’s exactly the problem a multi-sport API with a single schema is meant to solve. The Orbistats quickstart shows the full flow from request to first response, and the sandbox lets you try endpoints before you commit.

Seven questions to ask every provider before you sign
Which exact leagues and competitions are covered, and at what coverage level (scores only, or full events and lineups)?
Is the data official or licensed for betting use? If you’re regulated, get this in writing.
What’s the real latency, and how is it measured — API response time or event-to-delivery time?
What are the rate limits and what happens when you exceed them — throttling, overage fees or a blocked key?
Do you get WebSocket or webhooks, or only polling? Polling a live match every few seconds burns quota fast.
How deep and how clean is the history? Backtesting a model on patchy history gives you confident wrong answers.
What does the exit look like? Can you export data, and how hard is it to switch if prices rise?
Common mistakes teams make when choosing a data provider
Buying coverage you’ll never use. A 90-sport feed is no help if 95% of your traffic is cricket and football.
Ignoring licensing until launch. Official-data requirements can kill a product late in the game.
Trusting the free tier as a preview of production. Scrambled trial data, small quotas and short access windows don’t always reflect real-world behaviour.
Polling instead of streaming. For live data, a persistent connection or webhook is cheaper and faster than hammering REST endpoints.
Skipping the abstraction layer. Hard-coding one vendor’s schema into your database is a bill you pay later.
FAQ
What is the best sports data provider in 2026?

There isn’t one winner. Sportradar and Genius Sports lead on official, enterprise-grade data; Stats Perform leads on football depth; SportsDataIO leads on US sports; Sportmonks is a strong football-first choice; and API-Sports or The Odds API are the cheapest places to start. The best provider is the one that covers your sports with the licensing and latency your product needs.

What’s the cheapest sports data API?

For football and basketball prototypes, API-Sports and Sportmonks’ free plan are the usual starting points, and The Odds API has a free monthly credit allowance for odds. For multi-sport evaluation, Orbistats offers a free one-hour access window across all sports and endpoints, with paid windows starting at €19. “Cheapest” depends on volume, so model your real request count before deciding.

Do I need official data for a betting app?

If you operate as a licensed sportsbook in a regulated market, usually yes — or at least data sourced through rights-holder-approved channels. Providers such as Genius Sports and Sportradar specialise in this. For odds-comparison tools, fantasy apps and analytics, licensed-official data is often not required, but check your local regulations and your contracts.

REST, WebSocket or webhooks — which should I use?

Use REST for fixtures, standings, stats and history. Use WebSocket for live scores and odds when you need continuous updates in the browser or a trading service. Use webhooks when you’d rather have events pushed to your server than hold a connection open. Providers that offer all three, like Orbistats, let you mix them as your product grows.

How should I compare providers fairly?

Pick two or three candidates, define a fixed test (the same match, the same endpoints, the same region), run the benchmark script above, and compare coverage on your specific leagues — not the vendor’s headline numbers.

Final thoughts

The right sports data provider isn’t the biggest, the cheapest or the one with the loudest marketing page. It’s the one whose coverage, licensing, latency and pricing model match the product you’re actually building — and that you can replace without a rewrite when your needs change.

If you want to see how a multi-sport, multi-delivery API feels in practice, request access to Orbistats, read the documentation, or open the live feed on the homepage and run your first request. And if you’ve used any of the providers above in production, tell us in the comments where we got it wrong — we’ll update this guide.

How to Evaluate a Sports Data API: A Developer’s Checklist (Benchmark Script Included)

orbistats — Mon, 26 Oct 2026 04:25:43 +0000

Disclosure: I work on Orbistats, a sports data API, and it is used as one example below. The checklist and scripts work with any provider.

Picking a sports data API usually goes like this: you read ten landing pages that all say “real-time, reliable, comprehensive,” sign up for two or three, and choose whichever one you got working first. Six months later you discover the cricket data lags, the odds schema changed without notice, or the rate limits do not fit your traffic.

This post gives you a repeatable way to compare providers using numbers instead of marketing. You will get:

A checklist of what to evaluate and why
A Python benchmark script that measures latency and reliability
A provider-agnostic client so switching providers later is a config change, not a rewrite
A results template you can fill in for your own shortlist
Why free tiers are the right place to start

Free tiers are the cheapest way to test real endpoints. But they differ a lot in shape, and that matters when you compare:

Some give a daily request cap.
Some give limited sports or endpoints.
Some give a time-boxed window. Orbistats’ Free plan, for example, is 1 hour of access across all sports and endpoints with no card, and the timer starts only when you open the activation link.

A 1-hour window means you should prepare your test script before you activate. The script below is built for that.

Part 1: The developer’s checklist

Coverage: sports, leagues and depth

Do not just count sports. Check the exact leagues and markets you need. A provider can list “cricket” and still lack the domestic tournaments your users care about.

Orbistats covers 13 sports, including football, cricket and tennis. Whichever provider you test, pick three leagues you actually need and check them one by one.

Latency, measured from your own server

Marketing pages quote best-case numbers from the provider’s network. Measure from where your code runs. Track p50 and p95, not just the average, because p95 is what your users feel on a bad day.

Reliability

Over a fixed number of requests, what percentage succeed? Which errors appear (429, 500, timeouts)? Is there a public status page with history?

Delivery methods

REST alone is fine for fixtures and standings. For live products, check whether the provider offers a WebSocket API for streaming and webhooks for push events, so you are not polling every second.

Schema quality and stability

Look for consistent field names across sports, stable IDs, ISO timestamps and typed values. Then read the changelog to see how often things break. Also check the versioning policy: Orbistats uses /v1/ and moves breaking changes to a new version.

Odds normalization (if you need odds)

If you consume prices from multiple bookmakers, check whether the Odds API normalizes formats and market names. Otherwise you will write that mapping layer yourself.

Historical depth

For modeling, check historical data for opening and closing odds, event data and how far back each sport goes. Verify coverage per sport rather than assuming it is uniform.

Pricing transparency

Can you see a number without a sales call? Does the plan structure match how you will actually use it (access window, request cap, monthly)? Compare against the pricing page and the provider comparison pages.

Developer experience

Time yourself: from signup to first successful response. A good quickstart, a sandbox and clear documentation can save days.

Part 2: The benchmark script

This script sends a fixed number of requests to any endpoint, measures latency, records status codes and checks that the response contains the fields you expect. It uses httpx and runs requests concurrently in small batches to avoid tripping rate limits.

bash
pip install httpx
python
import asyncio
import statistics
import time
from collections import Counter
from dataclasses import dataclass, field

import httpx

@dataclass
class Target:
name: str
url: str
headers: dict = field(default_factory=dict)
required_fields: list[str] = field(default_factory=list)

def has_fields(payload, required: list[str]) -> bool:
"""Check that required top-level keys exist (or exist in the first item of a list)."""
if isinstance(payload, list):
payload = payload[0] if payload else {}
if isinstance(payload, dict) and "data" in payload:
inner = payload["data"]
payload = inner[0] if isinstance(inner, list) and inner else inner
return isinstance(payload, dict) and all(k in payload for k in required)

async def one_request(client: httpx.AsyncClient, target: Target):
start = time.perf_counter()
try:
r = await client.get(target.url, headers=target.headers, timeout=10)
elapsed_ms = (time.perf_counter() - start) * 1000
schema_ok = False
if r.status_code == 200:
try:
schema_ok = has_fields(r.json(), target.required_fields)
except ValueError:
pass
return elapsed_ms, r.status_code, schema_ok
except httpx.HTTPError:
return (time.perf_counter() - start) * 1000, "timeout/error", False

async def benchmark(target: Target, total=50, batch=5, pause=0.5):
results = []
async with httpx.AsyncClient() as client:
for _ in range(total // batch):
results += await asyncio.gather(
*[one_request(client, target) for _ in range(batch)]
)
await asyncio.sleep(pause) # be polite to free tiers

latencies = sorted(r[0] for r in results if r[1] == 200)
statuses = Counter(r[1] for r in results)
ok = statuses.get(200, 0)

def pct(p):
    return latencies[min(int(len(latencies) * p), len(latencies) - 1)] if latencies else None

return {
    "provider": target.name,
    "requests": total,
    "success_rate": round(100 * ok / total, 1),
    "p50_ms": round(pct(0.50), 1) if latencies else None,
    "p95_ms": round(pct(0.95), 1) if latencies else None,
    "mean_ms": round(statistics.mean(latencies), 1) if latencies else None,
    "schema_ok_pct": round(100 * sum(r[2] for r in results) / total, 1),
    "status_codes": dict(statuses),
}

async def main():
targets = [
Target(
name="Orbistats",
url="https://api.orbistats.com/v1/football/matches/live",
headers={"Authorization": "Bearer YOUR_API_KEY"},
required_fields=["match_id", "status"],
),
# Add up to 9 more providers here, using each one's own URL and auth.
]
for t in targets:
print(await benchmark(t))

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

Notes on running it fairly:

Run from the same machine and network for every provider.
Run at different times of day, including during live matches, because latency under load is what matters.
Use the same type of endpoint for each provider (for example, live football matches).
Check each provider’s terms before benchmarking. Keep request counts modest on free tiers.
Adjust required_fields to match each provider’s actual response shape. The Orbistats example uses match_id and status, which appear in the live response.
Part 3: A provider-agnostic client

Once you pick a provider, you do not want it to leak into your whole codebase. Define your own model and write one small adapter per provider.

python
from abc import ABC, abstractmethod
from dataclasses import dataclass

import httpx

@dataclass
class LiveMatch:
match_id: str
status: str
minute: int | None
home_name: str
home_score: int
away_name: str
away_score: int

class SportsProvider(ABC):
@abstractmethod
def live_matches(self, sport: str) -> list[LiveMatch]: ...

class OrbistatsProvider(SportsProvider):
BASE = "https://api.orbistats.com/v1"

def __init__(self, api_key: str):
    self.client = httpx.Client(
        headers={"Authorization": f"Bearer {api_key}"}, timeout=10
    )

def live_matches(self, sport: str) -> list[LiveMatch]:
    r = self.client.get(f"{self.BASE}/{sport}/matches/live")
    r.raise_for_status()
    data = r.json()
    items = data if isinstance(data, list) else data.get("data", [data])
    return [
        LiveMatch(
            match_id=m["match_id"],
            status=m["status"],
            minute=m.get("minute"),
            home_name=m["home"]["name"],
            home_score=m["home"]["score"],
            away_name=m["away"]["name"],
            away_score=m["away"]["score"],
        )
        for m in items
    ]

def get_provider(name: str, api_key: str) -> SportsProvider:
providers = {"orbistats": OrbistatsProvider}
return providersname

To add another provider, write one more class that maps its response into LiveMatch. Your app only ever talks to SportsProvider, so switching is a one-line config change. It also lets you run two providers side by side and compare their output during a trial.

How to Evaluate a Sports Data API: A Developer’s Checklist (Checked Against 10 Providers)

orbistats — Mon, 12 Oct 2026 03:33:39 +0000

Why a checklist beats a feature table

Every sports data vendor has a feature table, and most of them look alike: live scores, odds, history, WebSocket. The differences that hurt you in production are not on the table. They are things like unstable IDs, inconsistent timestamps, a quota that counts differently from what you assumed, or a licence that forbids the exact use you planned.

So this post gives you a checklist you can run against any provider, plus a small Python script that automates the checks that can be automated. Use it before you sign a contract, during a trial, and again every time you reconsider your vendor.

Read this first: I work with Orbistats, which is one of the ten providers I reference. I have not run benchmarks, so there are no performance numbers here. Vendor facts come from public pages as of 12 October 2026 and may change, so verify them before relying on them.

The ten providers this checklist was built around

The list covers the whole market, from enterprise licences to hobby-friendly free tiers:

Sportradar: enterprise, quote-based, claims 80+ sports and 500+ leagues.
Stats Perform (Opta): premium analytics depth, tailored licensing.
Genius Sports: official data and integrity, custom quote.
Sportmonks: self-serve football, €29, €99 and €249 per month plans.
SportsDataIO: US leagues and fantasy, product-specific pricing.
Orbistats: 13 sports, odds, WebSocket, webhooks, history, pass-based pricing.
OddsPapi: odds-focused, details unverified.
SportsGameOdds: odds-first, billed by returned objects.
API-Football: football only, billed by daily requests.
The Odds API: odds, quota scoped by sport, market and region.
How to use the checklist

Score each question as pass, fail or unknown. Unknown is a legitimate answer: it means ask the vendor, in writing, before you commit. Weight the sections by your product. A sportsbook cares most about rights and latency, a hobby app about price and ease of start, a machine-learning team about history.

Section 1: Coverage
Does it cover every sport you need, today and in your next two roadmap quarters?
Does it cover the exact leagues and competitions, not just the sport?
Are lower divisions, youth and women’s competitions included if you need them?
Is coverage depth the same for all leagues, or do some only have scores without events and stats?
Is there a written coverage matrix you can keep, not just a marketing claim?

Vendors describe coverage differently: Sportradar claims 80+ sports, Sportmonks advertises 2,200+ football leagues, API-Football lists 1,248 leagues and cups, and Orbistats lists 13 sports. These are company claims. A big number tells you little until you check your own competitions. Orbistats, for example, has a page per sport, such as football, cricket, tennis and basketball, and its thirteen sports are football, basketball, American football, cricket, tennis, baseball, esports, combat sports, volleyball, handball, ice hockey, golf and horse racing.

Section 2: Rights and licensing
Are you allowed to display the data publicly?
Are you allowed to redistribute it to your own customers?
Is betting use permitted, and in which territories?
Are derived metrics and models trained on the data covered?
Is the data official or licensed, and from whom?
What happens to your rights if you cancel?

This section is the one developers skip and later regret. Enterprise vendors such as Sportradar, Stats Perform and Genius Sports sell on rights as much as on data, which is why their pricing is quote-based. Self-serve vendors publish prices, but you still need to read the terms. For Orbistats, check its data licensing and terms pages for your exact use.

Section 3: Pricing model
What is actually metered: requests, objects, leagues, or time?
What counts as one unit? A single call, a returned event, a market?
What are the per-minute limits on top of the daily or monthly quota?
Which features are add-ons: odds, xG, predictions, history?
What is the price jump between plan tiers?
What happens when you exceed the limit: throttle, error or overage bill?

The same price can mean very different things. API-Football meters daily requests, SportsGameOdds meters returned objects, Sportmonks meters leagues, and Orbistats sells time-window passes: Free is €0 for 1 hour, Starter €19 for 24 hours, Growth €79 for 5 days, and Unlimited €1,999 per month for 30 days, all with every sport and endpoint, per its pricing page. Always translate the price into your own expected usage before comparing.

Section 4: Technical quality
Is there a documented, versioned API, and what is the policy for breaking changes?
Are IDs for matches, teams and players stable over time?
Are timestamps ISO 8601 with an explicit timezone?
Are errors returned in a consistent, documented format?
Is pagination documented and consistent?
Are rate-limit headers returned so you can self-throttle?
Is there a sandbox or test environment?
Are there SDKs and examples in your language?

On versioning, Orbistats documents a /v1/ base and says breaking changes would ship under a new version such as /v2/, with non-breaking fields added to the current one, per its documentation. It also lists a changelog, SDKs, examples and a sandbox. Whatever vendor you consider, ask for the equivalent.

Section 5: Delivery methods
Is REST enough, or do you need WebSocket or webhooks for live data?
Do WebSocket connections reconnect cleanly and resume without gaps?
Are webhooks signed, retried and idempotent?
What is the published latency, and how is it measured?
Is push available on the plan you will actually pay for?

Orbistats lists a WebSocket API, where the company cites sub-50ms, and webhooks, plus drop-in widgets. Treat any latency figure as a claim to measure yourself, not a fact. SportsGameOdds lists WebSocket for higher tiers, and Sportradar offers push on selected packages. Never assume a transport exists on your plan.

Section 6: Odds
Which bookmakers and markets are covered, and can you get a written list?
Are odds normalised into one schema across bookmakers?
Are odds decimal, American or fractional, and can you choose?
Is line movement history available?
Are closing odds stored for backtesting?
How fresh is the live odds refresh?

The Orbistats Odds API advertises pre-match and live odds normalised across bookmakers, including 1X2, moneyline, spreads, totals and props. The odds-first vendors, SportsGameOdds, OddsPapi and The Odds API, compete mainly on this section, so test them hardest here.

Section 7: History
How many seasons are available, per sport, not just overall?
Does history include lineups, events and statistics, or only results?
Are historical odds and closing odds included?
Can you bulk export, or only page through an API?
Is history included in your plan or a paid add-on?

Orbistats describes a Historical Data API and says some seasons go back to 2010. Check retention for your specific sport and competition. Sportmonks notes that older history can be an add-on on some plans.

Section 8: Reliability and support
Is there a public status page?
Is there an SLA, and what are the remedies?
What are the support channels and response times?
Is there a public changelog for incidents and changes?
How does the vendor communicate deprecations?

Orbistats links a public status page. For any vendor, compare the status page against your own monitoring over time rather than trusting either alone.

Automate what you can: a checklist script

Some checks are mechanical. This script tests six of them against any endpoint: does it reject a missing key, does it return a JSON content type, are timestamps ISO 8601, are IDs stable across calls, does it expose rate-limit headers, and does it respond within a time limit.

Install the dependency:

bash
pip install requests

Create eval_api.py:

python
import json
import re
import sys
import time
import requests

ISO_8601 = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2})?(.\d+)?(Z|[+-]\d{2}:?\d{2})$")

def walk(obj, path=""):
if isinstance(obj, dict):
for key, value in obj.items():
yield from walk(value, path + "." + key)
elif isinstance(obj, list):
for item in obj[:20]:
yield from walk(item, path + "[]")
else:
yield path, obj

def check_rejects_missing_key(url, params):
r = requests.get(url, params=params, timeout=10)
return r.status_code in (401, 403), "status " + str(r.status_code) + " without credentials"

def check_json_content_type(response):
kind = response.headers.get("Content-Type", "")
return "json" in kind.lower(), kind or "no Content-Type header"

def check_iso_timestamps(data):
bad = []
seen = 0
for path, value in walk(data):
name = path.split(".")[-1].lower()
if isinstance(value, str) and any(word in name for word in ("time", "date", "at")):
seen += 1
if not ISO_8601.match(value):
bad.append(path + "=" + value)
if seen == 0:
return None, "no timestamp-like fields found"
return len(bad) == 0, "bad examples: " + str(bad[:3]) if bad else str(seen) + " fields look ISO 8601"

def collect_ids(data):
ids = set()
for path, value in walk(data):
if path.split(".")[-1].lower().endswith("id"):
ids.add(str(value))
return ids

def check_stable_ids(first, second):
a, b = collect_ids(first), collect_ids(second)
if not a or not b:
return None, "no id fields found"
overlap = len(a & b) / len(a | b)
return overlap > 0.5, "id overlap between two calls: " + str(round(overlap, 2))

def check_rate_limit_headers(response):
found = {}
for name, value in response.headers.items():
low = name.lower()
if "ratelimit" in low or "rate-limit" in low or "remaining" in low or "retry-after" in low:
found[name] = value
return len(found) > 0, str(found) if found else "no rate-limit headers"

def check_latency(elapsed_ms, limit_ms=1500):
return elapsed_ms <= limit_ms, str(elapsed_ms) + " ms (limit " + str(limit_ms) + ")"

def main(url, headers, params):
print("Evaluating", url)
results = []

ok, note = check_rejects_missing_key(url, params)
results.append(("rejects missing key", ok, note))

start = time.perf_counter_ns()
r1 = requests.get(url, headers=headers, params=params, timeout=10)
elapsed = (time.perf_counter_ns() - start) // 1_000_000
r1.raise_for_status()
data1 = r1.json()
time.sleep(2)
r2 = requests.get(url, headers=headers, params=params, timeout=10)
data2 = r2.json()

results.append(("json content type",) + check_json_content_type(r1))
results.append(("iso 8601 timestamps",) + check_iso_timestamps(data1))
results.append(("stable ids",) + check_stable_ids(data1, data2))
results.append(("rate-limit headers",) + check_rate_limit_headers(r1))
results.append(("latency",) + check_latency(elapsed))

for name, ok, note in results:
    label = "UNKNOWN" if ok is None else ("PASS" if ok else "FAIL")
    print(label.ljust(8), name.ljust(24), note)

if name == "main":
api_url = sys.argv[1]
key_header = json.loads(sys.argv[2]) if len(sys.argv) > 2 else {}
query = json.loads(sys.argv[3]) if len(sys.argv) > 3 else {}
main(api_url, key_header, query)

Run it against Orbistats’ documented live endpoint:

bash
python eval_api.py "https://api.orbistats.com/v1/football/matches/live" '{"Authorization": "Bearer YOUR_API_KEY"}'

Run it against any other vendor by changing the URL, header and query parameters according to that vendor’s docs. Confirm each vendor’s endpoint and authentication method in its documentation before running, for example API-Football and The Odds API each use their own key style.

A few honest limits of this script. A live endpoint may return an empty list when no match is on, which makes some checks report UNKNOWN, so run it during a match window. A free-tier key may behave differently from a paid one. And passing six mechanical checks says nothing about rights, coverage depth or support, which still need the human checklist above.

Score your shortlist

Write each vendor’s result in a simple grid. Eight sections, each scored pass, fail or unknown, and a weight from 1 to 3 for how much that section matters to you. Multiply, add up, and then look closely at the unknowns, because they are the questions to put in your email to the vendor.

Questions worth sending to any vendor in writing:

A coverage matrix for my exact leagues and markets.
Sample payloads for a live match and for historical data.
The redistribution and betting-use terms for my territory.
Per-minute and daily limits on the plan I will buy.
SLA, status page and incident history.
Which vendors fit which kind of product
Regulated sportsbook or broadcaster: Sportradar, Genius Sports or Stats Perform, because rights and SLAs justify a contract.
Football-only product: Sportmonks for production, API-Football for a cheap prototype.
US fantasy app: SportsDataIO, with a written quote for your league.
Odds-focused app: SportsGameOdds, OddsPapi or The Odds API, judged by bookmaker coverage and billing model.
Multi-sport app with odds, streaming and history in one account: Orbistats is worth testing, for example through the quickstart and the API reference. Remember its pass-based pricing suits sprints and tests better than a long-running single-sport app, and that access starts after a request is approved.
Common mistakes when evaluating
Choosing on the feature table and never checking your own leagues.
Skipping the licence until after launch.
Comparing prices without translating them into your own usage.
Trusting a latency claim instead of measuring it from your region.
Testing only the happy path and never the rate-limit and error behaviour.
Coupling your code to one vendor’s schema, which makes switching painful. Put an adapter layer between your app and the vendor.
Next steps

Pick two vendors, run the script against both, send the five written questions, and score them on the grid. If a multi-sport feed with odds and streaming fits your project, you can request an Orbistats access pass and test it against your own sports. The glossary explains the odds terms if any are new, and the research page shows the kind of data the company publishes from its own feeds.

10 Sports Data APIs, 1 Benchmark Script: How to Compare Response Time and Reliability

orbistats — Mon, 12 Oct 2026 03:31:38 +0000

Why one-off latency tests mislead

Run a speed test once and you learn how one API behaved for 20 seconds from your laptop. That is not reliability. Reliability is what happens over days: how often a call succeeds, how often it times out, what happens when you hit a rate limit, and whether the slow tail (the p95 and p99) stays acceptable.

So instead of a single run, we build a small monitor that probes each provider on a schedule, stores every result, and produces a report. By the end you will have two scripts and a SQLite file you can chart, share or attach to a vendor negotiation.

Read this first: I work with Orbistats, which is one of the ten providers. I have not run this monitor over time, so there are no results in this post. Vendor facts come from public pages as of 12 October 2026, and you should verify them. Publish your own numbers, with your region and dates, once you have them.

The ten providers and what they let you test

Not every vendor offers free access, so plan which ones you can actually probe:

Sportradar: enterprise, quote-based, a trial is advertised for many APIs.
Stats Perform (Opta): premium analytics, tailored licensing, sales contact.
Genius Sports: official data and integrity, custom quote.
Sportmonks: self-serve football, entry plan at €29 per month.
SportsDataIO: US leagues and fantasy, product-specific pricing.
Orbistats: 13 sports, Free pass of 1 hour after request and approval.
OddsPapi: odds-focused, details unverified.
SportsGameOdds: free tier, billed by returned objects.
API-Football: free plan with 100 requests per day.
The Odds API: free tier with a quota by sport, market and region.

A fair note on the free passes: Orbistats’ Free pass lasts 1 hour from the moment you open your activation link, so a multi-day monitor needs a longer pass. Its pricing is pass-based: Starter is €19 for 24 hours, Growth €79 for 5 days, and Unlimited €1,999 for 30 days. For API-Football, 100 requests per day limits how often you can probe, which we handle below.

What we will measure

For every probe we record four things: the HTTP status, the response time, whether the body was valid JSON, and an outcome label. The outcome label is the important part. A timeout, a 429 rate limit and a 503 are three different problems, and lumping them together as “failed” hides what is really going on.

ok: a 2xx response with valid JSON.
rate_limited: HTTP 429. This is your quota, not the vendor’s outage.
client_error: other 4xx, usually a bad key or wrong endpoint.
server_error: 5xx, the vendor’s problem.
timeout: no answer within the limit.
connection_error: DNS, TLS or network failure.
bad_json: a 2xx whose body is not valid JSON.
Step 1: Setup
bash
mkdir sports-reliability && cd sports-reliability
python -m venv .venv && source .venv/bin/activate
pip install requests

Set your keys as environment variables so they never appear in code:

bash
export ORBISTATS_KEY="your_key_here"
export APIFOOTBALL_KEY="your_key_here"
export ODDSAPI_KEY="your_key_here"
Step 2: Describe your targets

Treat each vendor as data. Orbistats’ base URL and bearer authentication come from its documentation and quickstart. For every other vendor, confirm the endpoint and auth header in its own docs. The two extra entries below are examples to verify, not guaranteed values.

Create targets.py:

python
import os

TARGETS = {
"orbistats": {
"url": "https://api.orbistats.com/v1/football/matches/live",
"headers": {"Authorization": "Bearer " + os.getenv("ORBISTATS_KEY", "")},
"params": {},
"interval": 60,
},
"api_football": {
"url": "https://v3.football.api-sports.io/fixtures",
"headers": {"x-apisports-key": os.getenv("APIFOOTBALL_KEY", "")},
"params": {"live": "all"},
"interval": 900,
},
"the_odds_api": {
"url": "https://api.the-odds-api.com/v4/sports",
"headers": {},
"params": {"apiKey": os.getenv("ODDSAPI_KEY", "")},
"interval": 900,
},
}

Each target has its own interval in seconds. That is how you respect a 100-requests-per-day free plan: at one probe every 900 seconds you use 96 requests a day.

Step 3: The probe and the database

Create monitor.py:

python
import sqlite3
import time
import requests
from targets import TARGETS

DB_FILE = "reliability.db"
TIMEOUT = 10

def init_db():
conn = sqlite3.connect(DB_FILE)
conn.execute(
"CREATE TABLE IF NOT EXISTS probes ("
"ts INTEGER, provider TEXT, status INTEGER, "
"latency_ms INTEGER, outcome TEXT, size_bytes INTEGER)"
)
conn.commit()
return conn

def probe(cfg):
start = time.perf_counter_ns()
try:
r = requests.get(
cfg["url"],
headers=cfg["headers"],
params=cfg["params"],
timeout=TIMEOUT,
)
except requests.Timeout:
return None, TIMEOUT * 1000, "timeout", 0
except requests.RequestException:
return None, (time.perf_counter_ns() - start) // 1_000_000, "connection_error", 0

latency = (time.perf_counter_ns() - start) // 1_000_000
size = len(r.content)

if r.status_code == 429:
    return r.status_code, latency, "rate_limited", size
if 400 <= r.status_code < 500:
    return r.status_code, latency, "client_error", size
if r.status_code >= 500:
    return r.status_code, latency, "server_error", size
try:
    r.json()
except ValueError:
    return r.status_code, latency, "bad_json", size
return r.status_code, latency, "ok", size

def record(conn, provider, result):
status, latency, outcome, size = result
conn.execute(
"INSERT INTO probes VALUES (?, ?, ?, ?, ?, ?)",
(int(time.time()), provider, status, latency, outcome, size),
)
conn.commit()

def run_forever():
conn = init_db()
next_due = {name: 0 for name in TARGETS}
while True:
now = time.time()
for name, cfg in TARGETS.items():
if now >= next_due[name]:
record(conn, name, probe(cfg))
next_due[name] = now + cfg["interval"]
print("probed", name)
time.sleep(1)

if name == "main":
run_forever()

Run it with: python monitor.py

Leave it running for hours or days, ideally on a small always-on machine or server in the region where your real users are. A laptop that sleeps will give you gaps that look like outages.

Step 4: The report

Create report.py:

python
import sqlite3
import statistics

conn = sqlite3.connect("reliability.db")

def percentile(values, p):
values = sorted(values)
if not values:
return None
index = round((p / 100) * (len(values) - 1))
return values[index]

providers = [row[0] for row in conn.execute("SELECT DISTINCT provider FROM probes")]

for provider in providers:
rows = conn.execute(
"SELECT latency_ms, outcome FROM probes WHERE provider = ?", (provider,)
).fetchall()

total = len(rows)
ok_latencies = [lat for lat, outcome in rows if outcome == "ok"]
counts = {}
for _, outcome in rows:
    counts[outcome] = counts.get(outcome, 0) + 1

counted = total - counts.get("rate_limited", 0)
availability = (len(ok_latencies) / counted * 100) if counted else 0

print(provider)
print("  probes:", total)
print("  availability (excluding 429s):", round(availability, 2), "percent")
print("  median ms:", round(statistics.median(ok_latencies)) if ok_latencies else None)
print("  p95 ms:", percentile(ok_latencies, 95))
print("  p99 ms:", percentile(ok_latencies, 99))
print("  outcomes:", counts)
print()

Run it with: python report.py

Two choices here are worth explaining. Latency percentiles use only successful calls, because a timeout recorded as 10,000 ms would distort the median in a misleading way. And availability excludes 429s, because hitting your own quota is not the vendor being down. Report both numbers if you publish results, so readers can see how you counted.

Step 5: Measure live streaming separately

Request and response APIs are only half the picture. For live scores and odds, the question is whether a stream stays connected. Orbistats offers a WebSocket API, where the company cites sub-50ms, and webhooks. Take the exact connection URL and subscribe message from the documentation and never guess them. This script counts how long a connection survives and how many messages arrive:

python
import json
import time
import websocket

WS_URL = "PASTE_WS_URL_FROM_DOCS"
SUBSCRIBE = {"action": "subscribe", "sport": "football"}

connected_at = time.time()
messages = 0
try:
ws = websocket.create_connection(WS_URL, timeout=60)
ws.send(json.dumps(SUBSCRIBE))
while True:
ws.recv()
messages += 1
except Exception as e:
uptime = round(time.time() - connected_at)
print("disconnected after", uptime, "seconds,", messages, "messages, reason:", repr(e))

Install the extra dependency with: pip install websocket-client. The SUBSCRIBE message above is illustrative. Log how often the connection drops, and how long reconnecting takes, across a full match window.

Step 6: Read the results honestly

Numbers are easy to misuse. Before you draw conclusions, check these:

Sample size. A few dozen probes tell you almost nothing about p99. Collect hundreds, ideally thousands.
Time of day. Probe during live matches and quiet hours, since load differs.
Region. Latency from India is not latency from Frankfurt. Always state where the monitor ran.
Compare like with like. A live-scores endpoint and a static standings endpoint are not the same workload.
Caching. A response served from a vendor cache can look unrealistically fast.
Plan differences. A free tier can be throttled differently from a paid one.
Empty live endpoints. A live endpoint may legitimately return an empty list when no match is on, so label those periods.

For vendors that publish a status page, compare your own results with it. Orbistats lists a public status page, and checking it against your own logs is a useful sanity test of both.

A results template to publish

When you have real data, present it like this, one block per provider, with your own measurements:

Provider: name
Plan tested: free, trial or paid
Region and dates: where the monitor ran and for how long
Probes: total number
Availability: percent, excluding 429s
Median and p95 latency: in milliseconds
Dominant failure: timeout, 5xx or rate limit

Keep the method next to the numbers: interval, timeout, endpoint, and whether a match was live.

Which provider should you probe first?
Enterprise vendors (Sportradar, Stats Perform, Genius Sports): ask sales for a trial key and written SLA terms, then probe the same way.
Football products: Sportmonks and API-Football, probed on the leagues you will actually show.
Odds apps: SportsGameOdds, OddsPapi and The Odds API, probed on the markets and bookmakers you need.
Multi-sport apps with odds and streaming: Orbistats covers 13 sports (football, basketball, American football, cricket, tennis, baseball, esports, combat sports, volleyball, handball, ice hockey, golf and horse racing), so probe your own sports, for example cricket or basketball, in the sandbox before committing.
Backtesting and machine learning: probe the history endpoint separately, for example the Historical Data API, and verify retention per sport. The company says some seasons go back to 2010.
Common mistakes
Counting 429s as vendor downtime, which blames them for your own quota.
Probing too often on a request-metered plan and burning the free tier in an afternoon.
Running the monitor on a laptop that sleeps.
Measuring from one region and generalising to everywhere.
Publishing a table with no method, so nobody can trust or reproduce it.
Next steps

Chart the SQLite data with a notebook, add an alert when availability drops below a threshold, and run the same monitor against your own production traffic so you compare vendor claims with what your users actually experience. If you want an access pass to add a multi-sport feed to the test, follow the quickstart and request access here. The glossary is useful if the odds terms are new, and the API reference lists the exact response shapes.

Building a Provider-Agnostic Sports Data Client: What 10 Different APIs Teach You About Design

orbistats — Mon, 12 Oct 2026 03:29:01 +0000

Why you need a provider-agnostic client

Most sports apps start with one API and one hard-coded JSON shape. Six months later the vendor changes pricing, drops a league, or you need a second source for odds, and suddenly the vendor’s field names are spread across your whole codebase.

The fix is old and boring: put every vendor behind an adapter and make your app depend only on your own models. This tutorial builds that client in Python, using ten real providers as the design reference.

Read this first: I work with Orbistats, which is one of the ten providers. I did not run performance tests for this post, so there are no benchmark numbers here. Everything about vendors comes from their public pages as of 12 October 2026, and you should verify it before relying on it.

The ten providers and how they differ

The differences between vendors are exactly why an adapter layer is worth building:

Sportradar: enterprise, quote-based, claims 80+ sports and 500+ leagues, push on selected packages.
Stats Perform (Opta): premium analytics, tailored licensing.
Genius Sports: official data and integrity, custom quote.
Sportmonks: self-serve football, plans metered by number of leagues.
SportsDataIO: US leagues and fantasy, product-specific pricing.
Orbistats: 13 sports, odds, WebSocket, webhooks, history, access passes instead of monthly plans.
OddsPapi: odds-focused, details unverified, check the live page.
SportsGameOdds: odds-first, billed by returned objects.
API-Football: football only, billed by daily requests.
The Odds API: odds, quota scoped by sport, market and region.

Notice what varies: authentication style, what is metered (requests, objects, leagues, time), whether push delivery exists, and the shape of the JSON. Your client must hide all of that.

Architecture overview

The design has five small pieces:

Models: your own dataclasses, the only types the rest of the app sees.
Provider adapters: one class per vendor, converting vendor JSON into your models.
HTTP helper: retries, backoff and rate-limit handling in one place.
Cache and failover: protect your quota and survive an outage.
Streaming layer: WebSocket with reconnects, and a webhook receiver.
Step 1: Define your own models

Create models.py:

python
from dataclasses import dataclass
from typing import Optional

@dataclass
class LiveMatch:
provider: str
match_id: str
minute: Optional[int]
home_name: str
home_score: int
away_name: str
away_score: int

@dataclass
class OneXTwo:
home: float
draw: float
away: float

Your UI, your database and your analytics code import only these. Vendor field names never leave the adapter.

Step 2: One robust HTTP helper

Every vendor rate-limits differently, so handle it once. Create http_client.py:

python
import random
import time
import requests

RETRY_STATUS = {429, 500, 502, 503, 504}

def get_json(url, headers=None, params=None, retries=3, timeout=10):
last_error = None
for attempt in range(retries + 1):
delay = pow(2, attempt) / 2
try:
r = requests.get(url, headers=headers or {}, params=params or {}, timeout=timeout)
if r.status_code not in RETRY_STATUS:
r.raise_for_status()
return r.json()
retry_after = r.headers.get("Retry-After", "")
if retry_after.isdigit():
delay = float(retry_after)
last_error = "HTTP " + str(r.status_code)
except requests.RequestException as e:
last_error = str(e)
if attempt < retries:
time.sleep(delay + random.uniform(0, 0.3))
raise RuntimeError("request failed after retries: " + str(last_error))

Two details matter here. Exponential backoff with a little random jitter stops many clients retrying in lockstep, and honoring Retry-After respects whatever the vendor tells you.

Step 3: The provider interface

Create providers.py with a base class:

python
from abc import ABC, abstractmethod

class SportsProvider(ABC):
name = "base"

@abstractmethod
def live_matches(self, sport):
    pass

The Orbistats adapter

Orbistats documents a base URL of https://api.orbistats.com/v1/ with bearer-token authentication, and a live endpoint shaped like GET /v1/football/matches/live. The live example on its homepage returns match_id, status, minute, and home and away objects with name and score. Check the API reference for the exact response shape before shipping, in particular whether the endpoint returns one object or a list.

python
from http_client import get_json
from models import LiveMatch

class OrbistatsProvider(SportsProvider):
name = "orbistats"
BASE = "https://api.orbistats.com/v1"

def __init__(self, api_key):
    self.headers = {"Authorization": "Bearer " + api_key}

def live_matches(self, sport="football"):
    data = get_json(self.BASE + "/" + sport + "/matches/live", headers=self.headers)
    items = data if isinstance(data, list) else [data]
    return [
        LiveMatch(
            provider=self.name,
            match_id=str(m["match_id"]),
            minute=m.get("minute"),
            home_name=m["home"]["name"],
            home_score=m["home"]["score"],
            away_name=m["away"]["name"],
            away_score=m["away"]["score"],
        )
        for m in items
    ]

Writing the next adapter

For any other vendor, copy this class, change the URL and auth header from that vendor’s docs, and rewrite only the mapping inside live_matches. For example, API-Football authenticates with its own key header and The Odds API takes the key as a query parameter, but confirm both in their documentation (API-Football, The Odds API) before coding. That is the whole point of the pattern: the difference lives in one small class.

Step 4: Cache to protect your quota

Request-metered plans punish naive polling. A tiny time-based cache is often the cheapest optimization you will ever make.

python
import time

class TtlCache:
def init(self, ttl_seconds):
self.ttl = ttl_seconds
self.store = {}

def get(self, key):
    item = self.store.get(key)
    if item and time.monotonic() - item[0] < self.ttl:
        return item[1]
    return None

def set(self, key, value):
    self.store[key] = (time.monotonic(), value)

Pick the TTL per data type: fixtures and standings can live for minutes, live scores for seconds.

Step 5: Failover between providers

Create client.py:

python
class SportsClient:
def init(self, providers, cache):
self.providers = providers
self.cache = cache

def live_matches(self, sport="football"):
    key = "live:" + sport
    cached = self.cache.get(key)
    if cached is not None:
        return cached

    errors = {}
    for provider in self.providers:
        try:
            result = provider.live_matches(sport)
            self.cache.set(key, result)
            return result
        except Exception as e:
            errors[provider.name] = str(e)
    raise RuntimeError("all providers failed: " + str(errors))

Use it like this:

python
import os
from client import SportsClient
from providers import OrbistatsProvider
from cache import TtlCache

client = SportsClient(
providers=[OrbistatsProvider(os.getenv("ORBISTATS_KEY", ""))],
cache=TtlCache(ttl_seconds=5),
)

for match in client.live_matches("football"):
print(match.home_name, match.home_score, "-", match.away_score, match.away_name)

Add a second provider to the list and failover works with no other change. Remember that failing over between vendors can change data rights and coverage, so check the licence of each source before you mix them.

Step 6: Normalize odds across bookmakers

Odds are where schemas diverge most. Convert everything to decimal odds in your own model, then compute implied probability and the bookmaker margin. The Orbistats Odds API advertises normalized 1X2, moneyline, spreads, totals and props across books, and its docs example shows a 1X2 market like home 1.91, draw 3.40, away 4.20.

python
from models import OneXTwo

def implied_probabilities(odds):
return {
"home": 1 / odds.home,
"draw": 1 / odds.draw,
"away": 1 / odds.away,
}

def overround(odds):
return sum(implied_probabilities(odds).values())

example = OneXTwo(home=1.91, draw=3.40, away=4.20)
print(round(overround(example), 4))

For that example the three implied probabilities add up to roughly 1.056, meaning the book builds in about a 5.6 percent margin. Comparing that number across vendors for the same fixture is a quick sanity check on data quality. If you are new to these terms, the Orbistats glossary explains implied probability and more.

Step 7: Streaming with automatic reconnects

Polling wastes quota and adds delay for live data. Orbistats offers a WebSocket API, where the company cites sub-50ms, and webhooks. Take the exact connection URL and subscribe message from the documentation. Connections drop in the real world, so reconnect with backoff:

python
import json
import time
import websocket

def stream(url, subscribe_message, on_event):
attempt = 0
while True:
try:
ws = websocket.create_connection(url, timeout=30)
ws.send(json.dumps(subscribe_message))
attempt = 0
while True:
on_event(json.loads(ws.recv()))
except Exception:
attempt += 1
time.sleep(min(30, pow(2, attempt)))

Install the dependency with: pip install websocket-client. The subscribe message is vendor-specific, so never guess it.

Step 8: A safe webhook receiver

Webhooks can be delivered more than once, so make your handler idempotent. This example fingerprints the raw body so a repeated delivery is ignored. Check the vendor docs for whether deliveries are signed, and verify signatures if they are.

python
import hashlib
from flask import Flask, request

app = Flask(name)
seen = set()

@app.route("/webhook/sports", methods=["POST"])
def webhook():
fingerprint = hashlib.sha256(request.get_data()).hexdigest()
if fingerprint in seen:
return "", 200
seen.add(fingerprint)
print(request.get_json(silent=True))
return "", 200

if name == "main":
app.run(port=3000)

Install with: pip install flask. Acknowledge quickly and do heavy work in a background job. In production, replace the in-memory set with Redis or a database table.

Step 9: Test without calling real APIs

Because your app depends on the interface, you can test failover with fakes and spend zero quota:

python
from cache import TtlCache
from client import SportsClient
from models import LiveMatch

class BrokenProvider:
name = "broken"

def live_matches(self, sport):
    raise RuntimeError("down")

class FakeProvider:
name = "fake"

def live_matches(self, sport):
    return [LiveMatch("fake", "1", 72, "Home", 2, "Away", 1)]

def test_failover_uses_second_provider():
client = SportsClient([BrokenProvider(), FakeProvider()], TtlCache(0))
result = client.live_matches("football")
assert result[0].provider == "fake"

Run with: pip install pytest, then pytest.

Design lessons that apply to every vendor
Hide metering. Requests, objects, leagues and time windows are different units, so track your own usage and alert before you hit limits.
Never trust one schema. Parse defensively and fail loudly when a required field is missing.
Separate rights from technology. A fast feed you cannot legally redistribute is worthless, so read each licence.
Prefer push for live data. REST suits fixtures, standings and history, while WebSocket or webhooks suit live scores and odds.
Keep history behind its own interface. Backtesting data has different retention and cost rules. Orbistats describes a historical archive and says some seasons go back to 2010, but verify retention per sport.
Which vendor should sit behind your adapter?
Regulated sportsbook or broadcaster: Sportradar, Genius Sports or Stats Perform, because rights and SLAs justify a contract.
Football-only product: Sportmonks for production, API-Football for a cheap prototype.
US fantasy app: SportsDataIO, with a written quote.
Odds-focused app: SportsGameOdds, OddsPapi or The Odds API, judged by bookmaker coverage and billing model.
Multi-sport app with odds and streaming: Orbistats covers 13 sports (football, basketball, American football, cricket, tennis, baseball, esports, combat sports, volleyball, handball, ice hockey, golf and horse racing). Its pricing is pass-based, not monthly: Free is €0 for 1 hour, Starter €19 for 24 hours, Growth €79 for 5 days and Unlimited €1,999 per month for 30 days. Access starts after you request it, so try the sandbox and check the status page on your own leagues, for example cricket or basketball, before committing.

Because of the adapter layer, this choice is no longer a one-way door.

Common mistakes
Letting vendor JSON leak into your database schema.
Retrying on every error, including 401 and 403, which burns quota for nothing.
Polling live endpoints every second on a request-metered plan.
Forgetting that free passes and trials are time or quota limited.
Mixing providers without checking redistribution rights.
Next steps

Add a second adapter, add per-provider usage counters, and put a small dashboard on top of your logs. If you want to try the multi-sport feed, follow the quickstart, request an access pass and plug it in as one more provider. The whole point of this design is that trying a new vendor costs you one class, not a rewrite.

I Built a Benchmark for 10 Sports Data APIs’ Free Tiers — Here’s the Code (and How to Run It)

orbistats — Mon, 12 Oct 2026 03:24:19 +0000

A provider-agnostic Python harness that measures latency, schema consistency and quota burn, so you can produce your own results in 30 minutes.

Read this first: I work with Orbistats (https://orbistats.com/), which is one of the ten providers below. I have not published benchmark numbers here, because latency depends on your region, network and plan, and several vendors have no self-serve free tier at all. Instead you get the harness and a results template. Run it, then publish your own numbers. Public claims and prices are as of 12 October 2026.

What we’re building

A small tool that, for any sports data API, answers four questions:

How fast is a typical response? (median and p95 latency)
Is the data shape stable? (same fields on every call)
What does a call cost against my quota?
Does live data arrive by push, or only by polling?

By the end you will have a benchmark.py that writes a CSV you can paste into a blog post, a spreadsheet or a vendor negotiation.

Which of the ten actually offer free access?

The title says “free tiers,” but only some vendors have one. Here is what the public information says:

Sportradar (https://sportradar.com/media-tech/data-content/sports-data-api/): trial advertised for many APIs (30 days for the sports data API).
Stats Perform / Opta (https://www.statsperform.com/products/): sales contact, tailored licensing.
Genius Sports (https://www.geniussports.com/engage/official-sports-data-api/): sales contact, no public self-serve price.
Sportmonks (https://www.sportmonks.com/football-api/plans-pricing/): entry plan €29/month, check the page for any trial.
SportsDataIO (https://sportsdata.io/): product-specific, verify directly.
Orbistats (https://orbistats.com/pricing.html): Free €0 pass, 1 hour, after request and approval.
OddsPapi (https://oddspapi.io/): not verified, check the live page.
SportsGameOdds (https://sportsgameodds.com/pricing): free tier, 2,500 objects/month.
API-Football (https://www.api-football.com/pricing): free, 100 requests/day.
The Odds API (https://the-odds-api.com/): free tier, recheck quota.

So a true free-tier shootout is possible for only about four of the ten. For the rest, the harness works with a trial key or a paid entry plan.

Step 1: Project setup

mkdir sports-api-bench && cd sports-api-bench
python -m venv .venv && source .venv/bin/activate
pip install requests websocket-client

Set your keys as environment variables so they never touch the code:

export ORBISTATS_KEY="your_key_here"
export APIFOOTBALL_KEY="your_key_here"
export ODDSAPI_KEY="your_key_here"

Step 2: Describe each provider as data

The trick is to treat every vendor as a config entry, not a code branch. Orbistats’ URL and bearer auth come from its documentation (quickstart: https://orbistats.com/developers/quickstart.html, docs: https://orbistats.com/developers/documentation.html). For the others, confirm the endpoint and auth header in each vendor’s docs. The two below are shown as examples to verify.

Save this as providers.py:

import os

PROVIDERS = {
“orbistats”: {
“url”: “https://api.orbistats.com/v1/football/matches/live”,
“headers”: {“Authorization”: “Bearer “ + os.getenv(“ORBISTATS_KEY”, “”)},
“params”: {},
},
“api_football”: {
“url”: “https://v3.football.api-sports.io/fixtures”,
“headers”: {“x-apisports-key”: os.getenv(“APIFOOTBALL_KEY”, “”)},
“params”: {“live”: “all”},
},
“the_odds_api”: {
“url”: “https://api.the-odds-api.com/v4/sports”,
“headers”: {},
“params”: {“apiKey”: os.getenv(“ODDSAPI_KEY”, “”)},
},
}

Adding a vendor is now one dictionary entry. (Verify the api_football and the_odds_api entries against their docs before running.)

Step 3: Measure latency and schema stability

Save this as benchmark.py:

import csv, statistics, time, requests
from providers import PROVIDERS

N = 20
PAUSE = 1.0

def field_paths(obj, prefix=""):
paths = set()
if isinstance(obj, dict):
for k, v in obj.items():
paths |= field_paths(v, prefix + k + “.”)
elif isinstance(obj, list) and obj:
paths |= field_paths(obj[0], prefix)
else:
paths.add(prefix.rstrip(“.”))
return paths

def bench(name, cfg):
times, shapes, quota_headers = [], [], {}
for _ in range(N):
t0 = time.perf_counter_ns()
try:
r = requests.get(cfg[“url”], headers=cfg[“headers”],
params=cfg[“params”], timeout=10)
except requests.RequestException:
continue
times.append((time.perf_counter_ns() - t0) // 1_000_000)
for h, v in r.headers.items():
low = h.lower()
if “limit” in low or “remaining” in low or “used” in low:
quota_headers[h] = v
try:
shapes.append(frozenset(field_paths(r.json())))
except ValueError:
pass
time.sleep(PAUSE)

times.sort()
ok = len(times)
return {
"provider": name,
"ok_calls": ok,
"median_ms": round(statistics.median(times)) if ok else None,
"p95_ms": times[-1 - ok // 20] if ok else None,
"schema_stable": (len(set(shapes)) <= 1) if shapes else None,
"quota_headers": quota_headers,
}

if name == “main”:
rows = [bench(n, c) for n, c in PROVIDERS.items()]
with open(“results.csv”, “w”, newline="") as f:
w = csv.DictWriter(f, fieldnames=rows[0].keys())
w.writeheader()
w.writerows(rows)
for r in rows:
print(r)

Run it with: python benchmark.py

Two cautions about what the numbers mean. First, this measures request round-trip from your machine, which includes your own network. Second, a “live” endpoint may legitimately return an empty list when no match is on, so run it during a match window. Keep N low on free tiers, because every call burns quota.

Step 4: Test push delivery (WebSocket)

Polling latency is only half the story. For live scores and odds, compare how long a push takes to reach you. Orbistats lists WebSocket streaming (https://orbistats.com/api/websocket-api.html), where the company cites sub-50ms, and webhooks (https://orbistats.com/api/webhooks-api.html). Take the connection URL and subscribe message from the docs, then log the gaps between messages.

Save this as ws_probe.py:

import json, time, websocket

WS_URL = “PASTE_WS_URL_FROM_DOCS”
SUBSCRIBE = {“action”: “subscribe”, “sport”: “football”}

ws = websocket.create_connection(WS_URL, timeout=30)
ws.send(json.dumps(SUBSCRIBE))

last = None
gaps = []
for _ in range(100):
msg = ws.recv()
now = time.perf_counter_ns()
if last is not None:
gaps.append((now - last) // 1_000_000)
last = now
print(json.loads(msg))

gaps.sort()
print(“messages:”, len(gaps) + 1, “median gap ms:”, gaps[len(gaps) // 2])

The SUBSCRIBE message above is illustrative. Use the exact one from the documentation.

Honest limitation: gaps between messages show update cadence, not true end-to-end latency. To measure that, compare each event’s timestamp against a trusted reference such as an official match clock or a second vendor.

Step 5: Receive webhooks locally

Save this as server.js:

import express from “express”;
const app = express();
app.use(express.json());

app.post(“/webhook/sports”, (req, res) => {
const receivedAt = Date.now();
console.log(receivedAt, JSON.stringify(req.body).slice(0, 200));
res.sendStatus(200);
});

app.listen(3000, () => console.log(“listening on port 3000”));

Acknowledge fast and process asynchronously. Expose the server with a tunnel such as ngrok during testing, and register the URL as described in the documentation (https://orbistats.com/developers/documentation.html).

Step 6: Your results template

Fill this in after running the harness. Replace every dash with your own measurement, region and date.

Publish the methodology next to the table: region, time of day, number of samples and whether a match was live.

What the public docs already tell you

While you wait for your own data, here is what the vendors say about themselves. Verify all of it.

Sportradar (https://developer.sportradar.com/getting-started/docs/get-started): 80+ sports, 500+ leagues, push on selected packages, quote-based.
Sportmonks (https://www.sportmonks.com/football-api/coverage/): 2,200+ football leagues, plans at €29, €99 and €249 per month.
SportsGameOdds (https://sportsgameodds.com/docs/basics): 67+ leagues, 28+ sports, 85+ bookmakers depending on plan, object-based billing.
API-Football (https://www.api-football.com/coverage): 1,248 leagues and cups, 100 free requests a day.
Orbistats (https://orbistats.com/): 13 sports (football, basketball, American football, cricket, tennis, baseball, esports, combat sports, volleyball, handball, ice hockey, golf, horse racing). Passes at €0, €19, €79 and €1,999 per month. Some seasons back to 2010, per the company. Try its sandbox (https://orbistats.com/developers/sandbox.html) and check the status page (https://orbistats.com/developers/status.html).

Pitfalls to avoid

Benchmarking one endpoint and generalising to the whole API.
Forgetting that free tiers can be throttled differently from paid ones.
Comparing a cached response to a fresh one.
Ignoring commercial rights: a fast feed you cannot redistribute is useless.
Burning your free quota in the first run. Lower N.

Next steps

Extend the harness with odds checks (compare the same fixture’s 1X2 prices across vendors), a coverage check for your target leagues using Orbistats’ per-sport pages (https://orbistats.com/sports/cricket.html), and a nightly GitHub Action that appends to results.csv so you can chart reliability over weeks. If you want an access pass to try the multi-sport feed, you can request one here (https://orbistats.com/request-access.html), and the glossary (https://orbistats.com/resources/glossary.html) helps if odds terms are new.

Surviving a 150-Requests-a-Day Free Tier: Caching Patterns for Sports APIs

orbistats — Sat, 10 Oct 2026 12:37:21 +0000

Surviving a 150-Requests-a-Day Free Tier: Caching Patterns for Sports APIs

You sign up for a free sports API key, make your first request, and it works. Then you read the limit: 150 requests per day.

In a terminal, that feels generous. In a real app, it disappears fast.

Here is the math. 150 calls spread over 24 hours is one call every 9.6 minutes. If your app gets 10,000 page views a day and each view calls the API, your quota is gone in about 90 seconds of traffic. To survive, your cache hit rate must be at least 98.5%.

That is not a tuning problem. It is an architecture problem, and this guide solves it step by step in plain Node.js.

A note on limits. 150/day is a common free-tier ceiling across sports-data providers, and it is the constraint this guide designs for. Limits differ by provider and plan. The Orbistats Free plan, for example, is a time-boxed access window rather than a daily counter. The discipline is the same: every call is precious.

Prerequisites: Node.js 18+ (built-in fetch), basic JavaScript, and an API key. The quickstart guide takes you from signup to your first request.

About endpoints: the paths below follow the pattern in the Orbistats docs (https://api.orbistats.com/v1/{sport}/... with Bearer auth). Confirm exact paths and query parameters in the API reference before shipping.

Step 1: Know the shelf life of your data

The most common mistake with a small quota is using one TTL for everything. Sports data has very different shelf lives:

Data Changes Sensible TTL
Countries, competitions Almost never 7 days
Teams, player profiles Rarely 24 hours
Fixtures A few times a day 3-6 hours
Standings After each match ends 30-60 minutes
Live score Every few seconds 30-60 seconds
Finished match Never Forever
Historical seasons Never Forever

The last two rows are where free tiers are won. A finished match is immutable. Asking for it twice wastes a call.

Step 2: Budget your 150 calls like money

Write the budget before you write any cache code. Here is one for an app covering all 13 sports, including football, basketball and cricket:

Bucket Calls/day Why
Live reserve 40 Spent only when a match is on
Fixtures (13 sports x 1) 13 Schedules barely move
Standings (13 sports x 2) 26 Morning and late evening
Results sync (13 sports x 2) 26 Save finished matches forever
Cache-miss buffer 45 Retries and surprises
Total 150

That is about 11.5 calls per sport per day.

Notice what is missing: “one call per user request.” Users never talk to the API. Users talk to your cache. Only your background jobs talk to the API.

Covering fewer sports? Your budget is much roomier. Start with the sports your audience actually watches.

Step 3: Build a TTL cache with LRU eviction

The foundation is an in-memory cache that tracks freshness and staleness separately. Later steps depend on that split.

js
// cache.js
export class TTLCache {
constructor({ maxEntries = 500 } = {}) {
this.store = new Map();
this.maxEntries = maxEntries;
}

get(key) {
const entry = this.store.get(key);
if (!entry) return null;

// LRU bump: re-insert so recently used keys sit at the end
this.store.delete(key);
this.store.set(key, entry);

const now = Date.now();
return {
  value: entry.value,
  fresh: now < entry.freshUntil,   // serve with zero network
  usable: now < entry.staleUntil,  // serve, but refresh in background
};

}

set(key, value, ttlMs, staleMs = 0) {
const now = Date.now();
this.store.delete(key);
this.store.set(key, {
value,
freshUntil: now + ttlMs,
staleUntil: now + ttlMs + staleMs,
});
if (this.store.size > this.maxEntries) {
this.store.delete(this.store.keys().next().value); // evict LRU
}
}
}

Each entry has two clocks:

Fresh: serve instantly, no call.
Stale but usable: serve instantly and refresh quietly.
Expired: keep it only as an emergency fallback (Step 5).

Step 4: Stop cache stampedes with single-flight

Here is a quiet quota killer. Your football standings entry expires at 12:00:00. At 12:00:01, 200 users load your page. Every request sees an empty cache and fires its own API call. You just spent 200 calls on one piece of data.

The fix is single-flight: if a request for key X is already running, everyone else waits for the same promise.

js
refresh(key, url, ttlMs, staleMs, kind) {
// Someone is already fetching this key? Join them.
if (this.inflight.has(key)) return this.inflight.get(key);

const promise = (async () => {
// budget check + fetch + cache.set (full version in Step 7)
})().finally(() => this.inflight.delete(key));

this.inflight.set(key, promise);
return promise;
}

200 simultaneous users now cost 1 call. This one pattern often saves more quota than any TTL tweak.

Step 5: Serve stale data on purpose

Stale-while-revalidate (SWR) works like this:

The entry is a bit old, so return it immediately.
Start one background refresh.
The next visitor gets fresh data.

Stale-if-error is its cousin. If the API fails or your quota is spent, serve the last known value instead of an error page. A ten-minute-old standings table beats a 500 every time.

When something looks wrong, check the provider’s status page first. It is the fastest way to learn whether the problem is your cache or their infrastructure.

Step 6: Add a budget guard

Caching reduces calls. A budget guard guarantees you never exceed the limit, even when you ship a bug. It also reserves part of the quota for live data, so a runaway standings job cannot starve a live match.

js
// budget.js
export class DailyBudget {
constructor({ limit = 150, reserveForLive = 40 } = {}) {
this.limit = limit;
this.reserveForLive = reserveForLive;
this.day = this.today();
this.used = 0;
}

today() {
// Check your provider: UTC midnight reset, or a rolling 24h window?
return new Date().toISOString().slice(0, 10);
}

roll() {
const t = this.today();
if (t !== this.day) { this.day = t; this.used = 0; }
}

canSpend(kind = 'static') {
this.roll();
const ceiling = kind === 'live' ? this.limit : this.limit - this.reserveForLive;
return this.used < ceiling;
}

spend() { this.roll(); this.used += 1; }
remaining() { this.roll(); return this.limit - this.used; }
}

This counter lives in memory, so it resets on restart. Step 14 shows how to persist it.

Step 7: Assemble the cached client

Now combine everything: cache, single-flight, SWR, stale-if-error and the budget guard.

js
// client.js
import { TTLCache } from './cache.js';
import { DailyBudget } from './budget.js';

export class SportsClient {
constructor({
apiKey,
baseUrl = 'https://api.orbistats.com/v1',
cache = new TTLCache(),
budget = new DailyBudget(),
}) {
Object.assign(this, { apiKey, baseUrl, cache, budget });
this.inflight = new Map();
this.stats = { hits: 0, stale: 0, network: 0, errors: 0 };
}

buildUrl(path, params = {}) {
const url = new URL(this.baseUrl + path);
// Sorted params: ?a=1&b=2 and ?b=2&a=1 share one cache key
Object.keys(params).sort().forEach((k) => url.searchParams.set(k, params[k]));
return url;
}

async get(path, { params, ttlMs, staleMs = 0, kind = 'static' } = {}) {
const url = this.buildUrl(path, params);
const key = url.pathname + url.search;
const hit = this.cache.get(key);

if (hit?.fresh) {                       // 1) fresh: free answer
  this.stats.hits++;
  return { data: hit.value, source: 'cache' };
}

if (hit?.usable) {                      // 2) stale: answer now, refresh quietly
  this.stats.stale++;
  this.refresh(key, url, ttlMs, staleMs, kind).catch(() => {});
  return { data: hit.value, source: 'stale' };
}

try {                                   // 3) miss: network, fall back on failure
  const data = await this.refresh(key, url, ttlMs, staleMs, kind);
  return { data, source: 'network' };
} catch (err) {
  this.stats.errors++;
  if (hit) return { data: hit.value, source: 'stale-if-error' };
  throw err;
}

}

refresh(key, url, ttlMs, staleMs, kind) {
if (this.inflight.has(key)) return this.inflight.get(key);

const promise = (async () => {
  if (!this.budget.canSpend(kind)) throw new Error('BUDGET_EXHAUSTED');
  this.budget.spend();
  this.stats.network++;

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${this.apiKey}` },
  });

  if (res.status === 429) {
    this.budget.used = this.budget.limit; // our count was wrong; stop spending
    throw new Error('RATE_LIMITED');
  }
  if (!res.ok) throw new Error(`HTTP_${res.status}`);

  const data = await res.json();
  this.cache.set(key, data, ttlMs, staleMs);
  return data;
})().finally(() => this.inflight.delete(key));

this.inflight.set(key, promise);
return promise;

}

hitRate() {
const { hits, stale, network } = this.stats;
const total = hits + stale + network;
return total ? (hits + stale) / total : 0;
}
}

Usage:

js
const client = new SportsClient({ apiKey: process.env.ORBISTATS_KEY });

const { data, source } = await client.get('/football/standings', {
params: { competition: 'premier-league' },
ttlMs: 2_700_000, // fresh for 45 minutes
staleMs: 10_800_000, // then usable for 3 more hours
});

Every call site declares its own TTL. Standings and live scores never share a lifetime by accident.

Step 8: Store finished matches forever

An in-memory cache vanishes on restart. For data that can never change, use a permanent store. SQLite is perfect: no server, one file, very fast.

js
// finished.js
import Database from 'better-sqlite3';

const db = new Database('sports.db');
db.exec(CREATE TABLE IF NOT EXISTS finished_matches ( id TEXT PRIMARY KEY, sport TEXT NOT NULL, payload TEXT NOT NULL, saved_at INTEGER NOT NULL ));

const selectOne = db.prepare('SELECT payload FROM finished_matches WHERE id = ?');
const upsert = db.prepare(
'INSERT OR REPLACE INTO finished_matches VALUES (?, ?, ?, ?)'
);

export const getFinished = (id) => {
const row = selectOne.get(id);
return row ? JSON.parse(row.payload) : null;
};

export function saveFinished(match, sport) {
// Confirm the exact "finished" status value in the API reference
if (match.status !== 'finished') return false;
upsert.run(match.match_id, sport, JSON.stringify(match), Date.now());
return true;
}

A nightly results-sync job now makes one call per sport, saves every finished match, and never asks for it again.

The same idea powers model training. If you are backtesting on past seasons, download once and keep your own copy. The Historical Sports Data API is built for exactly that, and the Sports Statistics API pairs well with it for player and team aggregates.

Step 9: Warm the cache on a schedule

This is the mental shift that makes 150 calls viable.

Before: user opens page, your server calls the API, user waits.
After: a scheduled job calls the API, the cache stays warm, the user gets an instant answer with zero API calls.
js
// warmer.js
const SPORTS = [
'football', 'basketball', 'american-football', 'cricket', 'tennis',
'baseball', 'esports', 'combat-sports', 'volleyball', 'handball',
'ice-hockey', 'golf', 'horse-racing',
];

const ONE_HOUR = 3_600_000;
const SIX_HOURS = 21_600_000;
const TWELVE_HOURS = 43_200_000;

async function warm(client, resource, ttlMs, staleMs) {
for (const sport of SPORTS) {
try {
await client.get(/${sport}/${resource}, { ttlMs, staleMs });
} catch (err) {
console.warn(warm ${sport}/${resource} failed:, err.message);
}
}
}

export function startWarmers(client) {
warm(client, 'fixtures', SIX_HOURS, TWELVE_HOURS); // on boot
setInterval(() => warm(client, 'fixtures', SIX_HOURS, TWELVE_HOURS), SIX_HOURS);
setInterval(() => warm(client, 'standings', ONE_HOUR, SIX_HOURS), TWELVE_HOURS);
}

Public routes then read only from the cache and never fall through to the network:

js
app.get('/api/standings/:sport', (req, res) => {
const hit = client.cache.get(/v1/${req.params.sport}/standings);
if (!hit) return res.status(503).json({ error: 'Warming up, retry shortly' });
res.set('Cache-Control', 'public, max-age=60'); // CDN/browser = second cache layer
res.json(hit.value);
});

That Cache-Control header gives you a free second cache layer at your CDN and in the browser.

Step 10: Fetch wide, slice locally

Per-item endpoints drain quota:

text
GET /football/matches/101 <- 1 call
GET /football/matches/102 <- 1 call
GET /football/matches/103 <- 1 call

List endpoints are cheap:

text
GET /football/fixtures <- 1 call, filter in your own code

Whenever you write a loop that makes one API call per item, stop and look for a list endpoint. The Sports Data API covers fixtures, results, standings, teams and competitions, so a list is usually available. Check the documentation for date and competition filters.

Fetch the day’s fixtures once, then slice by team, league or kickoff time in memory.

Step 11: Push instead of poll for live data

Live scores are the hardest data to cache, because a 30-second TTL on a busy match still means two calls a minute. Poll one match for 2 hours and you have spent 240 calls on a single game.

Polling live data on a small quota does not work. Switch to push.

Webhooks: the provider calls your endpoint when something happens (goal, card, full time).
WebSocket API: one persistent connection streams events as they occur.
Live Scores API: the REST endpoint for snapshots when you need current state.

A webhook receiver that writes straight into your cache:

js
import crypto from 'node:crypto';
import express from 'express';

const app = express();

// Verify signatures against the RAW body, so use express.raw here
app.post('/webhooks/sports', express.raw({ type: 'application/json' }), (req, res) => {
const sig = req.get('X-Signature') || ''; // header name: confirm in the webhooks docs
const expected = crypto
.createHmac('sha256', process.env.WEBHOOK_SECRET)
.update(req.body)
.digest('hex');

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

const event = JSON.parse(req.body.toString('utf8'));
client.cache.set(live:${event.match_id}, event, 60_000, 300_000);

res.sendStatus(200); // acknowledge fast, do heavy work elsewhere
});

Pushed events do not count as polling calls, so your live reserve stays untouched. Verify the real signature scheme in the webhook docs before trusting this code.

If you only need a score box on a page, a drop-in widget can remove your live-data work entirely.

Step 12: Measure your hit rate

You cannot protect a quota you do not measure. Expose three numbers:

js
app.get('/internal/metrics', (_req, res) => {
res.json({
hitRate: client.hitRate(), // target: above 0.985
callsRemaining: client.budget.remaining(),
...client.stats,
});
});

Check them like this:

Hit rate below 95%? A TTL is too short, or a cache key is unstable (unsorted params, timestamps in the URL).
callsRemaining falling fast in the morning? A warmer is running too often.
Many stale-if-error responses? Check the upstream status page, then your network.

Step 13: Test without spending a single call

Here is the most useful habit on a small quota: never spend real calls on testing your cache. Stub fetch and assert on call counts.

js
import assert from 'node:assert';
import { SportsClient } from './client.js';

const calls = [];
globalThis.fetch = async (url) => {
calls.push(String(url));
return new Response(JSON.stringify({ table: [] }), { status: 200 });
};

const client = new SportsClient({ apiKey: 'test' });

// 200 simultaneous users, one standings table
await Promise.all(
Array.from({ length: 200 }, () =>
client.get('/football/standings', { ttlMs: 60_000 })
)
);

assert.equal(calls.length, 1, 'single-flight should collapse 200 calls into 1');
console.log('OK, network calls:', calls.length);

One practical tip: Orbistats access works in time windows. The Free plan is one hour with no card, and the timer starts when you open your activation link. Starter is 24 hours and Growth is five days, with every sport and endpoint on every plan. Current details are on the pricing page.

So build and test everything above locally, with stubbed responses, before you start the clock. Steps 1 to 12 need no live data. Then spend your window verifying real payloads and field names, using the sandbox and SDKs, and let one real match prove the pipeline.

Step 14: Production hardening checklist

The tutorial version is correct. A production version is also operable:

Persist the budget in Redis. An in-memory counter resets on every deploy. Use an atomic increment:
js
const key = budget:${new Date().toISOString().slice(0, 10)};
const used = await redis.incr(key);
if (used === 1) await redis.expire(key, 129_600); // 36 hours
if (used > ceiling) { await redis.decr(key); return false; }
Move the cache to Redis too if you run more than one server. Otherwise each instance warms its own copy and multiplies your calls.
Run warmers in a single process. Two warmers means double spend. Use one worker or a distributed lock.
Add jitter to TTLs. If 13 sports all expire at the same second, you create your own stampede. Add 5-10% random variation.
Alert at 80% quota. Page yourself before the limit, not after.
Cache errors briefly. If an endpoint returns 404 or 5xx, remember that for 30-60 seconds so retries do not burn calls.
Log the source of every response (cache, stale, network). It makes debugging trivial.
Watch the changelog. Field changes can silently break cached payload shapes. Follow the changelog and version your cache keys (v1:).
Know when to upgrade. If your hit rate is above 98% and you still run out, you have outgrown the free tier. That is a good problem, and the comparison pages show how providers stack up.

Wrapping up

Surviving a tiny quota is not about clever tricks. It is about never asking the same question twice:

Give each data type its own TTL
Collapse duplicate requests with single-flight
Serve stale data on purpose
Guard the budget with a live reserve
Store immutable data forever
Warm caches from schedules, not users
Push, don’t poll, for live data

Do these and 150 calls a day can comfortably serve thousands of users.

Want to try it on real data? Request access, and keep the glossary and odds converter tools handy if you plan to add the Odds API later.

What caching trick saved your quota? Tell me in the comments.

Live Score Widget in React: Embed or Build It in 10 Minutes

orbistats — Sat, 10 Oct 2026 12:26:47 +0000

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

Odds Converter in JS & Python: Decimal, American, Fractional

orbistats — Sat, 10 Oct 2026 12:18:52 +0000

Open any two sports betting sites and you will probably see the same price written in two different ways. One shows 2.50, another shows +150, and a third shows 3/2. A British horse racing site, a US NFL app and a European football portal can all be describing the exact same bet, and your code has to make sense of all three.

If you are building a sports app, an odds comparison page, a trading dashboard or a betting model, an odds converter is one of the first utilities you will write. It looks trivial. It is not. Rounding, ambiguous inputs, the "even money" edge case, floating point errors and bookmaker margin all show up the moment you ship it to real users.

In this guide we will build a production-minded odds converter in both JavaScript and Python. Along the way you will learn:

how decimal, American and fractional odds relate to each other (with the exact formulas)
how to calculate implied probability from any format
how to measure the bookmaker's margin (the overround or vig) and strip it out to get fair probabilities
the edge cases that break naive converters
how to wire the converter to a real sports odds API so users see prices in the format they prefer

Everything below was run and tested: 23 pytest cases for Python and 8 node:test cases for JavaScript, including a Python/JS parity check so both implementations return identical results. If you just want to try the maths in a browser first, Orbistats has a free odds converter you can poke at while you read.

A quick note. This article is about data handling and engineering. It is not betting advice, and betting is for adults (18+, or the legal age where you live) only. Please gamble responsibly.

TL;DR: the formulas

Keep this table handy. Everything else in the article is just these six lines done carefully.

From To Formula
American > 0 Decimal 1 + american / 100
American < 0 Decimal 1 + 100 / abs(american)
Fractional n/d Decimal 1 + n / d
Decimal >= 2.0 American (decimal - 1) * 100
Decimal < 2.0 American -100 / (decimal - 1)
Decimal Implied probability 1 / decimal

The big idea is to pick one internal format and convert only at the edges. We will use decimal odds internally, because every other format converts to and from decimal with one line of maths, and because probabilities and payouts are trivial in decimal.

Why three odds formats exist in the first place

Odds are a price: they tell you how much you win relative to what you stake. The three common formats are simply three conventions for writing that ratio.

Decimal odds (also called European odds) are the total return per 1 unit staked, including your stake. At 2.50, a 10 unit stake returns 25 units, which is 15 profit plus your 10 back. This is the default in continental Europe, Australia, Canada and most modern odds feeds, and it is the format football data for 1X2 markets is usually published in.

American odds (moneyline odds) are anchored to 100 units. A positive number such as +150 is the profit on a 100 unit stake. A negative number such as -110 is the stake you need to risk to win 100. Because US sportsbooks think in these terms, they dominate American football, basketball and baseball pricing.

Fractional odds are the traditional UK and Ireland format: 5/2 means you win 5 for every 2 staked. They are still the standard on horse racing cards, and you will also see them in futures markets and in many UK bookmaker apps.

There are other formats (Hong Kong, Malay, Indonesian), but if you can handle the big three and probabilities, the rest are small variations. If any of the terms in this article are new to you, the odds and implied probability glossary explains them in plain English.

Step 1: Understand the maths with one worked example

Let's use a real-looking football price: decimal 3.40 for an away win.

Decimal: 3.40. A 10 stake returns 34.
American: since 3.40 is above 2.0, (3.40 - 1) * 100 = +240.
Fractional: 3.40 - 1 = 2.40, and 2.40 as a fraction is 12/5.
Implied probability: 1 / 3.40 = 0.2941, or 29.41%.

Now go the other way. If someone hands you +240, you compute 1 + 240/100 = 3.40. If they hand you 12/5, you compute 1 + 12/5 = 3.40. Same price, three costumes.

Here is the small reference table the code below produces. Use it as a sanity check for your own implementation:

Decimal American Fractional Implied probability
1.20 -500 1/5 83.33%
1.50 -200 1/2 66.67%
1.91 -110 10/11 52.36%
2.50 +150 3/2 40.00%
3.40 +240 12/5 29.41%
4.20 +320 16/5 23.81%
11.00 +1000 10/1 9.09%

Notice that 1.91 is the famous -110 line. It is the standard price on a two-way US market, and it is not a coincidence that the implied probability of 52.36% is over 50%. We will come back to that when we talk about the margin.

Step 2: The Python converter

Create a file called odds.py. We use Python's built-in fractions.Fraction to turn a decimal into the nicest small fraction, and we validate every input so that bad data fails loudly instead of silently producing nonsense.

python
"""odds.py - convert between decimal, American and fractional odds."""
from future import annotations

import math
from fractions import Fraction
from typing import Sequence

class OddsError(ValueError):
"""Raised when an odds value is invalid."""

def _check_decimal(decimal: float) -> float:
if isinstance(decimal, bool) or not isinstance(decimal, (int, float)):
raise OddsError(f"decimal odds must be a number, got {decimal!r}")
if not math.isfinite(decimal) or decimal <= 1.0:
raise OddsError(f"decimal odds must be a finite number > 1.0, got {decimal!r}")
return float(decimal)

def american_to_decimal(american: float) -> float:
if not math.isfinite(american) or -100 < american < 100:
raise OddsError(f"American odds must be <= -100 or >= +100, got {american!r}")
if american > 0:
return 1 + american / 100
return 1 + 100 / abs(american)

def decimal_to_american(decimal: float) -> int:
d = _check_decimal(decimal)
if d >= 2.0:
return round((d - 1) * 100) # underdog: +150, +250 ...
return round(-100 / (d - 1)) # favourite: -110, -200 ...

def fractional_to_decimal(fractional: str) -> float:
text = fractional.strip().lower()
if text in {"evens", "evs", "even"}:
return 2.0
try:
num_s, den_s = text.split("/")
num, den = int(num_s), int(den_s)
except ValueError as exc:
raise OddsError(f"fractional odds must look like '5/2', got {fractional!r}") from exc
if num <= 0 or den <= 0:
raise OddsError(f"numerator and denominator must be positive, got {fractional!r}")
return 1 + num / den

def decimal_to_fractional(decimal: float, max_denominator: int = 20) -> str:
d = _check_decimal(decimal)
frac = Fraction(d - 1).limit_denominator(max_denominator)
if frac == 0: # very short prices such as 1.01
frac = Fraction(d - 1).limit_denominator(1000)
return f"{frac.numerator}/{frac.denominator}"

A few design decisions worth explaining:

Decimal is the pivot. There is no american_to_fractional(). To convert between any two formats you go through decimal. That keeps the number of functions linear instead of quadratic, and it means there is exactly one place where each format's rules live.

max_denominator=20 is deliberate. The decimal 1.91 is really 91/100 as a fraction, but no bookmaker prints that. They print 10/11. Limiting the denominator gives you the "bookmaker-looking" fraction. If you need an exact fraction, raise the limit.

The 1.01 fallback matters. At very short prices such as 1.01, limit_denominator(20) rounds the fraction to zero, which would print 0/1. Falling back to a denominator of 1000 returns the correct 1/100.

Americans between -100 and +100 are invalid. There is no such thing as +50 or -50 in American odds. Those values almost always mean the data is corrupted or in a different format, so we reject them.

Now the probability helpers, which are the bit most tutorials skip:

python
def implied_probability(decimal: float) -> float:
return 1 / _check_decimal(decimal)

def probability_to_decimal(probability: float) -> float:
if not 0 < probability < 1:
raise OddsError(f"probability must be between 0 and 1 (exclusive), got {probability!r}")
return 1 / probability

def overround(decimals: Sequence[float]) -> float:
"""Bookmaker margin: sum of implied probabilities minus 1."""
return sum(implied_probability(d) for d in decimals) - 1

def remove_vig(decimals: Sequence[float]) -> list[float]:
"""Proportional (multiplicative) de-vig: fair probabilities that sum to 1."""
probs = [implied_probability(d) for d in decimals]
total = sum(probs)
return [p / total for p in probs]

def to_decimal(value, fmt: str) -> float:
if fmt == "decimal":
return _check_decimal(float(value))
if fmt == "american":
return american_to_decimal(float(value))
if fmt == "fractional":
return fractional_to_decimal(str(value))
raise OddsError(f"unknown format {fmt!r}")

def convert_all(decimal: float) -> dict:
"""Every representation of one price - handy for UIs and debugging."""
return {
"decimal": round(decimal, 3),
"american": decimal_to_american(decimal),
"fractional": decimal_to_fractional(decimal),
"implied_probability": round(implied_probability(decimal), 4),
}

Try it in a REPL:

python

from odds import convert_all, to_decimal
convert_all(3.40)
{'decimal': 3.4, 'american': 240, 'fractional': '12/5', 'implied_probability': 0.2941}
convert_all(to_decimal("+150", "american"))
{'decimal': 2.5, 'american': 150, 'fractional': '3/2', 'implied_probability': 0.4}
to_decimal("evens", "fractional")
2.0
Step 3: The JavaScript converter

The same logic in modern ES modules, with no dependencies. JavaScript has no built-in Fraction, so decimalToFractional searches denominators from 1 up to the limit and keeps the closest match, preferring the smaller denominator on ties. That gives exactly the same answers as Python's limit_denominator.

Create odds.mjs:

js
// odds.mjs - convert between decimal, American and fractional odds.

export class OddsError extends Error {
constructor(message) {
super(message);
this.name = "OddsError";
}
}

const assertDecimal = (d) => {
if (typeof d !== "number" || !Number.isFinite(d) || d <= 1) {
throw new OddsError(decimal odds must be a finite number > 1, got ${d});
}
return d;
};

export const americanToDecimal = (a) => {
if (typeof a !== "number" || !Number.isFinite(a) || (a > -100 && a < 100)) {
throw new OddsError(American odds must be <= -100 or >= +100, got ${a});
}
return a > 0 ? 1 + a / 100 : 1 + 100 / Math.abs(a);
};

export const decimalToAmerican = (d) => {
assertDecimal(d);
return d >= 2 ? Math.round((d - 1) * 100) : Math.round(-100 / (d - 1));
};

export const fractionalToDecimal = (text) => {
const t = String(text).trim().toLowerCase();
if (["evens", "evs", "even"].includes(t)) return 2;
const m = /^(\d+)\s*\/\s*(\d+)$/.exec(t);
if (!m) throw new OddsError(fractional odds must look like "5/2", got "${text}");
const [num, den] = [Number(m[1]), Number(m[2])];
if (num <= 0 || den <= 0) throw new OddsError(numerator and denominator must be positive: "${text}");
return 1 + num / den;
};

// Best fraction with a denominator <= maxDen (smallest denominator wins ties).
export const decimalToFractional = (d, maxDen = 20) => {
assertDecimal(d);
const target = d - 1;
const search = (limit) => {
let best = { num: 1, den: 1, err: Infinity };
for (let den = 1; den <= limit; den++) {
const num = Math.round(target * den);
if (num <= 0) continue;
const err = Math.abs(target - num / den);
if (err < best.err - 1e-12) best = { num, den, err };
}
return best;
};
const best = Number.isFinite(search(maxDen).err) ? search(maxDen) : search(1000);
return ${best.num}/${best.den};
};

export const impliedProbability = (d) => 1 / assertDecimal(d);

export const overround = (decimals) =>
decimals.reduce((sum, d) => sum + impliedProbability(d), 0) - 1;

export const removeVig = (decimals) => {
const probs = decimals.map(impliedProbability);
const total = probs.reduce((a, b) => a + b, 0);
return probs.map((p) => p / total);
};

// Guess the format of a user-typed string. Bare integers are ambiguous on purpose.
export const detectFormat = (raw) => {
const s = String(raw).trim();
if (s.includes("/") || /^(evens|evs|even)$/i.test(s)) return "fractional";
if (/^[+-]\d+$/.test(s)) return "american";
if (/^\d+([.,]\d+)?$/.test(s) && /[.,]/.test(s)) return "decimal";
throw new OddsError(cannot tell the format of "${raw}" - pass it explicitly);
};

export const toDecimal = (value, format = detectFormat(value)) => {
switch (format) {
case "decimal": return assertDecimal(Number(String(value).replace(",", ".")));
case "american": return americanToDecimal(Number(value));
case "fractional": return fractionalToDecimal(value);
default: throw new OddsError(unknown format "${format}");
}
};

export const convertAll = (d) => ({
decimal: Number(d.toFixed(3)),
american: decimalToAmerican(d),
fractional: decimalToFractional(d),
impliedProbability: Number(impliedProbability(d).toFixed(4)),
});

And in Node:

js
import { convertAll, toDecimal } from "./odds.mjs";

console.log(convertAll(3.4));
// { decimal: 3.4, american: 240, fractional: '12/5', impliedProbability: 0.2941 }

console.log(toDecimal("+150")); // 2.5 (format auto-detected: American)
console.log(toDecimal("5/2")); // 3.5 (fractional)
console.log(toDecimal("2,50")); // 2.5 (European decimal comma)
Why detectFormat refuses to guess "150"

Look at the detectFormat function again. A string like "+150" is clearly American, and "5/2" is clearly fractional. But what is a bare "150"? It could be American +150 typed without the sign, or an absurdly long decimal price. We throw an error instead of guessing. In a betting context a silent wrong guess is far worse than a loud failure: if you read 150 as decimal you have just priced a 1% outcome as a near-certainty. When you control the UI, always have the user (or the data source) tell you the format explicitly.

Step 4: Test it properly

Odds code is exactly the sort of thing that looks right and is subtly wrong. Write tests before you trust it. The most valuable tests are round trips and known reference values.

Python (test_odds.py, run with pytest):

python
import pytest
from odds import *

@pytest.mark.parametrize("american,decimal", [
(150, 2.5), (-110, 1.9091), (100, 2.0), (-100, 2.0), (-200, 1.5), (250, 3.5),
])
def test_american_to_decimal(american, decimal):
assert american_to_decimal(american) == pytest.approx(decimal, abs=1e-4)

@pytest.mark.parametrize("decimal,frac", [
(3.5, "5/2"), (1.91, "10/11"), (2.0, "1/1"), (1.25, "1/4"), (1.01, "1/100"),
])
def test_decimal_to_fractional(decimal, frac):
assert decimal_to_fractional(decimal) == frac

def test_round_trip_american():
for a in [-1000, -250, -110, -101, 100, 105, 150, 400, 1200]:
assert decimal_to_american(american_to_decimal(a)) == a

def test_invalid_inputs():
for bad in [0, 50, -50]:
with pytest.raises(OddsError):
american_to_decimal(bad)
for bad in [1.0, 0.5, -3, float("nan")]:
with pytest.raises(OddsError):
decimal_to_american(bad)
with pytest.raises(OddsError):
fractional_to_decimal("2.5") # that's decimal, not fractional

JavaScript (odds.test.mjs, run with node --test):

js
import test from "node:test";
import assert from "node:assert/strict";
import * as o from "./odds.mjs";

test("round trip american", () => {
for (const a of [-1000, -250, -110, -101, 100, 105, 150, 400, 1200]) {
assert.equal(o.decimalToAmerican(o.americanToDecimal(a)), a);
}
});

test("python parity", () => {
assert.deepEqual(o.convertAll(3.4), {
decimal: 3.4, american: 240, fractional: "12/5", impliedProbability: 0.2941,
});
});

test("invalid input", () => {
assert.throws(() => o.americanToDecimal(50), o.OddsError);
assert.throws(() => o.detectFormat("150"), o.OddsError);
});

The "parity" test is a nice trick if you maintain both a backend (Python) and a frontend (JavaScript). Pin the same few known outputs in both test suites and you will catch drift the day somebody "improves" one implementation.

Step 5: Implied probability, the overround and fair odds

Converting formats is the easy half. The half that makes your app genuinely useful is understanding what a price is telling you about probability.

For decimal odds, implied probability = 1 / decimal. A price of 2.00 implies 50%. A price of 4.00 implies 25%.

Now take a three-way football market (home / draw / away) with these decimal prices:

Outcome Decimal Implied probability
Home 1.91 52.36%
Draw 3.40 29.41%
Away 4.20 23.81%
Total 105.58%

A real market's outcomes are mutually exclusive and exhaustive, so true probabilities must add up to exactly 100%. These add up to 105.58%. The extra 5.58% is the bookmaker's built-in margin, called the overround (or vig or juice in the US). It is how bookmakers get paid regardless of the result.

python
from odds import overround, remove_vig, probability_to_decimal

market = [1.91, 3.40, 4.20]

print(f"overround: {overround(market):.2%}") # overround: 5.58%

fair = remove_vig(market)
print([f"{p:.2%}" for p in fair]) # ['49.59%', '27.86%', '22.55%']
print([round(probability_to_decimal(p), 2) for p in fair]) # [2.02, 3.59, 4.43]

The method used here is the proportional (multiplicative) de-vig: divide each implied probability by the total. It is simple, fast and a perfectly good default. Be aware that it spreads the margin evenly across outcomes. Real bookmakers often load more margin onto longshots, so more advanced methods (power method, Shin's method, additive) exist and can give slightly different fair probabilities. For a first version, proportional is the right call. Just don't present the output as "the truth", present it as "the market's margin-free estimate".

The same maths in JavaScript:

js
import { overround, removeVig } from "./odds.mjs";

const market = [1.91, 3.4, 4.2];
console.log((overround(market) * 100).toFixed(2) + "%"); // 5.58%
console.log(removeVig(market).map((p) => (p * 100).toFixed(2) + "%")); // [ '49.59%', '27.86%', '22.55%' ]

Why does this matter for your product? A few examples:

Odds comparison pages can show "best price" and the margin, so users see which bookmaker is genuinely cheapest.
Trading dashboards compare each book's fair probabilities against a sharp reference line.
Models and backtests need fair probabilities, not margin-inflated ones, to measure calibration. We touch on that near the end.
Step 6: Edge cases that break naive converters

Here is the checklist I wish I had before shipping my first converter.

Even money has three faces. 2.00, +100, -100 and 1/1 ("evens") are all the same price. Make sure -100 and +100 both convert to 2.0, and decide which one you print on the way out. In this article 2.0 prints as +100 and 1/1. Both fractions and Americans round-trip fine.
Don't use floats for money. Our converter returns floats, which is fine for prices and probabilities. The moment you calculate a payout or stake, switch to Decimal in Python, or integer minor units (cents) in JavaScript:

python
from decimal import Decimal, ROUND_HALF_UP

def payout(stake: Decimal, decimal_odds: Decimal) -> Decimal:
return (stake * decimal_odds).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)

payout(Decimal("10.00"), Decimal("2.50")) # Decimal('25.00')

Rounding is a product decision. American odds are integers, so 1.91 becomes -110 (really -109.89). Converting back gives 1.9091, not 1.91. Never compare a converted-and-back value with ==; compare within a tolerance, as in our tests. Also note that Python's round() uses banker's rounding on exact halves, while JavaScript's Math.round() rounds .5 toward positive infinity. For real prices the difference almost never appears, but now you know where to look if a value is off by one.
Locale decimal commas. In much of Europe 2,50 is the decimal price. Parse input with care (our toDecimal swaps the comma for a dot) and never let parseFloat("2,50") quietly return 2.
Minimum prices. Decimal odds must be greater than 1.0. A decimal of exactly 1.00 means you win nothing. Some feeds send 0 or null for suspended markets. Reject them or you will end up dividing by zero.
Suspended and missing markets. When odds disappear mid-match (a goal was scored, the market is suspended), your UI should show "suspended", not a stale or converted zero. Treat null/undefined as a state, not as a number.
Cache the formatted value, not the format. Store and cache decimal prices. Format at render time based on the user's preference. If you cache "-110" strings you will have to invalidate them whenever a user flips their format setting.

Step 7: Plug the converter into a real odds API

A converter is most useful when it sits between a live odds feed and the user's screen. The feed gives you one canonical format (usually decimal), and your converter shows each user the format they expect: American for a US visitor, fractional for UK racing fans, decimal for everyone else.

For a data source we will use the Orbistats Odds API, which returns pre-match and live odds normalized into one format across sportsbooks. That is the point of an odds API: you do not write a parser per bookmaker. Per the odds endpoint reference, the endpoint is:

GET https://api.orbistats.com/v1/{sport}/odds?match_id={fixture_id}&market=1x2
Authorization: Bearer YOUR_API_KEY

and a 1X2 response looks like this (all Orbistats responses share a data / meta / errors envelope):

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

The odds endpoint is listed on the Growth+ plan in the API reference, so check the pricing page for the current plan details. The converter itself works fully offline, so you can follow every earlier step without a key. If you want to explore responses before writing any code, the API sandbox lets you try endpoints against sample data, and the quickstart guide walks you from signup to first request.

Python client
python
import os
import requests
from odds import convert_all, overround

BASE = "https://api.orbistats.com/v1"

def get_odds(sport: str, match_id: str, market: str = "1x2") -> dict:
resp = requests.get(
f"{BASE}/{sport}/odds",
params={"match_id": match_id, "market": market},
headers={"Authorization": f"Bearer {os.environ['ORBISTATS_API_KEY']}"},
timeout=10,
)
if resp.status_code == 429:
wait = resp.headers.get("Retry-After", "1")
raise RuntimeError(f"Rate limited, retry in {wait}s")
resp.raise_for_status() # 401 bad key, 403 plan, 404 unknown match ...
return resp.json()["data"]

def price_table(odds: dict, style: str = "american") -> dict:
"""Return home/draw/away formatted in the user's preferred style."""
return {side: convert_all(odds[side])[style] for side in ("home", "draw", "away")}

if name == "main":
data = get_odds("football", "fx_884213")
print(price_table(data, "american")) # {'home': -110, 'draw': 240, 'away': 320}
print(price_table(data, "fractional")) # {'home': '10/11', 'draw': '12/5', 'away': '16/5'}
print(f"margin: {overround([data['home'], data['draw'], data['away']]):.2%}") # margin: 5.58%
JavaScript client
js
import { convertAll, overround } from "./odds.mjs";

const BASE = "https://api.orbistats.com/v1";

export async function getOdds(sport, matchId, market = "1x2") {
const url = new URL(${BASE}/${sport}/odds);
url.search = new URLSearchParams({ match_id: matchId, market });

const res = await fetch(url, {
headers: { Authorization: Bearer ${process.env.ORBISTATS_API_KEY} },
});

if (res.status === 429) {
const wait = Number(res.headers.get("Retry-After") ?? 1);
throw Object.assign(new Error("Rate limited"), { retryAfter: wait });
}
if (!res.ok) throw new Error(Orbistats ${res.status}: ${await res.text()});

return (await res.json()).data;
}

export const priceTable = (odds, style = "american") =>
Object.fromEntries(["home", "draw", "away"].map((s) => [s, convertAll(odds[s])[style]]));

// usage
const data = await getOdds("football", "fx_884213");
console.log(priceTable(data, "fractional")); // { home: '10/11', draw: '12/5', away: '16/5' }
console.log((overround([data.home, data.draw, data.away]) * 100).toFixed(2) + "%"); // 5.58%

I verified the conversion and margin logic above against the example response using a mocked HTTP layer. Treat the field names as defined by the live API reference, because feeds differ per plan and per market (player props, totals and so on have different shapes). If you use an official client, the SDKs cover Python, JavaScript, TypeScript, PHP, Java, C#, Go and Ruby with the same method names as the REST endpoints.

Don't poll live odds, subscribe

Prices move every few seconds during a live match. Polling the REST endpoint in a loop wastes your request quota and still shows stale prices. For live boards, a push connection is the better fit. Orbistats offers a WebSocket API for a persistent low-latency stream and webhooks (including an odds.changed event) that push updates to your server the moment something changes.

The converter slots straight in, because conversion is O(1) and cheap enough to run on every tick:

js
import WebSocket from "ws";
import { convertAll } from "./odds.mjs";

const ws = new WebSocket(wss://stream.orbistats.com/v1?token=${process.env.ORBISTATS_API_KEY});

ws.on("open", () => ws.send(JSON.stringify({ subscribe: "football.live" })));

ws.on("message", (raw) => {
const msg = JSON.parse(raw);
// Illustrative: adapt these field names to the message shape in the WebSocket docs.
if (typeof msg.odds?.home === "number") {
console.log(msg.fixture_id, convertAll(msg.odds.home).american);
}
});
Where this goes next: backtesting and models

Once you can turn any price into a probability, a lot of doors open. With multi-season closing odds, you can convert each closing price to a fair probability (remove the vig first), compare it to what actually happened, and build a calibration curve: of all the matches where the market said 60%, did the home team really win about 60% of the time? That is the foundation of most betting-model backtests, and it is exactly the use case the Historical Sports Data API is built for. The loop is always the same: fetch history, convert to probabilities, strip the margin, compare with outcomes.

Production checklist

Before you ship your converter, run through this list:

One internal format (decimal), convert only at the UI edge
Every function validates input and throws a clear error
-100 and +100 both map to 2.0
Bare numbers are never auto-detected as a format
Money uses Decimal or integer cents, never floats
Round trips are tested with a tolerance, not ==
Suspended or null markets render as "suspended", not 0
Python and JS implementations share a parity test
The user's preferred format is stored as a setting, not baked into cached data
You show the overround where it helps users judge value
FAQ

How do I convert decimal odds to American odds? If the decimal price is 2.00 or higher, subtract 1 and multiply by 100 (2.50 becomes +150). If it is below 2.00, divide -100 by the decimal minus 1 (1.91 becomes -110).

How do I convert fractional odds to decimal? Divide the numerator by the denominator and add 1. So 5/2 is 1 + 5/2 = 3.50, and "evens" (1/1) is 2.00.

What is implied probability in betting? It is the chance of an outcome that is suggested by the odds. For decimal odds it is 1 divided by the price, so 4.00 implies 25%. When you add up the implied probabilities for every outcome in a market, the total is usually above 100%, and the surplus is the bookmaker's margin.

What is the overround (vig)? The overround is the sum of the implied probabilities of all outcomes minus 1. In our football example it is 5.58%. A lower overround means a better price for the bettor.

Should I store odds as decimal, American or fractional? Store decimal (or the probability) and convert for display. Decimal converts to the others with one formula and works directly in payout and probability maths.

Which sports does Orbistats cover? Thirteen sports at the time of writing: football, basketball, American football, cricket, tennis, baseball, esports, combat sports, volleyball, handball, ice hockey, golf and horse racing. Depth varies by sport and by endpoint, so check the coverage details before you build.

Wrapping up

An odds converter is a small piece of code with a surprising number of ways to go wrong. If you remember only four things, make them these:

Keep decimal odds as your internal format and convert at the edges.
Validate everything. Reject 0, 1.0, +50 and bare ambiguous numbers.
Convert prices to implied probabilities, and strip the overround before treating them as fair.
Test with round trips and reference values, and share a parity test between languages.

If you want live prices to feed the converter, you can get a free API key from Orbistats and try the odds endpoints in the sandbox. And if you build something with it, such as an odds comparison page, a margin tracker or a live ticker, I would love to see it in the comments.

Disclosure: I build Orbistats. Betting involves risk and is for adults only. This article is for educational and engineering purposes and is not betting advice.

Build a Webhook Receiver for Live Sports Events in Node.js (Retries, Idempotency, Signature Checks)

orbistats — Sat, 10 Oct 2026 12:11:01 +0000

Last month we published a minimal webhook receiver in Go. It ended with a question: how do you handle retries and idempotency? This post is the full answer, in Node.js.

By the end you’ll have a receiver that:

Verifies signatures on the raw request bytes, with a constant-time compare and secret rotation
Acknowledges in milliseconds and never does slow work on the request path
Deduplicates retried deliveries, so a goal is never counted twice
Retries failed processing with exponential backoff and jitter, then parks poison messages in a dead-letter state
Reconciles against the REST API, so a missed webhook doesn’t become a permanently wrong score
Ships with tests and a script that simulates signed deliveries locally

Everything runs on Node 20+ with three dependencies.

Why webhooks (and when to use something else)

A webhook means the provider calls you when something happens, so you never poll. That’s ideal for server-side triggers: notifications, score updates in your database, downstream jobs.

If you need a continuous live stream for a UI, a WebSocket is the better transport, and our 50-line WebSocket scoreboard tutorial shows that side. A common pattern is both: WebSocket for the browser, webhooks for backend logic. Live odds can also arrive over webhooks, as described on the Odds API page.

Read this before you copy the code

I want to be upfront about what is verified and what isn’t, because webhook bugs are expensive.

Topic Status in this tutorial
Webhooks exist and push events to your endpoint Documented
Registering an endpoint needs an API key Documented, see the API reference
Event payload field names (type, match_id, minute, team) Assumed, modeled on the Go tutorial and the documented WebSocket event. Check real payloads in the sandbox
Signature header name, algorithm, encoding Not assumed. All three are environment variables below. Confirm them in the webhooks docs
Retry schedule and delivery guarantees Not assumed. The code is built for the safe worst case: at-least-once delivery, duplicates, and out-of-order events

That last row is the design principle. If your receiver is correct under at-least-once delivery, it’s correct under every stricter guarantee too.

The architecture
text
Provider ──POST──▶ /webhooks/orbistats
│
1. verify signature (raw bytes)
2. parse + validate (zod)
3. INSERT into inbox ← idempotency key = PRIMARY KEY
4. respond 200 immediately
│
▼
inbox table (durable)
│
worker: claim → handle → done
│ failure
├──▶ retry with backoff
└──▶ dead after N attempts

Safety net: REST poll ──▶ compare with local state ──▶ log drift

This is the transactional inbox pattern. The request handler does exactly two things: prove the sender is authentic, and durably write the event. Everything else happens later, off the request path. That one decision removes most webhook failure modes: timeouts, lost events on crash, and double processing.

Step 1: Project setup
bash
mkdir webhook-receiver && cd webhook-receiver
npm init -y
npm install express zod better-sqlite3
mkdir src scripts test

Edit package.json:

json
{
"name": "orbistats-webhook-receiver",
"private": true,
"type": "module",
"engines": { "node": ">=20.6" },
"scripts": {
"start": "node --env-file=.env src/index.js",
"send": "node --env-file=.env scripts/send-test-event.js",
"test": "node --test"
},
"dependencies": {
"better-sqlite3": "^11.0.0",
"express": "^4.21.0",
"zod": "^3.23.0"
}
}

(Versions are those current at writing; use the latest compatible releases.) Node 20.6+ supports --env-file, so we don’t need dotenv.

Create .env.example and copy it to .env:

bash
PORT=8080
DB_PATH=webhooks.db

Comma-separated: lets you rotate secrets without downtime

WEBHOOK_SECRET=change-me

CONFIRM THESE THREE in the webhooks docs. Do not assume.

WEBHOOK_SIGNATURE_HEADER=x-signature
WEBHOOK_SIGNATURE_ENCODING=hex
WEBHOOK_SIGNATURE_PREFIX=

Optional: header carrying a unique delivery/event ID, if the docs define one

WEBHOOK_DELIVERY_ID_HEADER=

MAX_ATTEMPTS=6
ORBISTATS_API_KEY=
Step 2: Configuration

src/config.js:

javascript
const required = (name) => {
const v = process.env[name];
if (!v) throw new Error(Missing env var ${name});
return v;
};

export const config = {
port: Number(process.env.PORT ?? 8080),
dbPath: process.env.DB_PATH ?? "webhooks.db",

secrets: required("WEBHOOK_SECRET").split(",").map((s) => s.trim()),
signatureHeader: (process.env.WEBHOOK_SIGNATURE_HEADER ?? "x-signature").toLowerCase(),
signatureEncoding: process.env.WEBHOOK_SIGNATURE_ENCODING ?? "hex", // "hex" | "base64"
signaturePrefix: process.env.WEBHOOK_SIGNATURE_PREFIX ?? "", // e.g. "sha256="
deliveryIdHeader: (process.env.WEBHOOK_DELIVERY_ID_HEADER ?? "").toLowerCase(),

maxAttempts: Number(process.env.MAX_ATTEMPTS ?? 6),
apiKey: process.env.ORBISTATS_API_KEY ?? "",
};

Failing at startup on a missing secret is deliberate. A receiver that silently runs without verification is worse than one that refuses to boot.

Step 3: The inbox table

src/db.js:

javascript
import Database from "better-sqlite3";
import { config } from "./config.js";

export const db = new Database(config.dbPath);
db.pragma("journal_mode = WAL");

db.exec(`
CREATE TABLE IF NOT EXISTS inbox (
idempotency_key TEXT PRIMARY KEY,
received_at INTEGER NOT NULL,
event_type TEXT,
match_id TEXT,
payload TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'pending', -- pending | done | dead
attempts INTEGER NOT NULL DEFAULT 0,
next_attempt_at INTEGER NOT NULL,
last_error TEXT
);
CREATE INDEX IF NOT EXISTS idx_inbox_due ON inbox (status, next_attempt_at);

-- Domain table: one row per goal event, keyed so duplicates are harmless
CREATE TABLE IF NOT EXISTS goals (
idempotency_key TEXT PRIMARY KEY,
match_id TEXT NOT NULL,
team TEXT,
minute INTEGER
);
`);

Notice the idempotency key is a primary key. The database, not your application code, guarantees uniqueness, so two concurrent retries can’t both win a race.

SQLite keeps this tutorial self-contained. The same schema works in Postgres, and I show the multi-worker version later.

Step 4: Signature verification (on the raw bytes)

This is where most receivers go wrong, so slow down.

An HMAC signature is computed over the exact bytes the sender transmitted. If you let a JSON middleware parse the body first and then re-serialize it, key order and whitespace can change and every signature will fail (or, worse, you’ll “fix” it by skipping verification). We capture the raw Buffer and verify that.

src/signature.js:

javascript
import crypto from "node:crypto";
import { config } from "./config.js";

export function computeSignature(rawBody, secret, encoding = config.signatureEncoding) {
return crypto.createHmac("sha256", secret).update(rawBody).digest(encoding);
}

export function verifySignature(rawBody, headerValue) {
if (!headerValue) return false;

const received =
config.signaturePrefix && headerValue.startsWith(config.signaturePrefix)
? headerValue.slice(config.signaturePrefix.length)
: headerValue;
const receivedBuf = Buffer.from(received.trim());

// Try every configured secret so rotation never drops events
return config.secrets.some((secret) => {
const expected = Buffer.from(computeSignature(rawBody, secret));
return (
expected.length === receivedBuf.length &&
crypto.timingSafeEqual(expected, receivedBuf)
);
});
}

Three details matter here:

timingSafeEqual, not ===. Plain string comparison returns early at the first mismatch, which leaks timing information. timingSafeEqual throws if lengths differ, so we check length first.
Raw bytes in, always. The function takes a Buffer, never a parsed object.
Multiple secrets. During rotation you deploy WEBHOOK_SECRET=new,old, switch the sender, then drop the old one. Zero downtime.

If the docs say the signature covers a timestamp plus the body (many providers do this for replay protection), build the signed string accordingly and reject deliveries older than a few minutes:

javascript
// Only if the docs define a timestamp header. Illustrative.
const age = Math.abs(Date.now() / 1000 - Number(timestampHeader));
if (!Number.isFinite(age) || age > 300) return false;
Step 5: Tolerant payload validation

src/schema.js:

javascript
import { z } from "zod";

export const eventSchema = z
.object({
id: z.union([z.string(), z.number()]).optional(),
type: z.string().optional(),
event: z.string().optional(), // some payloads name it event
match_id: z.union([z.string(), z.number()]).transform(String),
minute: z.number().int().optional(),
team: z.string().optional(),
timestamp: z.string().optional(),
})
.passthrough() // keep unknown fields; providers add them over time
.refine((e) => e.type || e.event, { message: "payload needs type or event" });

export const eventTypeOf = (e) => e.type ?? e.event;

Two choices worth defending:

.passthrough(): APIs add fields without notice. A strict schema turns a harmless addition into an outage.
Accepting type or event: until you’ve inspected real payloads, being liberal in what you accept costs nothing.
Step 6: The HTTP server and the ACK rules

src/server.js:

javascript
import express from "express";
import crypto from "node:crypto";
import { config } from "./config.js";
import { db } from "./db.js";
import { verifySignature } from "./signature.js";
import { eventSchema, eventTypeOf } from "./schema.js";

const insertInbox = db.prepare(INSERT INTO inbox (idempotency_key, received_at, event_type, match_id, payload, next_attempt_at) VALUES (@key, @now, @type, @matchId, @payload, @now) ON CONFLICT(idempotency_key) DO NOTHING);

const insertDead = db.prepare(INSERT INTO inbox (idempotency_key, received_at, payload, status, next_attempt_at, last_error) VALUES (@key, @now, @payload, 'dead', @now, @err) ON CONFLICT(idempotency_key) DO NOTHING);

export function idempotencyKey(req, rawBody, parsed) {
// 1. A delivery/event ID header, if the docs define one
if (config.deliveryIdHeader) {
const h = req.get(config.deliveryIdHeader);
if (h) return hdr:${h};
}
// 2. An ID inside the payload
if (parsed?.id !== undefined) return id:${parsed.id};
// 3. Fallback: hash of the exact bytes (retries resend identical bodies)
return sha:${crypto.createHash("sha256").update(rawBody).digest("hex")};
}

export function createApp() {
const app = express();
app.disable("x-powered-by");

app.get("/healthz", (_req, res) => res.json({ ok: true }));

app.post(
"/webhooks/orbistats",
express.raw({ type: "/", limit: "256kb" }), // raw Buffer, not parsed JSON
(req, res) => {
const rawBody = req.body;
if (!Buffer.isBuffer(rawBody) || rawBody.length === 0) {
return res.status(400).json({ error: "empty body" });
}

  // 1. Authenticity first. Nothing below runs for forged requests.
  if (!verifySignature(rawBody, req.get(config.signatureHeader))) {
    return res.status(401).json({ error: "invalid signature" });
  }

  // 2. Parse and validate
  const text = rawBody.toString("utf8");
  let parsed;
  let parseError;
  try {
    const result = eventSchema.safeParse(JSON.parse(text));
    if (result.success) parsed = result.data;
    else parseError = result.error.message;
  } catch (e) {
    parseError = `invalid JSON: ${e.message}`;
  }

  const key = idempotencyKey(req, rawBody, parsed);
  const now = Date.now();

  try {
    // 3. Authentic but unusable: keep it for inspection, but still ACK
    if (!parsed) {
      insertDead.run({ key, now, payload: text, err: parseError });
      return res.status(200).json({ status: "stored_unparsed" });
    }

    // 4. Durable write. `changes` is 0 when the key already exists.
    const info = insertInbox.run({
      key,
      now,
      type: eventTypeOf(parsed),
      matchId: parsed.match_id,
      payload: text,
    });
    return res.status(200).json({ status: info.changes === 1 ? "accepted" : "duplicate" });
  } catch (err) {
    // We could not persist: tell the sender to retry later
    console.error(JSON.stringify({ level: "error", msg: "inbox write failed", err: err.message }));
    return res.status(500).json({ error: "temporary failure" });
  }
}

);

return app;
}
The status-code rules (this is the heart of reliable webhooks)
Situation Respond Why
Bad or missing signature 401 Not from the provider. Retrying won’t help and shouldn’t
Authentic event, written to inbox 200 You own it now. Process later
Authentic duplicate 200 The sender retried because it missed your last ACK. Acknowledge so retries stop
Authentic event you can’t parse or don’t recognize 200, store it Rejecting authentic traffic invites pointless retries and can get your endpoint disabled
You failed to write to the database 500 Genuinely temporary. You want a retry

The most common mistake is returning an error for a duplicate. The sender is retrying precisely because it didn’t see your 200. Answering the retry with an error just extends the loop.

Also notice what’s absent: no business logic in the handler. Slow handlers cause timeouts, timeouts cause retries, and retries cause duplicates. Keeping the request path to “verify, write, ACK” breaks that chain.

Step 7: Idempotent handlers

src/handlers.js:

javascript
import { db } from "./db.js";

const insertGoal = db.prepare(INSERT INTO goals (idempotency_key, match_id, team, minute) VALUES (?, ?, ?, ?) ON CONFLICT(idempotency_key) DO NOTHING);

export const scoreboard = db.prepare(SELECT team, COUNT(*) AS goals FROM goals WHERE match_id = ? GROUP BY team);

// event type -> handler. Add more as you inspect real payloads.
const handlers = {
"match.goal": (event, key) => {
insertGoal.run(key, event.match_id, event.team ?? null, event.minute ?? null);
},
};

export async function handleEvent(event, key) {
const handler = handlers[event.type];
if (!handler) {
console.log(JSON.stringify({ level: "info", msg: "no handler", type: event.type }));
return; // unknown types are not errors
}
await handler(event, key);
}

Two principles at work:

The handler is idempotent too. Even if the inbox dedupe somehow failed, ON CONFLICT DO NOTHING on the goal row makes a second run harmless. Defense in depth: assume each layer can fail.
Store events, derive state. We don’t keep a mutable “score” counter that we += 1. We store goal rows and compute the score with a query. If a correction ever arrives (a goal disallowed after review), you delete or void one row and the score fixes itself. Patching counters is how scores drift permanently.
Step 8: The worker, with retries and a dead-letter state

src/worker.js:

javascript
import { db } from "./db.js";
import { config } from "./config.js";
import { eventSchema, eventTypeOf } from "./schema.js";
import { handleEvent } from "./handlers.js";

const due = db.prepare(SELECT idempotency_key, payload, attempts FROM inbox WHERE status = 'pending' AND next_attempt_at <= ? ORDER BY received_at LIMIT 20);
const markDone = db.prepare(UPDATE inbox SET status = 'done', last_error = NULL WHERE idempotency_key = ?);
const markRetry = db.prepare(UPDATE inbox SET attempts = ?, next_attempt_at = ?, last_error = ? WHERE idempotency_key = ?);
const markDead = db.prepare(UPDATE inbox SET status = 'dead', attempts = ?, last_error = ? WHERE idempotency_key = ?);

// 2s, 4s, 8s ... capped at 5 min, with jitter so retries don't synchronize
export function backoffMs(attempt) {
const base = Math.min(2 ** attempt * 1000, 5 * 60_000);
return base / 2 + Math.random() * (base / 2);
}

export async function drainOnce(now = Date.now()) {
const rows = due.all(now);
for (const row of rows) {
try {
const event = eventSchema.parse(JSON.parse(row.payload));
await handleEvent({ ...event, type: eventTypeOf(event) }, row.idempotency_key);
markDone.run(row.idempotency_key);
} catch (err) {
const attempts = row.attempts + 1;
const msg = String(err.message).slice(0, 500);
if (attempts >= config.maxAttempts) {
markDead.run(attempts, msg, row.idempotency_key);
console.error(JSON.stringify({ level: "error", msg: "event dead-lettered", key: row.idempotency_key, err: msg }));
} else {
markRetry.run(attempts, now + backoffMs(attempts), msg, row.idempotency_key);
}
}
}
return rows.length;
}

What this gives you:

Exponential backoff with jitter: failures wait 1 to 2s, then 2 to 4s, then longer. Jitter prevents a thundering herd after an outage.
A bounded number of attempts: after MAX_ATTEMPTS, the event becomes dead. A poison message can’t loop forever or block the queue behind it.
Visibility: last_error and attempts tell you exactly what went wrong and how many times.

Dead letters are not a trash can. Alert on them. A growing dead count means your handler or your assumptions about payloads are broken, and you’ll want to fix the bug and replay those rows by setting them back to pending.

Step 9: Reconciliation, the safety net

Here’s an uncomfortable truth about webhooks: any push system can miss an event. Your server was down past the retry window, a network partition ate a delivery, a deploy dropped a connection. If a goal is missed and you never check, your scoreboard stays wrong forever.

The fix is cheap: periodically compare your local view against the REST API. We use the live-matches endpoint from the quickstart pattern (GET /v1/{sport}/matches/live).

src/reconcile.js:

javascript
import { config } from "./config.js";
import { scoreboard } from "./handlers.js";

const BASE = "https://api.orbistats.com/v1";

export async function reconcileLiveMatches(sport = "football") {
const res = await fetch(${BASE}/${sport}/matches/live, {
headers: { Authorization: Bearer ${config.apiKey} },
signal: AbortSignal.timeout(10_000),
});
if (!res.ok) throw new Error(live endpoint returned ${res.status});

const body = await res.json();
const matches = Array.isArray(body) ? body : body.data ?? [];
const drift = [];

for (const m of matches) {
const local = Object.fromEntries(
scoreboard.all(String(m.match_id)).map((r) => [r.team, r.goals])
);
const gotHome = local[m.home?.name] ?? 0;
const gotAway = local[m.away?.name] ?? 0;

if (gotHome !== m.home?.score || gotAway !== m.away?.score) {
  drift.push({
    match_id: m.match_id,
    api: { home: m.home?.score, away: m.away?.score },
    webhook_view: { home: gotHome, away: gotAway },
  });
}

}
return drift;
}

A few honest caveats:

The response shape here follows the example on the Orbistats homepage (match_id, home.score, away.score). Confirm it in the API reference, because the code accepts either a bare array or { data: [...] }.
If you start your receiver mid-match, drift is expected, since you missed earlier goals. Reconciliation is for detecting trouble.
Own goals can attribute differently (“team that scored” vs “team credited”), so the first time drift appears, check whether it’s real before panicking.
In production, don’t just log drift. Repair it by re-fetching the match’s event list and rebuilding rows.

Reconciliation also covers a failure mode no amount of signature checking can: the provider’s webhook for an event simply never arriving. The Sports Data API and Live Scores API are the pull-based sources you reconcile against.

Step 10: Wire it together

src/index.js:

javascript
import { createApp } from "./server.js";
import { startWorker } from "./worker.js";
import { reconcileLiveMatches } from "./reconcile.js";
import { config } from "./config.js";

const app = createApp();
const server = app.listen(config.port, () =>
console.log(JSON.stringify({ level: "info", msg: "listening", port: config.port }))
);
const stopWorker = startWorker();

// Safety net: only runs if you provided an API key
if (config.apiKey) {
setInterval(async () => {
try {
const drift = await reconcileLiveMatches();
if (drift.length) console.warn(JSON.stringify({ level: "warn", msg: "score drift", drift }));
} catch (e) {
console.error("reconcile failed:", e.message);
}
}, 60_000);
}

for (const sig of ["SIGINT", "SIGTERM"]) {
process.on(sig, () => {
stopWorker();
server.close(() => process.exit(0)); // finish in-flight requests, then exit
});
}

Run it:

bash
npm start
curl localhost:8080/healthz
Step 11: Simulate signed deliveries locally

You shouldn’t need a live match (or your provider) to test this. scripts/send-test-event.js signs a payload exactly the way your receiver expects and sends it twice:

javascript
import crypto from "node:crypto";

const secret = process.env.WEBHOOK_SECRET;
const url = process.env.TARGET_URL ?? "http://localhost:8080/webhooks/orbistats";
const header = (process.env.WEBHOOK_SIGNATURE_HEADER ?? "x-signature").toLowerCase();
const encoding = process.env.WEBHOOK_SIGNATURE_ENCODING ?? "hex";
const prefix = process.env.WEBHOOK_SIGNATURE_PREFIX ?? "";

const event = {
id: process.argv[2] ?? evt_${Date.now()},
type: "match.goal",
match_id: "48213",
minute: 72,
team: "Manchester City",
timestamp: new Date().toISOString(),
};

const body = JSON.stringify(event);
const signature = prefix + crypto.createHmac("sha256", secret).update(body).digest(encoding);

async function send(label) {
const res = await fetch(url, {
method: "POST",
headers: { "content-type": "application/json", [header]: signature },
body,
});
console.log(label, res.status, await res.text());
}

await send("first ");
await send("replay"); // same id, so this must come back as a duplicate
bash
npm run send -- evt_1

first 200 {"status":"accepted"}

replay 200 {"status":"duplicate"}

Then check the database:

bash
sqlite3 webhooks.db "SELECT status, COUNT(*) FROM inbox GROUP BY status;"
sqlite3 webhooks.db "SELECT * FROM goals;"

You should see one inbox row and one goal row, even though you sent two deliveries.

Step 12: Automated tests

test/webhook.test.js (uses Node’s built-in test runner, no extra dependencies):

javascript
import { test, before, after } from "node:test";
import assert from "node:assert/strict";
import crypto from "node:crypto";

// Env must be set BEFORE the modules load
process.env.WEBHOOK_SECRET = "test-secret";
process.env.DB_PATH = ":memory:";

const { createApp } = await import("../src/server.js");
const { drainOnce, backoffMs } = await import("../src/worker.js");
const { db } = await import("../src/db.js");

let server;
let base;

before(async () => {
server = createApp().listen(0);
await new Promise((r) => server.once("listening", r));
base = http://127.0.0.1:${server.address().port};
});
after(() => server.close());

test("rejects a bad signature", async () => {
const res = await post(evt("e1"), "deadbeef");
assert.equal(res.status, 401);
});

test("accepts a valid event once and ACKs duplicates", async () => {
const body = evt("e2");
assert.equal((await (await post(body)).json()).status, "accepted");
assert.equal((await (await post(body)).json()).status, "duplicate");
assert.equal(count("SELECT COUNT(*) AS n FROM inbox WHERE idempotency_key = 'id:e2'"), 1);
});

test("processing is idempotent", async () => {
await post(evt("e3"));
await post(evt("e3"));
await drainOnce();
assert.equal(count("SELECT COUNT(*) AS n FROM goals WHERE idempotency_key = 'id:e3'"), 1);
});

test("unknown event types are ACKed and completed, not errored", async () => {
const res = await post(evt("e4", "match.something_new"));
assert.equal(res.status, 200);
await drainOnce();
assert.equal(count("SELECT COUNT(*) AS n FROM inbox WHERE idempotency_key = 'id:e4' AND status = 'done'"), 1);
});

test("authentic but malformed payloads are stored, not rejected", async () => {
const body = "not json at all";
const res = await post(body);
assert.equal(res.status, 200);
assert.equal(count("SELECT COUNT(*) AS n FROM inbox WHERE status = 'dead'"), 1);
});

test("backoff grows with attempts", () => {
assert.ok(backoffMs(1) < backoffMs(5));
});
bash
npm test

These six tests encode the rules from Step 6. If anyone later “simplifies” the handler into returning 409 for duplicates, a test fails.

Step 13: Going live without wasting your access window

When you’re ready to receive real events:

Expose your local server over HTTPS with a tunnel (ngrok or Cloudflare Tunnel), or deploy it.
Get an API key. Request access and follow the activation steps in the quickstart.
Inspect a real payload in the sandbox, then adjust schema.js and your handlers to match.
Confirm the three signature settings (header, encoding, prefix) in the webhooks docs, and put them in .env.
Register your public URL (https://your-domain/webhooks/orbistats) using the registration steps in the API reference.

So build and test everything above locally with simulated, signed events before you start the clock. Steps 1 to 12 need no live data. Then spend the window verifying real payloads and signatures, and let a live match prove the pipeline.

Also bookmark the status page. When events stop arriving, it’s the fastest way to learn whether the problem is yours or the provider’s.

Step 14: Production hardening checklist

The tutorial version is correct. A production version is also operable:

Move the worker to its own process so slow handlers can’t affect request latency. better-sqlite3 is synchronous, so heavy handlers block the event loop in a single process.
Use Postgres for multiple workers. Replace SQLite’s claim step with a row-locking claim:
sql
UPDATE inbox
SET status = 'processing', locked_at = now()
WHERE idempotency_key IN (
SELECT idempotency_key FROM inbox
WHERE status = 'pending' AND next_attempt_at <= now()
ORDER BY received_at
LIMIT 20
FOR UPDATE SKIP LOCKED
)
RETURNING *;

Add a lease timeout so rows stuck in processing after a crash return to pending.

Monitor three numbers: pending depth, age of the oldest pending row, and dead-letter count.
sql
SELECT status, COUNT(*) FROM inbox GROUP BY status;
SELECT (strftime('%s','now')*1000 - MIN(received_at)) / 1000 AS oldest_pending_seconds
FROM inbox WHERE status = 'pending';
Alert on silence. If a match is live and zero events have arrived for several minutes, something is wrong even if no errors are firing. Reconciliation catches this.
Never log secrets or full signatures. Log the idempotency key and event type instead.
Terminate TLS properly, apply rate limiting at your proxy, and keep the body size limit small.
Retain the inbox for a while (days, not forever). It’s your audit trail and your replay source.
Handle match-day spikes with a queue and caching in front of your readers. Our post on scaling a sports data consumer for match-day spikes covers that side.
Common pitfalls (each one has bitten someone)
Symptom Likely cause Fix
Every signature fails A JSON parser ran before verification Use express.raw on this route and verify the Buffer
Signature fails only sometimes You re-serialized parsed JSON Verify the original bytes, never JSON.stringify(req.body)
Same goal counted twice Dedupe in memory, or only in the handler Unique key in the database, enforced on insert
Provider keeps retrying forever You return non-2xx for duplicates or unknown types ACK anything authentic that you’ve stored
Slow responses, then more duplicates Business logic on the request path Write to the inbox, ACK, process in the worker
Scores drift over a week Mutable counters and no reconciliation Store events, derive state, reconcile periodically
Endpoint suddenly disabled by sender Sustained 4xx/5xx or timeouts Fix the cause, monitor, and see the retry/disable policy in the docs
Duplicates after a deploy In-memory dedupe lost on restart Persist idempotency keys
Wrapping up

Reliable webhook handling comes down to a handful of habits:

Verify authenticity on the raw bytes, with a constant-time compare.
Acknowledge fast and keep the request path to verify, write, ACK.
Make duplicates harmless with a database-enforced idempotency key, in the inbox and in the handler.
Retry with backoff and jitter, cap the attempts, and alert on dead letters.
Store events, derive state, and reconcile against a pull API so a missed push can’t become a permanent error.

If you want the wider picture of how REST, WebSocket and webhooks fit together, our sports odds API guide walks through delivery methods and a production checklist.

Question for the comments: for your idempotency key, do you trust the provider’s event ID, or do you hash the body as a fallback? And have you ever been bitten by a webhook that never arrived? I’d like to hear how you caught it.

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! 📊