Developer Docs · REST + WebSocket

The API Reference for every sport we cover

One consistent resource model — fixtures, live scores, results, standings, statistics, odds, teams, players and history — repeated identically across 13 sports. Learn it once, use it everywhere.

Base URL https://api.orbistats.com Format JSON over HTTPS Auth Bearer API key Current version v1
Core resources

Eight endpoint families, one shape

Every sport exposes the same building blocks. Jump to any resource below, or use the sidebar for the full reference.

Getting started

Authentication

Every request needs an API key. Pass it as a Bearer token in the Authorization header for production traffic, or as an api_key query parameter while testing in a browser. Keep the key in the ORBISTATS_API_KEY environment variable, never in client-side code. Keys are scoped to a plan and can be rotated at any time from your dashboard without downtime — issue a new key, update your app, then revoke the old one.

curl https://api.orbistats.com/v1/football/fixtures \ -H "Authorization: Bearer YOUR_API_KEY"
const res = await fetch("https://api.orbistats.com/v1/football/fixtures", { headers: { Authorization: `Bearer ${process.env.ORBISTATS_API_KEY}` } }); const data = await res.json();
import os import requests resp = requests.get( "https://api.orbistats.com/v1/football/fixtures", headers={"Authorization": f"Bearer {os.environ['ORBISTATS_API_KEY']}"} ) data = resp.json()

Base URL & versioning

All endpoints are served from https://api.orbistats.com and prefixed with a version segment. The current stable version is v1. We never introduce breaking changes inside a version — new fields are additive, and breaking changes ship as a new version with a migration guide and an overlap window.

https://api.orbistats.com/v1/{sport}/{resource}

Response format

Every response — success or failure — shares the same envelope, so your parsing code doesn't branch per endpoint. Unknown fields should be ignored: new fields are additive within a version.

{ "data": [ { "…": "endpoint-specific object" } ], "meta": { "request_id": "req_8f2c1a", "generated_at": "2026-08-30T10:00:00Z", "pagination": { "page": 1, "per_page": 25, "total": 38, "total_pages": 2, "next_cursor": null } }, "errors": [] }
FieldTypeDescription
dataobject | array | nullThe payload. null when the request failed.
meta.request_idstringUnique id for the request. Quote it when contacting support.
meta.generated_atstringServer time the response was built, ISO 8601 UTC.
meta.paginationobjectOnly on list endpoints — see below.
errorsarrayEmpty on success. Each item has code, message and, for validation problems, field.

Errors

Errors return the matching HTTP status code and the standard envelope with data: null and a populated errors array. Never retry a 4xx unchanged; retry 500/502/503/504 and network timeouts with exponential backoff and jitter. Quote meta.request_id when contacting support.

