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.
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.
Fixtures
Schedules and upcoming matches for every league.
Live Scores
In-play score, clock and latest event, updated in seconds.
Results
Full-time results with final score and match summary.
Standings
League tables, updated after every match.
Statistics
Team and player statistics for the current season.
Odds
Pre-match and live odds, normalized across books.
Teams & Players
Rosters, profiles and identifiers used across the API.
Historical Data
Season-by-season archives built for backtesting.
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.
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.
Pagination
List endpoints (fixtures, results, teams, players, historical matches) are paginated with page and per_page, or a cursor for high-volume historical queries. Every list response includes a meta.pagination block. Stop when page reaches total_pages (offset) or when next_cursor is null (cursor).
| Parameter | Type | Default | Description |
|---|---|---|---|
| page | integer | 1 | Page number for offset-based pagination. |
| per_page | integer | 25 | Items per page. Max 100. |
| cursor | string | — | Opaque cursor for large historical datasets. Overrides page. |
| Field | Type | Description |
|---|---|---|
| page | integer | Current page (offset pagination). |
| per_page | integer | Items per page. Max 100. |
| total | integer | Total matching items. |
| total_pages | integer | Total pages at the current per_page. |
| next_cursor | string | null | Cursor for the next page on cursor-paginated queries; null when there are no more results. |
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.
| Field | Type | Description |
|---|---|---|
| data | object | array | null | The payload. null when the request failed. |
| meta.request_id | string | Unique id for the request. Quote it when contacting support. |
| meta.generated_at | string | Server time the response was built, ISO 8601 UTC. |
| meta.pagination | object | Only on list endpoints — see below. |
| errors | array | Empty 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.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | invalid_parameter | Malformed or invalid parameter | Fix the parameter named in errors[].field. Do not retry unchanged. |
| 401 | invalid_api_key | Missing, invalid or revoked API key | Check the Authorization: Bearer header and that the key is active. |
| 403 | plan_restricted | Your plan doesn't include this resource | Remove the endpoint/field from the request, or move to a plan that includes it. |
| 404 | not_found | Resource or ID doesn't exist | Verify the sport slug and ID; IDs are sport-scoped. |
| 500 | internal_error | Unexpected server error | Safe to retry with exponential backoff and jitter. |
| 502 / 503 / 504 | service_unavailable | Temporary upstream or availability problem | Safe to retry with exponential backoff and jitter; check the status page. |
Upcoming fixtures for a sport, filterable by league, team or date range. Powers schedule pages, "next match" widgets and fixture-list views.
| Parameter | Type | Required | Description |
|---|---|---|---|
| league | string | No | Competition slug, e.g. premier-league. |
| team | string | No | Team slug or ID to filter fixtures for one club. |
| date_from | date | No | ISO 8601 date. Defaults to today. |
| date_to | date | No | ISO 8601 date. Defaults to +14 days. |
| page / per_page | integer | No | Standard pagination, see above. |
| Field | Type | Description |
|---|---|---|
| fixture_id | string | Stable fixture identifier (fx_…). Use it for odds, lineups, events, webhooks and WebSocket filters. |
| sport | string | Sport slug, e.g. football. |
| league | string | Competition display name. |
| league_slug | string | Competition slug accepted by the league filter. |
| season | string | Season key, e.g. 2025-2026. |
| home_team / away_team | string | Team display names. |
| home_team_id / away_team_id | string | Team identifiers (tm_…) usable with /teams and /statistics/team. |
| kickoff | string | Scheduled start, ISO 8601 UTC. |
| venue | string | null | Venue name when known. |
| status | string | scheduled, live, finished, postponed or cancelled. |
A single fixture with full detail — venue, officials, broadcast info and links to its lineups, events and odds once available.
| Parameter | Type | Required | Description |
|---|---|---|---|
| fixture_id | string | Yes | Unique fixture identifier returned by the fixtures list. |
| Field | Type | Description |
|---|---|---|
| fixture_id | string | Stable fixture identifier (fx_…). Use it for odds, lineups, events, webhooks and WebSocket filters. |
| sport | string | Sport slug, e.g. football. |
| league | string | Competition display name. |
| league_slug | string | Competition slug accepted by the league filter. |
| season | string | Season key, e.g. 2025-2026. |
| home_team / away_team | string | Team display names. |
| home_team_id / away_team_id | string | Team identifiers (tm_…) usable with /teams and /statistics/team. |
| kickoff | string | Scheduled start, ISO 8601 UTC. |
| venue | string | null | Venue name when known. |
| status | string | scheduled, live, finished, postponed or cancelled. |
| round | string | null | Round or matchday label. |
| officials | object | Match officials, e.g. referee. Empty until assigned. |
| broadcast | string[] | Broadcasters, when published. |
| links | object | Relative URLs for lineups, events and odds. Populated once the data exists. |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| league | string | No | Restrict to a single competition. |
| Field | Type | Description |
|---|---|---|
| fixture_id | string | Fixture identifier. |
| sport / league | string | Sport slug and competition name. |
| home_team / away_team | string | Team display names. |
| status | string | live while in play; the match leaves this endpoint once it is finished. |
| score | object | { home, away } integers. Sport-specific scoring (sets, innings, rounds) is exposed in score.detail when relevant. |
| minute | integer | null | Match clock in minutes; null for sports without a running clock. |
| period | string | Current period, e.g. 1st_half, 2nd_half, set_2, q3. |
| last_event | object | null | Most recent event: type, team, player, minute. |
| updated_at | string | When this snapshot was produced, ISO 8601 UTC. |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| league | string | No | Competition slug. |
| team | string | No | Filter to one team's results. |
| season | string | No | e.g. 2025-2026. Defaults to current season. |
| Field | Type | Description |
|---|---|---|
| fixture_id | string | Fixture identifier. |
| sport / league / season | string | Sport slug, competition name and season key. |
| home_team / away_team | string | Team display names. |
| kickoff | string | Scheduled start, ISO 8601 UTC. |
| status | string | Always finished on this endpoint. |
| score | object | Final score { home, away }. |
| half_time | object | null | Half-time score where the sport has halves. |
| winner | string | home, away or draw. |
| finished_at | string | When the result was confirmed, ISO 8601 UTC. |
The current league table — played, won, drawn, lost, goal difference and points — updated automatically after every result is confirmed.
| Parameter | Type | Required | Description |
|---|---|---|---|
| league | string | Yes | Competition slug. |
| season | string | No | Defaults to the current season. |
| Field | Type | Description |
|---|---|---|
| league / season | string | Competition and season the table belongs to. |
| updated_at | string | When the table was last recalculated, ISO 8601 UTC. |
| table[].position | integer | Rank in the table, starting at 1. |
| table[].team / team_id | string | Team name and identifier. |
| table[].played / won / drawn / lost | integer | Record. Sports without draws return drawn: 0. |
| table[].goals_for / goals_against / goal_difference | integer | Scoring totals (points or runs for other sports). |
| table[].points | integer | Competition points. |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| team_id | string | Yes | Team identifier. |
| season | string | No | Defaults to current season. |
| competition | string | No | Scope statistics to one competition only. |
| Field | Type | Description |
|---|---|---|
| team_id / team | string | Team identifier and display name. |
| season / competition | string | Scope of the numbers. competition is null when aggregated across all competitions. |
| matches_played | integer | Matches included in the aggregate. |
| stats | object | Sport-specific metrics. Football keys are shown; other sports return their own keys under the same object. |
Pre-match and live odds normalized into a single format across sportsbooks, so you compare markets without writing a parser per book.
| Parameter | Type | Required | Description |
|---|---|---|---|
| match_id | string | Yes | Fixture identifier. |
| market | string | No | e.g. 1x2, totals, player_props. |
| bookmaker | string | No | Restrict to a single sportsbook. |
| Field | Type | Description |
|---|---|---|
| fixture_id / sport | string | Fixture the prices belong to. |
| updated_at | string | Most recent price change across all books, ISO 8601 UTC. |
| markets | object | Keyed by market name (1X2, totals, player_props). Each value is an array of quotes. |
| markets.*[].bookmaker | string | Source sportsbook. |
| markets.*[].home / draw / away | number | Decimal odds. draw is omitted for two-way markets; totals markets use line, over, under. |
| markets.*[].updated_at | string | When this quote last changed. |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| league | string | No | Filter teams or players to one competition. |
| team_id | string | No | Filter players to one squad. |
| search | string | No | Free-text name search. |
| Field | Type | Description |
|---|---|---|
| team_id | string | Stable team identifier. |
| name / short_name | string | Display names. |
| country / venue | string | null | Country and home venue. |
| player_id | string | Stable player identifier. |
| team_id (player) | string | Current squad. null for free agents. |
| position / nationality | string | Position label and nationality. |
| date_of_birth | string | null | ISO 8601 date. |
Starting lineups, formations and substitutes for a fixture, plus a chronological event feed — goals, cards, substitutions and sport-specific events — as they're confirmed.
| Field | Type | Description |
|---|---|---|
| home / away.formation | string | null | Formation, 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_id | string | Unique, ordered event identifier. |
| events[].type | string | goal, card, substitution or a sport-specific type. |
| events[].minute / team / player | mixed | When it happened, and who was involved. |
| events[].detail | object | Type-specific extras (assist, card colour, replaced player…). |
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.
| Field | Type | Description |
|---|---|---|
| competition_id | string | Stable competition identifier. |
| name / slug | string | Display name and the slug used by the league parameter. |
| country / tier | string | integer | Country and level in the pyramid. |
| current_season | string | Season key currently in play. |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| league | string | No | Competition slug. |
| season_from / season_to | string | No | Season range, e.g. 2015-2016 to 2025-2026. |
| cursor | string | No | Recommended for large historical pulls. |
Same fields as Results — historical matches reuse the live schema field-for-field. Page with meta.pagination.next_cursor until it is null.
| Field | Type | Description |
|---|---|---|
| fixture_id | string | Fixture identifier. |
| sport / league / season | string | Sport slug, competition name and season key. |
| home_team / away_team | string | Team display names. |
| kickoff | string | Scheduled start, ISO 8601 UTC. |
| status | string | Always finished on this endpoint. |
| score | object | Final score { home, away }. |
| half_time | object | null | Half-time score where the sport has halves. |
| winner | string | home, away or draw. |
| finished_at | string | When the result was confirmed, ISO 8601 UTC. |
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.
| Field | Type | Description |
|---|---|---|
| id | string | Unique event id. Store it and ignore repeats — retries can deliver the same event more than once. |
| event | string | fixture.updated, fixture.finished, match.live.event or odds.changed. |
| sport | string | Sport slug. |
| created_at | string | When the event was generated, ISO 8601 UTC. |
| data | object | Event payload. Always contains fixture_id; other fields depend on event. |
| Header | Meaning |
|---|---|
| X-Orbistats-Signature | sha256=<hex> — HMAC-SHA256 of {timestamp}.{raw_body} using your endpoint's signing secret. |
| X-Orbistats-Timestamp | Unix time (seconds) when the delivery was signed. Reject deliveries older than 5 minutes. |
| Content-Type | application/json |
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.
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.
| Field | Type | Description |
|---|---|---|
| type | string | subscribed, score_update, match_event, odds_update, heartbeat or error. |
| channel | string | Channel the message belongs to, e.g. football.live, football.odds. |
| seq | integer | Increases by 1 per message on a channel. A jump means you missed messages — resync over REST. |
| sent_at | string | Server timestamp, ISO 8601 UTC. |
| data | object | Same field names as the matching REST object (fixture_id, score, minute, …). |
| code / message | string | Only 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.
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.
| Sport | Fixtures | Live | Standings | Statistics | Odds | Lineups | Historical |
|---|---|---|---|---|---|---|---|
| Football | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Basketball | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| American Football | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ |
| Cricket | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ |
| Tennis | ✓ | ✓ | — | ✓ | ✓ | — | ✓ |
| Baseball | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ |
| Horse Racing | ✓ | ✓ | — | — | ✓ | — | ✓ |
| Golf | ✓ | ✓ | ✓ | — | ✓ | — | ✓ |
| Combat Sports | ✓ | ✓ | — | — | ✓ | — | — |
| Esports | ✓ | ✓ | ✓ | ✓ | ✓ | — | — |
| Volleyball | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ |
| Handball | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ |
| Ice Hockey | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ |
SDKs & languages
Every endpoint on this page maps directly onto a method in each official SDK — same parameters, same response shape.
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.
Explore more of the platform
Related developer resources, product pages and research.
Quickstart
Make your first request in five minutes.
Sandbox
Try every endpoint above against live sample data.
SDKs
Official client libraries and code examples.
Documentation
Authentication, limits, errors and webhooks.
Sports Glossary
xG, implied probability and other terms explained.
Code Examples
Worked examples in Node.js and Python.
Changelog
New endpoints, changes and deprecations.
Sports Data API
Product overview for the core data feed.
Pricing
Free to start, transparent per-event rates at scale.
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.