Introduction

Big Balls Sports Data is a unified sports data API. It aggregates 20+ upstream sources and 10 MCP scrapers behind a single Stripe-style gateway. Every response uses the same envelope and every field carries provenance.

Surface area

  • REST under /v1 on the gateway host
  • WebSocket rooms via socket.io for live push
  • HMAC-signed webhook delivery with exponential retry
  • TypeScript SDK in @bigballsdata/sdk; Python and Go generated from the OpenAPI spec
  • Historical odds snapshots (opening, 24h, and closing lines back to ~2020) on odds data via snapshot_type / snapshot_at, queryable at /v1/odds/historical and /v1/odds/closing-lines
  • Two-source odds verification (Pro+): cross-provider divergence flags (price, line, coverage, staleness) on game lines, via /v1/odds/divergences

Sports covered

Football (Soccer), basketball, baseball, american_football, ice_hockey, mma, cricket, formula1.

Featured endpoints

  • /v1/predictions, WC2026 match predictions with Elo-based win/draw/loss probabilities (Solo plan or higher)
  • /v1/standings, live league standings
  • /v1/stored/matches, rich match data with team names
  • /v1/teams, team roster with logos

Response envelope

Every response, success or error, uses this shape:

jsonjson
{
  "data": { /* the resource you requested */ },
  "meta": {
    "source":       "official-league",
    "confidence":   0.95,
    "cached":       false,
    "cache_age_ms": 0,
    "request_id":   "c2f1c4d0-9a8e-4b1c-9c3e-7e2d2f8a1c7b"
  },
  "error": null
}

meta.source is a tier label, never a vendor identifier. Possible values: official-league, aggregator-paid, aggregator-free, community-scraper. See the OpenAPI spec for the full schema.

Next