StatusCodeMeaningWhat to do
400invalid_parameterMalformed or invalid parameterFix the parameter named in errors[].field. Do not retry unchanged.
401invalid_api_keyMissing, invalid or revoked API keyCheck the Authorization: Bearer header and that the key is active.
403plan_restrictedYour plan doesn't include this resourceRemove the endpoint/field from the request, or move to a plan that includes it.
404not_foundResource or ID doesn't existVerify the sport slug and ID; IDs are sport-scoped.
500internal_errorUnexpected server errorSafe to retry with exponential backoff and jitter.
502 / 503 / 504service_unavailableTemporary upstream or availability problemSafe to retry with exponential backoff and jitter; check the status page.
{ "data": null, "meta": { "request_id": "req_8f2c1a", "generated_at": "2026-08-30T10:00:00Z" }, "errors": [ { "code": "invalid_parameter", "message": "'league' must be a known competition slug.", "field": "league" } ] }
Retry with backoff
const RETRYABLE = new Set([500, 502, 503, 504]); async function orbistatsFetch(path, { retries = 3, timeoutMs = 10000 } = {}) { for (let attempt = 0; ; attempt++) { try { const res = await fetch(`https://api.orbistats.com/v1${path}`, { headers: { Authorization: `Bearer ${process.env.ORBISTATS_API_KEY}` }, signal: AbortSignal.timeout(timeoutMs), }); const body = await res.json(); if (res.ok) return body; // { data, meta, errors: [] } const err = body.errors?.[0] ?? { code: 'unknown', message: res.statusText }; if (!RETRYABLE.has(res.status) || attempt >= retries) { throw Object.assign(new Error(err.message), { status: res.status, code: err.code, requestId: body.meta?.request_id, }); } } catch (e) { if (e.status || attempt >= retries) throw e; // API error, or out of retries // otherwise: network error or timeout, retry below } const delay = Math.min(8000, 500 * 2 ** attempt) + Math.random() * 250; // backoff + jitter await new Promise((resolve) => setTimeout(resolve, delay)); } }
import os import random import time import requests RETRYABLE = {500, 502, 503, 504} class OrbistatsError(Exception): def __init__(self, status, code, message, request_id=None): super().__init__(message) self.status, self.code, self.request_id = status, code, request_id def orbistats_get(path, params=None, retries=3, timeout=10): for attempt in range(retries + 1): try: res = requests.get( f"https://api.orbistats.com/v1{path}", params=params, headers={"Authorization": f"Bearer {os.environ['ORBISTATS_API_KEY']}"}, timeout=timeout, ) except (requests.ConnectionError, requests.Timeout): if attempt == retries: raise # out of retries else: try: body = res.json() except ValueError: body = {} if res.ok: return body # {"data": ..., "meta": ..., "errors": []} if res.status_code not in RETRYABLE or attempt == retries: err = (body.get("errors") or [{}])[0] raise OrbistatsError( res.status_code, err.get("code", "unknown"), err.get("message", res.reason), body.get("meta", {}).get("request_id"), ) time.sleep(min(8, 0.5 * 2 ** attempt) + random.random() * 0.25) # backoff + jitter
GET/v1/{sport}/fixtures

Upcoming fixtures for a sport, filterable by league, team or date range. Powers schedule pages, "next match" widgets and fixture-list views.

PaginatedCacheableAll plans
Query parameters
ParameterTypeRequiredDescription
leaguestringNoCompetition slug, e.g. premier-league.
teamstringNoTeam slug or ID to filter fixtures for one club.
date_fromdateNoISO 8601 date. Defaults to today.
date_todateNoISO 8601 date. Defaults to +14 days.
page / per_pageintegerNoStandard pagination, see above.
Example request
curl "https://api.orbistats.com/v1/football/fixtures?league=premier-league" \ -H "Authorization: Bearer YOUR_API_KEY"
const client = new orbistats.Client(process.env.ORBISTATS_API_KEY); const { data: fixtures } = await client.football.fixtures({ league: "premier-league" });
client = orbistats.Client(os.environ["ORBISTATS_API_KEY"]) res = client.football.fixtures(league="premier-league") fixtures = res["data"]
Example response
{ "data": [ { "fixture_id": "fx_884213", "sport": "football", "league": "Premier League", "league_slug": "premier-league", "season": "2025-2026", "home_team": "Manchester City", "home_team_id": "tm_2011", "away_team": "Arsenal", "away_team_id": "tm_2014", "kickoff": "2026-08-30T15:00:00Z", "venue": "Etihad Stadium", "status": "scheduled" } ], "meta": { "request_id": "req_8f2c1a", "generated_at": "2026-08-30T10:00:00Z", "pagination": { "page": 1, "per_page": 25, "total": 38, "total_pages": 2, "next_cursor": null } }, "errors": [] }
Response fields
FieldTypeDescription
fixture_idstringStable fixture identifier (fx_…). Use it for odds, lineups, events, webhooks and WebSocket filters.
sportstringSport slug, e.g. football.
leaguestringCompetition display name.
league_slugstringCompetition slug accepted by the league filter.
seasonstringSeason key, e.g. 2025-2026.
home_team / away_teamstringTeam display names.
home_team_id / away_team_idstringTeam identifiers (tm_…) usable with /teams and /statistics/team.
kickoffstringScheduled start, ISO 8601 UTC.
venuestring | nullVenue name when known.
statusstringscheduled, live, finished, postponed or cancelled.
GET/v1/{sport}/fixtures/{fixture_id}

A single fixture with full detail — venue, officials, broadcast info and links to its lineups, events and odds once available.

Path parameters
ParameterTypeRequiredDescription
fixture_idstringYesUnique fixture identifier returned by the fixtures list.
Example request
curl https://api.orbistats.com/v1/football/fixtures/fx_884213 \ -H "Authorization: Bearer YOUR_API_KEY"
Example response
{ "data": { "fixture_id": "fx_884213", "sport": "football", "league": "Premier League", "league_slug": "premier-league", "season": "2025-2026", "home_team": "Manchester City", "home_team_id": "tm_2011", "away_team": "Arsenal", "away_team_id": "tm_2014", "kickoff": "2026-08-30T15:00:00Z", "venue": "Etihad Stadium", "status": "scheduled", "round": "Matchday 1", "officials": { "referee": "Michael Oliver" }, "broadcast": ["Sky Sports"], "links": { "lineups": "/v1/football/fixtures/fx_884213/lineups", "events": "/v1/football/fixtures/fx_884213/events", "odds": "/v1/football/odds?match_id=fx_884213" } }, "meta": { "request_id": "req_8f2c1a", "generated_at": "2026-08-30T10:00:00Z" }, "errors": [] }
Response fields
FieldTypeDescription
fixture_idstringStable fixture identifier (fx_…). Use it for odds, lineups, events, webhooks and WebSocket filters.
sportstringSport slug, e.g. football.
leaguestringCompetition display name.
league_slugstringCompetition slug accepted by the league filter.
seasonstringSeason key, e.g. 2025-2026.
home_team / away_teamstringTeam display names.
home_team_id / away_team_idstringTeam identifiers (tm_…) usable with /teams and /statistics/team.
kickoffstringScheduled start, ISO 8601 UTC.
venuestring | nullVenue name when known.
statusstringscheduled, live, finished, postponed or cancelled.
roundstring | nullRound or matchday label.
officialsobjectMatch officials, e.g. referee. Empty until assigned.
broadcaststring[]Broadcasters, when published.
linksobjectRelative URLs for lineups, events and odds. Populated once the data exists.
GET/v1/{sport}/matches/live

Every match currently in play, with the live score, clock, period and the most recent event. Poll every 5–10 seconds, or switch to the WebSocket API for push updates.

Real-timeNot cachedAll plans
Query parameters
ParameterTypeRequiredDescription
leaguestringNoRestrict to a single competition.
Example response
{ "data": [ { "fixture_id": "fx_884213", "sport": "football", "league": "Premier League", "home_team": "Manchester City", "away_team": "Arsenal", "status": "live", "score": { "home": 2, "away": 1 }, "minute": 67, "period": "2nd_half", "last_event": { "type": "goal", "team": "Arsenal", "player": "Bukayo Saka", "minute": 65 }, "updated_at": "2026-08-30T16:07:12Z" } ], "meta": { "request_id": "req_8f2c1a", "generated_at": "2026-08-30T10:00:00Z" }, "errors": [] }
Response fields
FieldTypeDescription
fixture_idstringFixture identifier.
sport / leaguestringSport slug and competition name.
home_team / away_teamstringTeam display names.
statusstringlive while in play; the match leaves this endpoint once it is finished.
scoreobject{ home, away } integers. Sport-specific scoring (sets, innings, rounds) is exposed in score.detail when relevant.
minuteinteger | nullMatch clock in minutes; null for sports without a running clock.
periodstringCurrent period, e.g. 1st_half, 2nd_half, set_2, q3.
last_eventobject | nullMost recent event: type, team, player, minute.
updated_atstringWhen this snapshot was produced, ISO 8601 UTC.
GET/v1/{sport}/results

Completed matches with the final score, filterable the same way as fixtures. Use it to build results grids, form guides and head-to-head history.

ParameterTypeRequiredDescription
leaguestringNoCompetition slug.
teamstringNoFilter to one team's results.
seasonstringNoe.g. 2025-2026. Defaults to current season.
Example response
{ "data": [ { "fixture_id": "fx_883990", "sport": "football", "league": "Premier League", "season": "2025-2026", "home_team": "Liverpool", "away_team": "Chelsea", "kickoff": "2026-08-23T15:00:00Z", "status": "finished", "score": { "home": 2, "away": 2 }, "half_time": { "home": 1, "away": 0 }, "winner": "draw", "finished_at": "2026-08-23T16:52:03Z" } ], "meta": { "request_id": "req_8f2c1a", "generated_at": "2026-08-30T10:00:00Z", "pagination": { "page": 1, "per_page": 25, "total": 38, "total_pages": 2, "next_cursor": null } }, "errors": [] }
Response fields
FieldTypeDescription
fixture_idstringFixture identifier.
sport / league / seasonstringSport slug, competition name and season key.
home_team / away_teamstringTeam display names.
kickoffstringScheduled start, ISO 8601 UTC.
statusstringAlways finished on this endpoint.
scoreobjectFinal score { home, away }.
half_timeobject | nullHalf-time score where the sport has halves.
winnerstringhome, away or draw.
finished_atstringWhen the result was confirmed, ISO 8601 UTC.
GET/v1/{sport}/standings

The current league table — played, won, drawn, lost, goal difference and points — updated automatically after every result is confirmed.

ParameterTypeRequiredDescription
leaguestringYesCompetition slug.
seasonstringNoDefaults to the current season.
Example response
{ "data": { "league": "Premier League", "season": "2025-2026", "updated_at": "2026-08-30T10:00:00Z", "table": [ { "position": 1, "team": "Manchester City", "team_id": "tm_2011", "played": 3, "won": 3, "drawn": 0, "lost": 0, "goals_for": 8, "goals_against": 1, "goal_difference": 7, "points": 9 }, { "position": 2, "team": "Arsenal", "team_id": "tm_2014", "played": 3, "won": 2, "drawn": 1, "lost": 0, "goals_for": 6, "goals_against": 2, "goal_difference": 4, "points": 7 } ] }, "meta": { "request_id": "req_8f2c1a", "generated_at": "2026-08-30T10:00:00Z" }, "errors": [] }
Response fields
FieldTypeDescription
league / seasonstringCompetition and season the table belongs to.
updated_atstringWhen the table was last recalculated, ISO 8601 UTC.
table[].positionintegerRank in the table, starting at 1.
table[].team / team_idstringTeam name and identifier.
table[].played / won / drawn / lostintegerRecord. Sports without draws return drawn: 0.
table[].goals_for / goals_against / goal_differenceintegerScoring totals (points or runs for other sports).
table[].pointsintegerCompetition points.
GET/v1/{sport}/statistics/team/{team_id}

Season-level team statistics — shots, possession, cards and sport-specific metrics. A matching /statistics/player/{player_id} endpoint returns individual player numbers for the same season.

Path & query parameters
ParameterTypeRequiredDescription
team_idstringYesTeam identifier.
seasonstringNoDefaults to current season.
competitionstringNoScope statistics to one competition only.
Example response
{ "data": { "team_id": "tm_2011", "team": "Manchester City", "season": "2025-2026", "competition": "Premier League", "matches_played": 3, "stats": { "goals_for": 8, "goals_against": 1, "shots": 54, "shots_on_target": 22, "possession_avg": 63.4, "yellow_cards": 4, "red_cards": 0, "clean_sheets": 2 } }, "meta": { "request_id": "req_8f2c1a", "generated_at": "2026-08-30T10:00:00Z" }, "errors": [] }
Response fields
FieldTypeDescription
team_id / teamstringTeam identifier and display name.
season / competitionstringScope of the numbers. competition is null when aggregated across all competitions.
matches_playedintegerMatches included in the aggregate.
statsobjectSport-specific metrics. Football keys are shown; other sports return their own keys under the same object.
GET/v1/{sport}/odds

Pre-match and live odds normalized into a single format across sportsbooks, so you compare markets without writing a parser per book.

Real-timeGrowth+ plan
ParameterTypeRequiredDescription
match_idstringYesFixture identifier.
marketstringNoe.g. 1x2, totals, player_props.
bookmakerstringNoRestrict to a single sportsbook.
Example response
{ "data": { "fixture_id": "fx_884213", "sport": "football", "updated_at": "2026-08-30T10:00:00Z", "markets": { "1X2": [ { "bookmaker": "bookmaker_a", "home": 1.91, "draw": 3.4, "away": 4.2, "updated_at": "2026-08-30T09:59:41Z" }, { "bookmaker": "bookmaker_b", "home": 1.95, "draw": 3.35, "away": 4.1, "updated_at": "2026-08-30T09:59:58Z" } ] } }, "meta": { "request_id": "req_8f2c1a", "generated_at": "2026-08-30T10:00:00Z" }, "errors": [] }
Response fields
FieldTypeDescription
fixture_id / sportstringFixture the prices belong to.
updated_atstringMost recent price change across all books, ISO 8601 UTC.
marketsobjectKeyed by market name (1X2, totals, player_props). Each value is an array of quotes.
markets.*[].bookmakerstringSource sportsbook.
markets.*[].home / draw / awaynumberDecimal odds. draw is omitted for two-way markets; totals markets use line, over, under.
markets.*[].updated_atstringWhen this quote last changed.
GET/v1/{sport}/teams · /v1/{sport}/players

Team and player directories with stable IDs used throughout the rest of the API. /teams/{team_id} and /players/{player_id} return full profiles including current squad, competitions and season stats links.

ParameterTypeRequiredDescription
leaguestringNoFilter teams or players to one competition.
team_idstringNoFilter players to one squad.
searchstringNoFree-text name search.
Example response
{ "data": [ { "team_id": "tm_2011", "name": "Manchester City", "short_name": "Man City", "country": "England", "venue": "Etihad Stadium" } ], "meta": { "request_id": "req_8f2c1a", "generated_at": "2026-08-30T10:00:00Z", "pagination": { "page": 1, "per_page": 25, "total": 38, "total_pages": 2, "next_cursor": null } }, "errors": [] }
{ "data": [ { "player_id": "pl_30112", "name": "Bukayo Saka", "team_id": "tm_2014", "position": "Forward", "nationality": "England", "date_of_birth": "2001-09-05" } ], "meta": { "request_id": "req_8f2c1a", "generated_at": "2026-08-30T10:00:00Z", "pagination": { "page": 1, "per_page": 25, "total": 38, "total_pages": 2, "next_cursor": null } }, "errors": [] }
Response fields
FieldTypeDescription
team_idstringStable team identifier.
name / short_namestringDisplay names.
country / venuestring | nullCountry and home venue.
player_idstringStable player identifier.
team_id (player)stringCurrent squad. null for free agents.
position / nationalitystringPosition label and nationality.
date_of_birthstring | nullISO 8601 date.
GET/v1/{sport}/fixtures/{fixture_id}/lineups · /events

Starting lineups, formations and substitutes for a fixture, plus a chronological event feed — goals, cards, substitutions and sport-specific events — as they're confirmed.

Example response
{ "data": { "lineups": { "fixture_id": "fx_884213", "home": { "formation": "4-3-3", "starting": [ { "player_id": "pl_30001", "name": "Ederson", "number": 31, "position": "GK" } ], "substitutes": [ { "player_id": "pl_30044", "name": "Stefan Ortega", "number": 18, "position": "GK" } ] }, "away": { "formation": "4-3-3", "starting": [ { "player_id": "pl_30090", "name": "David Raya", "number": 22, "position": "GK" } ], "substitutes": [] } }, "events": [ { "event_id": "ev_5521", "fixture_id": "fx_884213", "type": "goal", "minute": 65, "team": "Arsenal", "player": "Bukayo Saka", "detail": { "assist": "Martin Odegaard" }, "confirmed_at": "2026-08-30T16:05:30Z" } ] }, "meta": { "request_id": "req_8f2c1a", "generated_at": "2026-08-30T10:00:00Z" }, "errors": [] }
Response fields
FieldTypeDescription
home / away.formationstring | nullFormation, e.g. 4-3-3.
home / away.starting[]object[]Starting players: player_id, name, number, position.
home / away.substitutes[]object[]Bench players, same shape.
events[].event_idstringUnique, ordered event identifier.
events[].typestringgoal, card, substitution or a sport-specific type.
events[].minute / team / playermixedWhen it happened, and who was involved.
events[].detailobjectType-specific extras (assist, card colour, replaced player…).
GET/v1/{sport}/competitions

Every league and tournament we cover for a sport, with country, tier and current season, so you can build a competition picker without hardcoding a list.

Example response
{ "data": [ { "competition_id": "cmp_39", "name": "Premier League", "slug": "premier-league", "country": "England", "tier": 1, "current_season": "2025-2026" } ], "meta": { "request_id": "req_8f2c1a", "generated_at": "2026-08-30T10:00:00Z", "pagination": { "page": 1, "per_page": 25, "total": 38, "total_pages": 2, "next_cursor": null } }, "errors": [] }
Response fields
FieldTypeDescription
competition_idstringStable competition identifier.
name / slugstringDisplay name and the slug used by the league parameter.
country / tierstring | integerCountry and level in the pyramid.
current_seasonstringSeason key currently in play.
GET/v1/{sport}/history/matches

Season-by-season historical match data for backtesting models, building head-to-head pages and long-run trend analysis. Depth varies by sport and competition — check the coverage matrix below.

ParameterTypeRequiredDescription
leaguestringNoCompetition slug.
season_from / season_tostringNoSeason range, e.g. 2015-2016 to 2025-2026.
cursorstringNoRecommended for large historical pulls.
Starter+ planBulk export available
Example response
{ "data": [ { "fixture_id": "fx_771204", "sport": "football", "league": "Premier League", "season": "2019-2020", "home_team": "Liverpool", "away_team": "Norwich City", "kickoff": "2019-08-10T14:00:00Z", "status": "finished", "score": { "home": 4, "away": 1 }, "half_time": { "home": 4, "away": 0 }, "winner": "home", "finished_at": "2019-08-10T15:55:11Z" } ], "meta": { "request_id": "req_8f2c1a", "generated_at": "2026-08-30T10:00:00Z", "pagination": { "per_page": 100, "total": 1900, "total_pages": 19, "next_cursor": "cur_eyJvIjoxMDB9" } }, "errors": [] }
Response fields

Same fields as Results — historical matches reuse the live schema field-for-field. Page with meta.pagination.next_cursor until it is null.

FieldTypeDescription
fixture_idstringFixture identifier.
sport / league / seasonstringSport slug, competition name and season key.
home_team / away_teamstringTeam display names.
kickoffstringScheduled start, ISO 8601 UTC.
statusstringAlways finished on this endpoint.
scoreobjectFinal score { home, away }.
half_timeobject | nullHalf-time score where the sport has halves.
winnerstringhome, away or draw.
finished_atstringWhen the result was confirmed, ISO 8601 UTC.
WEBHOOKfixture.updated · fixture.finished · match.live.event · odds.changed

Register an HTTPS endpoint once and Orbistats pushes a payload the moment something changes — no polling loop to maintain. Each payload is signed so you can verify it came from us.

Example payload
{ "id": "evt_01J8Z3K5Q2", "event": "fixture.finished", "sport": "football", "created_at": "2026-08-30T16:52:03Z", "data": { "fixture_id": "fx_884213", "status": "finished", "final_score": { "home": 2, "away": 1 }, "finished_at": "2026-08-30T16:52:03Z" } }
Payload fields
FieldTypeDescription
idstringUnique event id. Store it and ignore repeats — retries can deliver the same event more than once.
eventstringfixture.updated, fixture.finished, match.live.event or odds.changed.
sportstringSport slug.
created_atstringWhen the event was generated, ISO 8601 UTC.
dataobjectEvent payload. Always contains fixture_id; other fields depend on event.
Delivery headers
HeaderMeaning
X-Orbistats-Signaturesha256=<hex> — HMAC-SHA256 of {timestamp}.{raw_body} using your endpoint's signing secret.
X-Orbistats-TimestampUnix time (seconds) when the delivery was signed. Reject deliveries older than 5 minutes.
Content-Typeapplication/json
Verify the signature

Compute HMAC-SHA256 of {timestamp}.{raw_body} with your endpoint's signing secret, compare it to the X-Orbistats-Signature header in constant time, and reject deliveries whose timestamp is older than 5 minutes. Use the raw request body — re-serialized JSON will not match. Respond 2xx quickly; non-2xx responses are retried, so de-duplicate on id.

const crypto = require('crypto'); const express = require('express'); const app = express(); const SECRET = process.env.ORBISTATS_WEBHOOK_SECRET; const TOLERANCE_SECONDS = 300; const seen = new Set(); // use Redis or a database table with a TTL in production function verify(rawBody, headers) { const timestamp = headers['x-orbistats-timestamp']; const received = (headers['x-orbistats-signature'] || '').replace(/^sha256=/, ''); if (!timestamp || !received) return false; if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false; // replay protection const expected = crypto.createHmac('sha256', SECRET).update(`${timestamp}.${rawBody}`).digest('hex'); const a = Buffer.from(received, 'hex'); const b = Buffer.from(expected, 'hex'); return a.length === b.length && crypto.timingSafeEqual(a, b); // constant-time compare } // Use the RAW body: re-serialized JSON will not match the signature app.post('/webhooks/orbistats', express.raw({ type: 'application/json' }), (req, res) => { const raw = req.body.toString('utf8'); if (!verify(raw, req.headers)) return res.sendStatus(401); const event = JSON.parse(raw); res.sendStatus(200); // acknowledge fast, process afterwards if (seen.has(event.id)) return; // retries can deliver the same event twice seen.add(event.id); setImmediate(() => handleEvent(event).catch((err) => console.error('handler failed', event.id, err))); }); async function handleEvent(event) { switch (event.event) { case 'fixture.finished': { const { fixture_id, final_score } = event.data; console.log(`${fixture_id} finished: ${final_score.home}-${final_score.away}`); break; } case 'match.live.event': case 'fixture.updated': case 'odds.changed': // enqueue to your job queue / update your cache here break; default: break; // ignore unknown event types so new ones never break you } } app.listen(3000);
import hashlib import hmac import json import os import time from flask import Flask, abort, request app = Flask(__name__) SECRET = os.environ["ORBISTATS_WEBHOOK_SECRET"].encode() TOLERANCE_SECONDS = 300 seen_ids = set() # use Redis or a database table with a TTL in production def verify(raw_body: bytes, headers) -> bool: timestamp = headers.get("X-Orbistats-Timestamp", "") received = headers.get("X-Orbistats-Signature", "").removeprefix("sha256=") if not timestamp.isdigit() or not received: return False if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS: return False # replay protection signed = timestamp.encode() + b"." + raw_body expected = hmac.new(SECRET, signed, hashlib.sha256).hexdigest() return hmac.compare_digest(received, expected) # constant-time compare @app.post("/webhooks/orbistats") def orbistats_webhook(): raw = request.get_data() # RAW bytes, before any JSON parsing if not verify(raw, request.headers): abort(401) event = json.loads(raw) if event["id"] in seen_ids: return "", 200 # duplicate delivery seen_ids.add(event["id"]) handle_event(event) # keep it fast; hand slow work to a queue return "", 200 def handle_event(event): if event["event"] == "fixture.finished": data = event["data"] print(f"{data['fixture_id']} finished: {data['final_score']['home']}-{data['final_score']['away']}") # other event types: match.live.event, fixture.updated, odds.changed # unknown types are ignored on purpose so new ones never break you
WSwss://stream.orbistats.com/v1

A persistent connection for clients that need sub-second updates — live scoreboards, trading desks and in-play odds boards. Subscribe to one or more channels after connecting.

const WebSocket = require('ws'); const orbistats = require('orbistats'); const client = new orbistats.Client(process.env.ORBISTATS_API_KEY); const URL = `wss://stream.orbistats.com/v1?token=${process.env.ORBISTATS_API_KEY}`; const CHANNEL = 'football.live'; const STALE_MS = 45000; // no frame for this long = dead connection let attempt = 0; let lastSeq = null; let hasConnectedBefore = false; let watchdog; async function resync() { const { data } = await client.football.matchesLive(); // REST is the source of truth replaceScoreboard(data); } function connect() { const ws = new WebSocket(URL); const armWatchdog = () => { clearTimeout(watchdog); watchdog = setTimeout(() => ws.terminate(), STALE_MS); // fires 'close' -> reconnect }; ws.on('open', () => { attempt = 0; // healthy connection, reset the backoff lastSeq = null; ws.send(JSON.stringify({ subscribe: CHANNEL })); // always re-subscribe after reconnecting if (hasConnectedBefore) resync().catch(console.error); // fill what was missed while offline hasConnectedBefore = true; armWatchdog(); }); ws.on('message', (raw) => { armWatchdog(); let msg; try { msg = JSON.parse(raw); } catch { return; // ignore malformed frames } switch (msg.type) { case 'subscribed': console.log('subscribed to', msg.channel); break; case 'heartbeat': break; case 'error': console.error(`stream error ${msg.code}: ${msg.message}`); break; case 'score_update': case 'match_event': if (lastSeq !== null && msg.seq > lastSeq + 1) resync().catch(console.error); // gap lastSeq = msg.seq; applyUpdate(msg.type, msg.data); // msg.data.fixture_id, msg.data.score, ... break; default: break; // ignore unknown types so new ones never break you } }); ws.on('error', (err) => console.error('socket error:', err.message)); // 'close' always follows ws.on('close', () => { clearTimeout(watchdog); const delay = Math.min(30000, 1000 * 2 ** attempt++) + Math.random() * 1000; // backoff + jitter console.log(`disconnected, reconnecting in ${Math.round(delay)}ms`); setTimeout(connect, delay); }); } connect();
import asyncio import json import os import random import orbistats import websockets API_KEY = os.environ["ORBISTATS_API_KEY"] URL = f"wss://stream.orbistats.com/v1?token={API_KEY}" CHANNEL = "football.live" STALE_SECONDS = 45 # no frame for this long = dead connection client = orbistats.Client(API_KEY) async def resync(): res = await asyncio.to_thread(client.football.matches_live) # REST is the source of truth replace_scoreboard(res["data"]) async def listen_once(first_connect): # an HTTP 401 during the handshake means a bad key: fix the key instead of retrying async with websockets.connect(URL) as ws: await ws.send(json.dumps({"subscribe": CHANNEL})) # always re-subscribe after reconnecting if not first_connect: await resync() # fill what was missed while offline last_seq = None while True: # TimeoutError if the feed goes quiet -> the caller reconnects raw = await asyncio.wait_for(ws.recv(), timeout=STALE_SECONDS) try: msg = json.loads(raw) except ValueError: continue # ignore malformed frames kind = msg.get("type") if kind == "error": print(f"stream error {msg['code']}: {msg['message']}") elif kind in ("score_update", "match_event"): if last_seq is not None and msg["seq"] > last_seq + 1: await resync() # gap detected last_seq = msg["seq"] apply_update(kind, msg["data"]) # msg["data"]["fixture_id"], ["score"], ... async def main(): attempt, first = 0, True loop = asyncio.get_running_loop() while True: started = loop.time() try: await listen_once(first) except (websockets.exceptions.ConnectionClosed, asyncio.TimeoutError, OSError) as exc: print(f"disconnected: {exc!r}") first = False if loop.time() - started > 60: attempt = 0 # the connection was healthy, reset the backoff delay = min(30, 2 ** attempt) + random.random() # backoff + jitter attempt += 1 print(f"reconnecting in {delay:.1f}s") await asyncio.sleep(delay) asyncio.run(main())
Messages
{ "subscribe": "football.live" }
{ "type": "score_update", "channel": "football.live", "seq": 10423, "sent_at": "2026-08-30T16:05:31Z", "data": { "fixture_id": "fx_884213", "score": { "home": 2, "away": 1 }, "minute": 65, "period": "2nd_half" } }
{ "type": "error", "code": "invalid_channel", "message": "Unknown channel 'footbal.live'.", "sent_at": "2026-08-30T16:00:01Z" }
Message fields
FieldTypeDescription
typestringsubscribed, score_update, match_event, odds_update, heartbeat or error.
channelstringChannel the message belongs to, e.g. football.live, football.odds.
seqintegerIncreases by 1 per message on a channel. A jump means you missed messages — resync over REST.
sent_atstringServer timestamp, ISO 8601 UTC.
dataobjectSame field names as the matching REST object (fixture_id, score, minute, …).
code / messagestringOnly on error messages.

Subscribe to {sport}.live (scores and match events) or {sport}.odds; add "fixture_id" to the subscribe message to filter to one match. Reconnect with exponential backoff and jitter, resubscribe after every reconnect, treat a silent connection as dead, and resync over REST when seq jumps.

Coverage

Sport coverage matrix

All 13 sports share the fixtures, results, standings and statistics resources. Odds, lineups/events and full historical depth roll out sport by sport — this table reflects what's live today.

SportFixturesLiveStandingsStatisticsOddsLineupsHistorical
Football✓✓✓✓✓✓✓
Basketball✓✓✓✓✓✓✓
American Football✓✓✓✓✓—✓
Cricket✓✓✓✓✓—✓
Tennis✓✓—✓✓—✓
Baseball✓✓✓✓✓—✓
Horse Racing✓✓——✓—✓
Golf✓✓✓—✓—✓
Combat Sports✓✓——✓——
Esports✓✓✓✓✓——
Volleyball✓✓✓✓✓—✓
Handball✓✓✓✓✓—✓
Ice Hockey✓✓✓✓✓—✓
Client libraries

SDKs & languages

Every endpoint on this page maps directly onto a method in each official SDK — same parameters, same response shape.

Python pip install orbistats
JavaScript npm i orbistats
TypeScript Typed client
PHP composer require
Java Maven / Gradle
C# NuGet
Go go get
Ruby gem install
FAQ

Common questions

Answers to what developers ask most before their first integration.

What format does the Orbistats API return data in?

Every endpoint returns JSON over HTTPS, wrapped in a consistent envelope containing a data object or array, a meta block with pagination and timing details, and an errors array when something goes wrong.

Is the same endpoint structure used for every sport?

Yes. Fixtures, live scores, results, standings, statistics and odds follow the same resource shape for every sport — only the {sport} path segment and sport-specific fields change, so code you write for one sport ports directly to another.

How do I authenticate requests to the Orbistats API?

Send your API key in the Authorization header as a Bearer token, or as an api_key query parameter during local testing. Keys are issued instantly on the free plan from the signup page.

Does Orbistats offer real-time data without polling?

Yes. Webhooks push fixture, score and odds changes to your endpoint as they happen, and the WebSocket API offers a persistent low-latency stream for live matches and live odds for clients that need sub-second updates.

See also

Explore more of the platform

Related developer resources, product pages and research.

Get Started

Start free. Upgrade when you need enterprise SLAs.

Self-serve API keys for developers today — dedicated infrastructure, custom feeds and SLAs when you're ready.