# SportsAPI

> Real-time sports data API for 20 sports: live scores, fixtures, lineups, statistics, standings, teams, players and leagues as JSON with our own stable ids, plus a WebSocket for live changes.

Base URL: https://api.sportsapi.app. Send your API key as `Authorization: Bearer <key>` on every /v2 request; keys are created in the dashboard (https://sportsapi.app/dashboard). Every success is `{ data, meta? }`; errors are `{ error: { code, message } }` with a real HTTP status. SDKs for TypeScript, Python and Go, and a CLI.

## Docs

- [Overview](https://sportsapi.app/markdown/en/docs.md): authentication, SDKs and CLI, rate limits and plans, errors, data freshness, the WebSocket protocol, every endpoint and the changelog
- [Data reference](https://sportsapi.app/markdown/en/reference.md): every object, WebSocket frame, enum, status code, position and statistic key

## Catalog

- [GET /v2/sports](https://sportsapi.app/markdown/en/docs/catalog/sports-list.md): Every supported sport with its current in-progress match count (matches the source never closed — no change for 45 min and started longer ago than the sport can last — are not counted).

## Live scores

- [GET /v2/livescores](https://sportsapi.app/markdown/en/docs/livescores/list.md): All in-progress fixtures across every sport, or one sport’s in-play board with ?sport= (each listed match as the live index holds it — the same state as the no-sport form and the WebSocket).

## Fixtures

- [GET /v2/fixtures](https://sportsapi.app/markdown/en/docs/fixtures/list.md): Fixtures kicking off on one UTC calendar day — for one league, or for a whole sport ten leagues per page (in the order the leagues are ranked).
- [GET /v2/fixtures/{id}](https://sportsapi.app/markdown/en/docs/fixtures/get.md): Full fixture: teams, score, status, match clock, league, season, round, venue, winner, the referee (with career cards per game), both managers (homeManager / awayManager), previousLegFixtureId (our i…
- [GET /v2/fixtures/{id}/lineups](https://sportsapi.app/markdown/en/docs/fixtures/lineups.md): Lineups, formations and missing players, with each player’s match rating and statistics.
- [GET /v2/fixtures/{id}/statistics](https://sportsapi.app/markdown/en/docs/fixtures/statistics.md): Match statistics grouped by period and category.
- [GET /v2/fixtures/{id}/events](https://sportsapi.app/markdown/en/docs/fixtures/events.md): Incidents — goals, cards, substitutions, period markers, added-time boards — oldest first (chronological).
- [GET /v2/fixtures/{id}/play-by-play](https://sportsapi.app/markdown/en/docs/fixtures/play-by-play.md): The source’s text commentary, one entry per action, oldest first: football (cards, shots, corners, substitutions, … by minute) and basketball (every basket, free throw, rebound, foul, turnover — with…
- [GET /v2/fixtures/{id}/h2h](https://sportsapi.app/markdown/en/docs/fixtures/h2h.md): Head-to-head record between the two teams (from this fixture’s home/away perspective), as the source counts it: their recent meetings — usually about the last ten — and the fixture itself once it is …
- [GET /v2/fixtures/{id}/h2h/fixtures](https://sportsapi.app/markdown/en/docs/fixtures/h2h-fixtures.md): The two teams’ meetings as fixtures, oldest first by kick-off, without the fixture asked about — scheduled meetings included.
- [GET /v2/fixtures/{id}/best-players](https://sportsapi.app/markdown/en/docs/fixtures/best-players.md): Player of the match and the best-rated players of each side.
- [GET /v2/fixtures/{id}/momentum](https://sportsapi.app/markdown/en/docs/fixtures/momentum.md): Attack-momentum graph: one point per minute, positive = home pressure, negative = away.
- [GET /v2/fixtures/{id}/win-probability](https://sportsapi.app/markdown/en/docs/fixtures/win-probability.md): Our own win-probability model for a football fixture: the pre-match estimate, the current home / draw / away probabilities and the curve — a point at kick-off, every minute, and right after each goal…
- [GET /v2/fixtures/{id}/commentary](https://sportsapi.app/markdown/en/docs/fixtures/commentary.md): AI match commentary for a football fixture, oldest first (by seq; the newest 100): one short entry per goal, red card, missed penalty, VAR decision, period start / end, big chance and sustained momen…
- [GET /v2/fixtures/{id}/shotmap](https://sportsapi.app/markdown/en/docs/fixtures/shotmap.md): Every shot with its outcome and expected goals, oldest first: football (expectedGoals / expectedGoalsOnTarget, situation, body part, pitch and goal-mouth coordinates), ice hockey (technique, strength…
- [GET /v2/fixtures/{id}/form](https://sportsapi.app/markdown/en/docs/fixtures/form.md): Both sides’ form going into the fixture: last results (oldest first), league position, the table figure as numbers (football: points; W-L / W-D-L sports: wins, draws, losses) and average rating.
- [GET /v2/fixtures/{id}/streaks](https://sportsapi.app/markdown/en/docs/fixtures/streaks.md): Team streaks before the fixture — each side’s recent run (wins, unbeaten, over 2.5 goals, …) and streaks over their meetings.
- [GET /v2/fixtures/{id}/heatmap/{playerId}](https://sportsapi.app/markdown/en/docs/fixtures/heatmap.md): Where one player was active during the fixture: every position sample, in pitch percentages.
- [GET /v2/fixtures/{id}/average-positions](https://sportsapi.app/markdown/en/docs/fixtures/average-positions.md): Each player’s average position in the fixture, per side.
- [GET /v2/fixtures/{id}/points](https://sportsapi.app/markdown/en/docs/fixtures/points.md): The match point by point.
- [GET /v2/fixtures/{id}/scorecard](https://sportsapi.app/markdown/en/docs/fixtures/scorecard.md): Cricket: the full scorecard, innings by innings — totals, extras, the batting card (state, dismissal, bowler, fielder, runs, balls, fours, sixes, strike rate), the bowling card (overs, maidens, runs,…
- [GET /v2/fixtures/{id}/umpires](https://sportsapi.app/markdown/en/docs/fixtures/umpires.md): Baseball: the umpire crew — name, position (homePlate, firstBase, secondBase, thirdBase, leftField, rightField, other) and years of experience.
- [GET /v2/fixtures/{id}/weather](https://sportsapi.app/markdown/en/docs/fixtures/weather.md): Baseball: the weather at the ballpark — the observation, then the forecast — in metric units (°C, %, km/h).
- [GET /v2/fixtures/{id}/games](https://sportsapi.app/markdown/en/docs/fixtures/games.md): Esports: the series game by game — status, map, start and duration, winner, and per side the score, players (role, champion / hero, kills, deaths, assists, then the title’s own figures — League of Le…

## Teams

- [GET /v2/teams/{id}](https://sportsapi.app/markdown/en/docs/teams/get.md): Team profile: country, sport, venue, colours, logo, gender, national team or club, kind (team / individual / pair), manager — and, for an individual competitor the source profiles (tennis, MMA), pers…
- [GET /v2/teams/{id}/fixtures](https://sportsapi.app/markdown/en/docs/teams/fixtures.md): A page of the team’s recent or upcoming fixtures.
- [GET /v2/teams/{id}/squad](https://sportsapi.app/markdown/en/docs/teams/squad.md): The current squad: every player’s profile plus contract end and current injury.
- [GET /v2/teams/{id}/transfers](https://sportsapi.app/markdown/en/docs/teams/transfers.md): The team’s moves in (arrivals) and out (departures), about the last year, newest first: transfers with their fee, loans and loan ends, and the US leagues’ roster moves — signings, trades, the draft, …
- [GET /v2/teams/{id}/statistics](https://sportsapi.app/markdown/en/docs/teams/statistics.md): The team’s season statistics in one league: totals and averages (goals scored and conceded, shots, possession, rating, clean sheets, …).
- [GET /v2/teams/{id}/leagues](https://sportsapi.app/markdown/en/docs/teams/leagues.md): Every competition the team plays in or has played in — domestic league, cups, European competitions, friendly tournaments.
- [GET /v2/teams/{id}/trophies](https://sportsapi.app/markdown/en/docs/teams/trophies.md): The team’s trophy cabinet: every competition it has won, the competition type (domestic league, domestic cup, international cup, other), whether it is a major title, how often, and the seasons (newes…
- [GET /v2/teams/{id}/position-history](https://sportsapi.app/markdown/en/docs/teams/position-history.md): The team’s league position at the end of each week of one season, week 1 first, with the fixtures it played that week.
- [GET /v2/teams/{id}/career-statistics](https://sportsapi.app/markdown/en/docs/teams/career-statistics.md): An MMA fighter’s career statistics: strikes landed and absorbed per round by target (head, body, legs) and position (distance, clinch, ground), accuracy and defence shares, takedowns and submissions …

## Players

- [GET /v2/players/{id}](https://sportsapi.app/markdown/en/docs/players/get.md): Player profile: position, detailed positions (goalkeeper, centreBack, leftWinger, striker, …; [] when the source lists none), team, nationality, physicals, market value, contract end, current injury …
- [GET /v2/players/{id}/transfers](https://sportsapi.app/markdown/en/docs/players/transfers.md): The player’s career moves, newest first — the same Transfer objects as a team’s list.
- [GET /v2/players/{id}/seasons](https://sportsapi.app/markdown/en/docs/players/seasons.md): The leagues and seasons the player has statistics for, with the statistics types available in each (overall, home, away, regularSeason, playoffs).
- [GET /v2/players/{id}/fixtures](https://sportsapi.app/markdown/en/docs/players/fixtures.md): A page of the player’s most recent fixtures (the teams he played for), newest first on every page (since 2026-10-24).
- [GET /v2/players/{id}/statistics](https://sportsapi.app/markdown/en/docs/players/statistics.md): The player’s season statistics in one league: totals and averages (goals, minutes, averageRating, expected goals, passes, duels, …).
- [GET /v2/players/{id}/attributes](https://sportsapi.app/markdown/en/docs/players/attributes.md): A football player’s attribute ratings from the source’s scouting model (0–100): attacking, technical, tactical, defending and creativity — for goalkeepers saves, anticipation, ball distribution, aeri…

## Leagues

- [GET /v2/leagues/{id}](https://sportsapi.app/markdown/en/docs/leagues/get.md): League profile: level in its country’s pyramid (tier), gender, the title holder and how often it won, the record title holders, the divisions above and below, and the current season’s first and last …
- [GET /v2/leagues/{id}/seasons](https://sportsapi.app/markdown/en/docs/leagues/seasons.md): Available seasons, newest first.
- [GET /v2/leagues/{id}/seasons/{seasonId}](https://sportsapi.app/markdown/en/docs/leagues/season.md): Season facts: totals so far (goals, home / away wins, draws, cards, …) and the newcomers — relegated from above, promoted from below.
- [GET /v2/leagues/{id}/standings](https://sportsapi.app/markdown/en/docs/leagues/standings.md): Standings for one season.
- [GET /v2/leagues/{id}/rounds](https://sportsapi.app/markdown/en/docs/leagues/rounds.md): The rounds of a season and the current one.
- [GET /v2/leagues/{id}/fixtures](https://sportsapi.app/markdown/en/docs/leagues/fixtures.md): The fixtures of one round of a season.
- [GET /v2/leagues/{id}/top-players](https://sportsapi.app/markdown/en/docs/leagues/top-players.md): Season leaderboards: the top players per statistic (rating, goals, xG, assists, tackles, saves, … — up to 50 each at the source), paged: limit players per leaderboard (default 10), or one leaderboard…
- [GET /v2/leagues/{id}/top-teams](https://sportsapi.app/markdown/en/docs/leagues/top-teams.md): Season team leaderboards: the top teams per statistic (average rating, goals scored, clean sheets, possession, …), paged like top-players.
- [GET /v2/leagues/{id}/player-statistics](https://sportsapi.app/markdown/en/docs/leagues/player-statistics.md): The season’s player-statistics explorer (football): every player of the league, 20 a page, sorted by any statistic, with a group of columns — summary, attack, defense, passing, goalkeeping or other —…
- [GET /v2/leagues/{id}/cup-trees](https://sportsapi.app/markdown/en/docs/leagues/cup-trees.md): The season’s knockout brackets — a cup’s knockout stage, playoffs, a tennis draw: rounds → ties → the two participants (team, seed, winner, score) → our fixture ids.
- [GET /v2/leagues/{id}/team-of-the-week/periods](https://sportsapi.app/markdown/en/docs/leagues/team-of-the-week-periods.md): The rounds (football and other round-based leagues) or weeks (NBA) of a season that have a team of the week, newest first.
- [GET /v2/leagues/{id}/team-of-the-week](https://sportsapi.app/markdown/en/docs/leagues/team-of-the-week.md): The team of the week of one round or week: the best-rated players as a line-up — formation, each player with his team, position, the rating that earned the place and the match it is from.

## Discovery

- [GET /v2/rankings](https://sportsapi.app/markdown/en/docs/discovery/rankings-list.md): The rankings we serve: FIFA (men), UEFA country and club coefficients, World Rugby (men), ATP and WTA singles (official and live) and the UFC divisions.
- [GET /v2/rankings/{type}](https://sportsapi.app/markdown/en/docs/discovery/rankings-get.md): One ranking table, best first: position and previous position, points and previous points, best position, tournaments played.
- [GET /v2/categories](https://sportsapi.app/markdown/en/docs/discovery/categories-list.md): A sport’s categories: the source’s grouping of leagues — countries, regions (Europe, International), tours (ATP), esports games.
- [GET /v2/leagues](https://sportsapi.app/markdown/en/docs/discovery/leagues-list.md): The league directory: every league of one category, or of one sport in one country.
- [GET /v2/leagues/popular](https://sportsapi.app/markdown/en/docs/discovery/leagues-popular.md): The source’s own pick of a sport’s popular leagues for a visitor’s country, in its order — the home country’s leagues and the big international competitions first.

## Race sports

- [GET /v2/races](https://sportsapi.app/markdown/en/docs/races/list.md): Races with a session starting on one UTC day, each with all its sessions.
- [GET /v2/races/{id}](https://sportsapi.app/markdown/en/docs/races/get.md): One race: series, season, round, status, days, host country, circuit (motorsport), laps and distance, category (cycling), winner — and its sessions in start order, each with type, status, start time,…
- [GET /v2/races/{id}/results](https://sportsapi.app/markdown/en/docs/races/results.md): The race’s classification — motorsport: the main race session’s (the last session of type race: grid, pit stops, tyres, best laps, points; meta.session names it); a cycling stage race: the general cl…
- [GET /v2/series](https://sportsapi.app/markdown/en/docs/races/series-list.md): The race sports’ directory: the series of one category — Nascar → NASCAR Cup Series, Truck Series, Xfinity; Formula 1 → Formula 1; cycling’s International → Cycling Men, Cycling Women.
- [GET /v2/series/{id}](https://sportsapi.app/markdown/en/docs/races/series-get.md): A racing series: name, slug, sport.
- [GET /v2/series/{id}/seasons](https://sportsapi.app/markdown/en/docs/races/series-seasons.md): The series’ seasons, newest first.
- [GET /v2/series/{id}/races](https://sportsapi.app/markdown/en/docs/races/series-races.md): The races of one season of the series (without sessions — /v2/races/{id} has them).
- [GET /v2/series/{id}/standings](https://sportsapi.app/markdown/en/docs/races/series-standings.md): The championship table of a season: the drivers’ / riders’ (type=competitors, default) or the teams’ (type=teams) — points, wins, podiums, pole positions, fastest laps, races started and races with p…

## Referees & managers

- [GET /v2/referees/{id}](https://sportsapi.app/markdown/en/docs/people/referees-get.md): A referee: country, sport, career totals (matches, yellow, red and second-yellow cards) and the figures per competition (appearances, cards, penalties awarded).
- [GET /v2/referees/{id}/fixtures](https://sportsapi.app/markdown/en/docs/people/referees-fixtures.md): A page of the matches the referee officiated (recent) or is appointed to (upcoming) — the same list rule as team fixtures.
- [GET /v2/managers/{id}](https://sportsapi.app/markdown/en/docs/people/managers-get.md): A manager / head coach: country, date of birth, preferred formation, current team, career record (games, wins, draws, losses, goals, points) and every job with its own record, newest first.
- [GET /v2/managers/{id}/fixtures](https://sportsapi.app/markdown/en/docs/people/managers-fixtures.md): A page of the manager’s recent or upcoming matches — the same list rule as team fixtures.

## Venues

- [GET /v2/venues/{id}](https://sportsapi.app/markdown/en/docs/venues/get.md): A stadium or arena: city, country, capacity, coordinates, a photo, the teams that play their home games there and, per sport, its record over every match the source has there (matches, goals or point…
- [GET /v2/venues/{id}/fixtures](https://sportsapi.app/markdown/en/docs/venues/fixtures.md): A page of the matches played or to be played at a venue, in one sport — the same list rule as team fixtures.

## Search

- [GET /v2/search](https://sportsapi.app/markdown/en/docs/search/query.md): Unified search across teams (and individual competitors), players, leagues, managers, referees, racing series, races, fixtures and venues — each hit’s type says which endpoint its id belongs to (/v2/…

## Widgets

- [GET https://sportsapi.app/widgets/v1.js](https://sportsapi.app/markdown/en/docs/widgets/script.md): The widget script.

## Bulk exports

- [POST /v2/exports](https://sportsapi.app/markdown/en/docs/exports/create.md): Start an export of one league season.
- [GET /v2/exports/{id}](https://sportsapi.app/markdown/en/docs/exports/get.md): One export.
- [GET /v2/exports](https://sportsapi.app/markdown/en/docs/exports/list.md): Your last 20 exports, newest first, with fresh download links for the ready ones.

## Webhooks

- [POST {your endpoint URL}](https://sportsapi.app/markdown/en/docs/webhooks/event.md): One request per event and endpoint.

## WebSocket

- [POST /v2/stream/ticket](https://sportsapi.app/markdown/en/docs/websocket/stream-ticket.md): Mint a single-use connection ticket, valid for 30 seconds.
- [WS wss://api.sportsapi.app/?ticket={ticket}](https://sportsapi.app/markdown/en/docs/websocket/connect.md): Connect to the url from the ticket.

## Optional

- [Everything in one file](https://sportsapi.app/llms-full.txt): the overview, every endpoint and the data reference
- [OpenAPI 3.1](https://api.sportsapi.app/v2/openapi.json): the machine-readable contract