Skip to content

Livematches in play

Demo: Matchboard, opens in a new tab

Glossary

Sports data glossary

A sports data glossary for people who build with match data: what each term means, how it differs between sports and, where the API returns it, the call that does. 55 terms in 5 groups.

Matches

The words for a single game: who plays, how time is counted, and what happens when a match does not end the ordinary way. Football leads, with the terms other sports use for the same ideas.

Fixturealso match, game, event

One scheduled contest between two sides, from the moment it is announced until its result is final.

In British usage a fixture is any match on the calendar, played or not; American sources tend to say game or event. A data feed uses the word for the whole record: teams, start time, competition, venue, status and score.

Each fixture keeps one id for life, so a match that is postponed and replayed weeks later is still the same object. Race sports such as Formula 1 and cycling have no fixtures: a field of competitors takes part in races and sessions instead.

In the API: GET /v2/fixtures/{id}

Lineup, formation and substitutionsalso starting eleven, team sheet, formation, substitution

The players a team starts with, the shape they line up in (such as 4-3-3), and the changes made from the bench during play.

A lineup splits a squad into starters and substitutes. A formation reads from defence to attack, so 4-2-3-1 means four defenders, two holding midfielders, three attacking midfielders and one striker; the goalkeeper is left out.

In football the official team sheets usually appear about an hour before kick-off. Lower leagues and friendlies may never publish one. A substitution swaps a player on the pitch for one from the bench and is recorded as a match event with the player coming on and the player going off.

In the API: GET /v2/fixtures/{id}/lineups

VAR and event correctionsalso VAR, video assistant referee, disallowed goal, score correction

A video review can cancel a goal or change a card, so live data must be able to take events back, not only add them.

The video assistant referee checks goals, penalties, red cards and mistaken identity. While a check runs, the fixture carries a varCheck field naming the side it concerns. If the decision overturns a goal, the score goes down and the goal event is corrected or removed.

Software that assumes scores only rise will show wrong results. Treat every update as the latest truth: replace the score, and match events by their stable key rather than appending duplicates. Basketball and other sports have reviews and score corrections too.

In the API: GET /v2/fixtures/{id}/events

Period and match clockalso half, quarter, match minute, game clock

A period is a fixed segment of play (half, quarter, period, set, inning); the clock says how much of it has gone.

What counts as a period depends on the sport: halves in football and rugby, quarters in basketball, three periods in ice hockey, sets in tennis and volleyball, innings in baseball. The score is kept per period as well as in total.

Rather than sending a new minute every second, a live fixture carries a clock object: when the current period started and how many seconds of play came before it. Your app adds the time since the period began and draws a running clock without extra requests. Tennis and other set sports often have no clock at all.

In the API: GET /v2/fixtures/{id}

Extra time and overtimealso extra time, overtime, AET, OT, extra innings

Additional play after regulation time when a match must have a winner and the scores are level.

Football knockout ties play two halves of 15 minutes, written as AET (after extra time) when they settle the match. Basketball, ice hockey and American football call it overtime, and baseball adds extra innings.

Stoppage time is different: the minutes added at the end of each half for time lost, still part of regulation. In the API, football extra time lives under the extra1 and extra2 period keys, overtime in other sports under overtime, and the finished match records how it ended so you can label it correctly.

In the API: GET /v2/fixtures/{id}

Penalty shoot-outalso shoot-out, shootout, penalties, AP

A series of alternating penalty kicks or shots that decides a knockout match still level after extra time.

Each side takes five attempts, then sudden death. Ice hockey and field sports use their own versions. The shoot-out result decides who advances, but it is not added to the match score: a 1–1 draw won 4–3 on penalties stays 1–1, with the shoot-out shown alongside.

That is how the API keeps it too: shoot-out goals sit in a separate penalties value, and the kicks are listed after the other events in the order they were taken. Ice hockey is the exception, adding one goal to the winner's score.

In the API: GET /v2/fixtures/{id}/events

Postponed, abandoned and walkoveralso postponed, suspended, abandoned, walkover, awarded result, forfeit

The statuses for matches that do not run their normal course: moved to a later date, stopped for good, or decided without play.

Postponed means the match will be played later; the fixture keeps its id and gets a new start time. Interrupted and suspended describe play halted partway, expected to resume, sometimes on another day. Abandoned means stopped and not resumed, so the API files it under canceled; the organiser may later replay it or award a result.

A walkover is a result awarded with no match played, usually because one side did not turn up. In tennis a player can also retire during a match or be defaulted. Filter on the status type, not on its display text.

In the API: GET /v2/fixtures/{id}

Innings and overs (cricket)also innings, over, scorecard, ball by ball

An innings is one side's turn to bat; an over is a set of six legal deliveries bowled by one bowler.

A T20 innings lasts at most 20 overs, a one-day innings 50, while Test cricket gives each side two innings with no over limit. Overs are written with a dot that counts balls, not tenths: 19.3 means 19 overs and three balls.

A cricket scorecard lists each innings with its batting card (runs, balls faced, dismissal) and bowling card (overs, maidens, runs conceded, wickets). Ball-by-ball detail, with the batter, bowler and outcome of every delivery, comes from the point-by-point endpoint on Pro. More on the cricket page.

In the API: GET /v2/fixtures/{id}/scorecard

Sets, tie-breaks and break points (tennis)also set, tie-break, tiebreak, break point, break of serve

Tennis is scored in points, games and sets; a tie-break settles a set at 6–6, and a break point is a chance to win the opponent's service game.

A set goes to the first player to win six games with a two-game lead. At 6–6 most events play a tie-break, first to seven points by two; its points are stored apart from the games, so a set can read 7–6 with a tie-break score next to it.

A break point arises when the receiver is one point from winning a game on the opponent's serve. Converting it is a break. Match statistics count break points faced, saved and converted; the point-by-point feed on Pro flags each one. See the tennis page.

In the API: GET /v2/fixtures/{id}/statistics

Heats, sessions and laps (motorsport)also heat, session, lap chart, qualifying, grid

Racing splits an event into timed sessions or heats, and a race into laps; positions are counted lap by lap.

A heat is a short race whose result decides who goes through or where they start. Formula 1 and MotoGP use practice, qualifying, sprint and race sessions instead, so a Grand Prix weekend is one race with several sessions.

A lap is one full circuit. Lap 0 is the starting grid, and a lap chart records every driver's position at the end of each lap, along with pit stops and retirements. Session results and timings are on every plan; the lap-by-lap chart for Formula 1 races needs Pro. See the motorsport page.

In the API: GET /v2/races/{id}

Maps and rounds (esports)also map, round, best of three, BO3, series

An esports match is a series of games, often played on different maps; in Counter-Strike each map is won round by round.

A best-of-three (BO3) series ends when one team wins two games. In Counter-Strike each game is played on a map chosen in a pick-and-ban phase, and each map is a race to win rounds. League of Legends and Dota 2 have no map choice, so a game is simply a game.

The games endpoint returns the series game by game: map, winner, each side's score and players, bans and objectives, and for Counter-Strike a record of every round. See the esports page.

In the API: GET /v2/fixtures/{id}/games

Competitions

How matches add up to a league or a cup: seasons, rounds, tables, brackets and the rules that separate teams level on points.

League vs cupalso league, cup, competition format, round robin

A league ranks every team in a table over a season; a cup eliminates teams in knockout ties until one is left.

In a league every team meets the others, usually home and away, and points decide the order. In a cup a defeat ends your run. Many competitions mix the two: the Champions League and the World Cup open with groups or a league phase, then switch to knockouts.

For data work the format decides which endpoints matter. A league season is read through its standings and rounds; a cup through its bracket. The API treats both as leagues with seasons, so the same calls apply and the empty ones simply return nothing.

Season and roundalso season, round, matchday, gameweek, campaign

A season is one edition of a competition, with its own id; a round is a batch of its fixtures, such as matchday 12 or the quarter-finals.

European football seasons cross the new year and are labelled 25/26, while summer leagues such as MLS run inside one calendar year. Ask for standings or rounds by season id and only display the label. Teams change between seasons through promotion and relegation, so never assume last year's members.

In leagues a round, or gameweek in fantasy football, usually gives each team one match; in cups rounds have names, such as round of 16. Round numbers repeat across phases, so a qualifying round 1 and a league-phase round 1 can both exist: identify a round by its slug and prefix. Some competitions, such as NBA regular seasons, have no rounds at all.

In the API: GET /v2/leagues/{id}/rounds

Standingsalso league table, table, rankings

The ranked table of a competition: position, matches played, wins, draws, losses, scores for and against, and points.

Football awards three points for a win and one for a draw. The NBA ranks on win percentage, the NHL gives a point for an overtime loss, and many sports have no draws. A season can hold several tables at once: conferences, divisions, groups, plus home-only and away-only versions.

Columns that do not apply to a sport are null rather than zero, and each row can carry a zone label and the team's recent form.

In the API: GET /v2/leagues/{id}/standings

Tiebreakersalso tie-breaking rules, goal difference, head-to-head rule

The ordered rules a competition uses to rank teams that finish level on points or win percentage.

The Premier League looks at goal difference, then goals scored. La Liga and Serie A look first at the matches between the tied teams. American leagues have long lists of their own, from division record to strength of schedule.

Because the rules differ, a table computed from results alone can disagree with the official one at the margins. Show the source's order. The standings response names the competition's rule where one is published, in meta.tieBreakRule.

In the API: GET /v2/leagues/{id}/standings

Form guidealso form, recent form, WDL

A team's most recent results in order, usually the last five, written as wins, draws and losses.

A string such as W W D L W reads oldest to newest, or newest first, depending on who prints it; agree on one order in your interface and label it. Form is often split into home and away, because many teams behave very differently on the road.

Before a match, the form endpoint returns both teams' recent results in the competition, their table positions and their latest five matches in any competition. Each standings row also carries up to five results, oldest first.

In the API: GET /v2/fixtures/{id}/form

Group stagealso groups, pool stage, league phase

The opening phase of many tournaments, where teams play in small round-robin groups and the best placed go through.

The World Cup, the European Championship and many basketball and handball tournaments use groups of three to six teams. Each group is a table of its own, and some formats also compare third-placed teams across groups.

Ask the standings endpoint with group=all to get every group table in one call; without it you receive the first group only, flagged as the primary table. When the groups finish, the competition continues in a knockout bracket.

In the API: GET /v2/leagues/{id}/standings

Knockout bracketalso cup tree, draw, playoff bracket, elimination bracket

The tree of ties in a knockout phase, showing who meets whom in each round and how winners advance to the final.

A bracket is drawn before the matches are known, so its later slots hold placeholders such as the winner of quarter-final 1. Tennis calls it the draw, and seeded players are spread out so they cannot meet early. A bye sends a team or player through without a match.

The cup-tree endpoint nests rounds, ties and participants, with each tie's result and the ids of its matches: aggregate goals in two-legged football ties, series wins in NBA and NHL playoffs, sets in tennis.

In the API: GET /v2/leagues/{id}/cup-trees

Aggregate scorealso aggregate, two-legged tie, on aggregate

The combined score of a tie played over two matches, one at each team's ground, which decides who goes through.

European club competitions and many domestic cups play ties over two legs. A 2–1 first-leg win and a 1–1 second leg give 3–2 on aggregate. If the aggregate is level, extra time and penalties follow, since away goals were dropped by UEFA in 2021.

Each leg is a separate fixture. The second leg points back to the first through previousLegFixtureId, and once it is complete aggregateWinner names the side that progressed.

In the API: GET /v2/fixtures/{id}

Promotion and relegation zonesalso relegation zone, drop zone, qualification places, playoff places

The table positions that lead to a reward or a penalty at season's end: promotion, a European place, playoffs or relegation.

In open league systems the bottom clubs drop a division and the top clubs of the division below come up, sometimes through playoffs. The top of a table often also qualifies for continental competitions.

Standings rows carry a zone label where the source marks one, such as "Champions League", "Playoffs" or "Relegation", so you can colour the table without hard-coding each league's rules, which change from season to season.

In the API: GET /v2/leagues/{id}/standings

Statistics

The numbers that describe how a match was played, from simple counts such as possession to model-based figures such as expected goals and win probability.

Expected goals (xG)also xG, expected goals

The probability that a shot becomes a goal, judged from shots like it; summed over a match, it measures the quality of chances.

A penalty is worth roughly 0.75 to 0.8 xG, a header from outside the box only a few hundredths. Adding up a team's shots gives its match xG, which often tells you more about how a game went than the score does.

xG models differ between providers, so compare figures from one source only. Team xG for a match is part of the free match statistics; the shot map on Pro gives the value of every single shot.

In the API: GET /v2/fixtures/{id}/statistics

Expected assists (xA)also xA, expected assists

The xG of the shots a player's passes set up, credited to the passer whether or not the shot went in.

Assists depend on a teammate finishing; xA does not. A playmaker who keeps creating good chances for poor finishers will show a high xA and few assists, which is why scouts and fantasy players look at both.

Season player statistics include expectedAssists next to expectedGoals and their sum, expectedGoalInvolvements, for covered football leagues.

In the API: GET /v2/players/{id}/statistics

Shot mapalso shotmap, shot chart

Every shot in a match plotted where it was taken, with its outcome and, in football, its expected goals value.

A football shot map shows where shots came from, how they were struck and whether they were scored, saved, blocked, missed or hit the post. Basketball's equivalent, the shot chart, marks every field-goal attempt as made, missed or blocked on the court.

The API returns shot maps for football, ice hockey and basketball in covered leagues, with pitch or court coordinates you can draw directly.

In the API: GET /v2/fixtures/{id}/shotmap · Pro plan

Heatmap and average positionsalso heat map, touch map, average positions

A heatmap shades where a player was active; average positions place each player at the mean of their match locations.

Both use coordinates from 0 to 100 across and along the pitch, turned so that each team attacks the same way. A heatmap reveals a full-back who lived in the opponent's half; an average-positions chart shows the shape a team really played, which may differ from its listed formation.

Match heatmaps cover one player in one football match, while a season heatmap sums a player's matches in a league. Average positions are per match, grouped by side.

In the API: GET /v2/fixtures/{id}/heatmap/{playerId} · Pro plan

Player ratingalso match rating, performance rating, player of the match

A single score, usually on a 0–10 scale, that sums up a player's contribution to one match from their statistics.

Ratings combine dozens of actions, from passes and duels to goals and errors, weighted by position. They make players comparable at a glance and drive features such as player of the match and team of the week.

Each provider weights actions its own way, so a 7.4 from one source is not a 7.4 from another. The API's football ratings come from our data source; a player's ratings across a season form a graph you can draw match by match.

In the API: GET /v2/players/{id}/ratings · Pro plan

Possessionalso ball possession, possession %

The share of the match, in percent, that a team had the ball; the two sides add up to 100.

Possession is usually estimated from passes and touches rather than measured with a stopwatch, so different sources can disagree by a few points. It describes style more than quality: a team can dominate the ball and still lose, especially against opponents who defend deep and counter.

In the API it is the ballPossession key of the football and rugby match statistics, a value from 0 to 100, broken down by period where available.

In the API: GET /v2/fixtures/{id}/statistics

Momentumalso attack momentum, pressure graph, match momentum

A minute-by-minute curve of which team was pushing, drawn above the line for the home side and below it for the away side.

Momentum graphs turn attacks, shots and dangerous possession into one value per minute, so a reader can see at a glance when a match turned. They are a summary for display, not a statistic to add up.

The API returns a point per minute for football, basketball and ice hockey in covered leagues, with each added-time minute as its own point. Tennis uses one value per game, plus whether serve was broken.

In the API: GET /v2/fixtures/{id}/momentum · Pro plan

Win probabilityalso live win probability, win chance, match prediction

A model's estimate of each outcome's chance, before kick-off and updated as the match goes on.

A win-probability curve starts from a pre-match estimate and moves with every goal, red card and passing minute: a one-goal lead is worth more with ten minutes left than with eighty. The three outcomes, home, draw and away, add up to 100%.

For football we run our own model, whose inputs are documented on the endpoint page; no bookmaker prices feed into it. It is an analytical indicator for display and research, not betting advice.

In the API: GET /v2/fixtures/{id}/win-probability · Pro plan

Head-to-headalso H2H, previous meetings

The record of two teams or players against each other: wins, draws and losses over their past meetings.

Head-to-head records are a staple of match previews and, in some leagues, a tiebreaker in the table. A long record can mislead when squads have changed, so most previews weigh recent meetings more.

The API gives the two sides' record over roughly their last ten meetings, seen from the upcoming fixture's home and away sides, plus the two managers' record against each other. A separate call lists every meeting.

In the API: GET /v2/fixtures/{id}/h2h

Streaksalso run, unbeaten run, winning streak

A team's current run of a repeated outcome, such as five wins in a row or seven of the last eight matches over 2.5 goals.

Streaks come in three shapes: consecutive matches (5 in a row), a share of recent matches (7 of the last 8) and an average (83 points a game). Show the shape with the number, since 5 alone is ambiguous.

The streaks endpoint returns each team's current runs before a match, plus runs drawn from their meetings with each other. A kind field tells you which of the three shapes each figure has.

In the API: GET /v2/fixtures/{id}/streaks

Box scorealso boxscore, stat line, player stats

A table of every player's statistics in one game, the standard summary of a basketball, baseball or American football match.

A basketball box score lists minutes, points, rebounds, assists, steals, blocks, turnovers and shooting splits per player, with team totals underneath. Baseball's version covers at-bats, hits, runs and RBIs for batters and innings, strikeouts and earned runs for pitchers.

In the API the per-player lines come with the lineups, each player carrying their match statistics, and the team totals with the match statistics.

In the API: GET /v2/fixtures/{id}/lineups

Play-by-playalso PBP, live commentary, point-by-point

The ordered list of every action in a game, each with its time, the players involved and, in basketball, the running score.

Where match events record only the big moments, play-by-play records everything: each basket, free throw, rebound and foul in basketball, or each shot, corner and card in football. It powers text commentary, replays and detailed analysis.

Entries arrive oldest first. Basketball entries also carry the game clock and the location of each shot on the court. Tennis and cricket have the equivalent in point-by-point and ball-by-ball form on a separate endpoint.

In the API: GET /v2/fixtures/{id}/play-by-play · Pro plan

Power play (ice hockey)also power play, man advantage, short-handed, PP%

A spell, usually two minutes, when one ice hockey team has more skaters on the ice because an opponent is serving a penalty.

Ice hockey is played in three 20-minute periods, and penalties send players to the box. A goal scored with the extra man is a power-play goal; one scored by the team a man down is short-handed. Teams are judged by how often they convert power plays and how well they kill penalties.

Goal events carry a powerPlay, shortHanded or emptyNet detail, and match statistics include powerPlayConversion. See the ice hockey page.

In the API: GET /v2/fixtures/{id}/statistics

Betting odds

How prices are written and what they imply, explained for developers who display or analyse odds. Definitions only: nothing here is advice to place a bet.

Decimal, fractional and American oddsalso decimal odds, fractional odds, American odds, odds formats

Three ways to write the same price: total return per unit staked (decimal), profit to stake (fractional), or a plus or minus figure (American).

Decimal 2.50 returns 2.50 per 1 staked, profit included. Fractional 6/4 shows profit against stake, so decimal = 1 + fractional. American odds centre on 100: +150 is the profit on 100 staked, while −200 is the stake needed to win 100.

The API gives every price in decimal and fractional form. To show American odds, convert from decimal: if it is 2.00 or more, (decimal − 1) × 100 with a plus sign; below 2.00, −100 / (decimal − 1), or try a price in the odds converter. Odds are for information only; follow the display rules where your users are.

In the API: GET /v2/fixtures/{id}/odds · Pro plan

Implied probabilityalso implied odds, break-even probability

The chance of an outcome that a price suggests, found by dividing 1 by the decimal odds.

Decimal odds of 2.00 imply 50%, 4.00 imply 25%. Because the bookmaker builds a margin into every price, the implied probabilities of all outcomes in a market add up to more than 100%, so they slightly overstate each outcome.

The winning-odds endpoint sets each side's implied chance against how often sides at that price have actually won, according to our data source, with the margin left in. It describes the market and predicts nothing.

In the API: GET /v2/fixtures/{id}/odds/winning · Pro plan

Overround (vig)also vig, vigorish, juice, bookmaker margin

The amount by which a market's implied probabilities exceed 100%: the margin a bookmaker keeps whatever the result.

If a football match is priced 2.10, 3.40 and 3.60, the implied chances are about 47.6%, 29.4% and 27.8%, a total near 104.8%. The extra 4.8 points are the overround.

To estimate fair probabilities, divide each implied probability by the total, so they sum to 100%. This simple method spreads the margin evenly; analysts use other methods too, and none of them makes a price a forecast.

Moneyline and 1X2also moneyline, 1X2, match result, three-way, match winner

The basic market on who wins: three-way 1X2 (home, draw, away) where draws happen, or two-way moneyline where they cannot.

In 1X2, 1 is a home win, X a draw and 2 an away win; in football it is settled on regular time, so extra time and penalties do not count. Moneyline is the American name for a two-way winner market, common in basketball, baseball and tennis.

The API calls these markets result and winner. The day's list of odds returns this headline market for every priced fixture of a sport in one request.

In the API: GET /v2/odds · Pro plan

Spread and handicapalso point spread, Asian handicap, handicap, line

A market that gives one side a head start or deficit, such as −1.5 goals or +6.5 points, to balance an uneven match.

With a −1.5 handicap a favourite must win by two or more. Asian handicaps in football use quarter and half lines to remove the draw or split the stake across two lines; the point spread is the same idea in American sports.

In the API a handicap market's line is the home side's handicap, and the market key includes it, for example asianHandicap:-1.25. When the line moves, a market with a new key appears.

In the API: GET /v2/fixtures/{id}/odds · Pro plan

Totals (over/under)also over/under, O/U, totals, total goals

A market on whether the combined score, or a count such as corners or cards, ends above or below a set line.

Over 2.5 goals wins with three or more goals. Half lines such as 2.5 make a tie impossible; whole lines such as 3 can end level, and the stake is then returned. Totals exist for goals, points, corners, cards and more.

The API keys each totals market by its line, for example totalGoals:2.5, so lines stay apart as the market moves.

In the API: GET /v2/fixtures/{id}/odds · Pro plan

Line movementalso odds movement, price movement, opening odds, drifting, shortening

The change in a price or line between the moment a market opens and now, which shows how the market's view has shifted.

A price that shortens (goes down) means the market now sees the outcome as more likely; one that drifts (goes up) means less likely. Lines move with team news, injuries and the volume of money.

Every market in the API carries its opening and current prices and the direction of the latest change: up, down or none. Over REST prices refresh roughly every 30 seconds in play; Business accounts can follow every change on a WebSocket channel.

In the API: GET /v2/fixtures/{id}/odds · Pro plan

API delivery

The engineering terms behind getting sports data into your product: requests, pushes, limits, identifiers and formats.

REST endpointalso endpoint, REST API, HTTP API

A URL you call with an HTTP method, such as GET, to read one kind of resource, such as a fixture, a table or a player.

REST models data as resources at stable addresses. Paths read like nouns, /v2/fixtures/{id}/lineups, and query parameters narrow the answer, ?sport=tennis. Responses are JSON, and each call stands alone, so any server can answer it and any client can cache it.

Every authenticated call counts as one request against your plan. The full list of paths is in the API reference.

Pollingalso short polling, refresh interval

Asking a REST endpoint for the latest data again and again at a fixed interval, for example every 15 seconds.

Polling is the simplest way to follow live sport: no open connection and no public server, and it works on every plan. Its costs are delay, up to one interval, and requests, which add up against the quota whether or not anything changed.

Cache one answer on your server and share it with every visitor, and poll slower when nothing is live. For a full comparison with push methods, read WebSocket vs webhooks vs polling.

In the API: GET /v2/livescores

WebSocketalso WSS, stream, push, socket

A connection that stays open between client and server so the server can push each change the moment it happens.

A WebSocket starts as an HTTP request and is then upgraded into a two-way channel. Your client subscribes to what it wants, receives a snapshot of the current state, then small updates as they happen. Frames do not count as requests.

To connect, request a one-time ticket over REST and open the URL it returns, so the API key never appears in a socket address. If the connection drops, reconnecting with the last sequence number you hold replays the frames you missed. The stream comes with Business; more on the real-time page.

In the API: POST /v2/stream/ticket · Business plan

Webhookalso webhooks, HTTP callback, event notification

An HTTP POST that the API sends to your server whenever a chosen event happens, such as a goal or a final whistle.

With webhooks you keep no connection open: you register a public https:// URL and filters, and each event arrives as its own signed JSON request. Answer with a 2xx within 10 seconds; otherwise the delivery is retried over several hours.

Verify the DSA-Signature header on every request and drop duplicates by event id, since order is not guaranteed. Webhooks come with Business.

In the API: POST {your endpoint URL} · Business plan

Delta (patch)also delta, patch, partial update, diff

A message that carries only the fields that changed, to be merged into the full object you already hold.

Sending a whole fixture for every goal wastes bandwidth. A delta sends only what changed, for example the away side's new score, and your client merges it in: nested objects key by key, every other value replacing the old one, null included.

WebSocket deltas and the changes in webhook events share this shape. A delta only touches a fixture you have already received in full, so keep the first copy and apply each change in order.

In the API: WebSocket delta frame · Business plan

Idempotencyalso idempotent, deduplication, at-least-once delivery

An operation is idempotent when doing it twice has the same effect as doing it once, which makes retries safe.

Network failures force retries, and retries cause repeats. Reading data with GET is idempotent by nature: ask again and nothing changes. Receiving data is where it matters. Webhooks are delivered at least once, so the same event can arrive twice, and out of order.

Make your handler idempotent: store each event's id (sent in the DSA-Event-Id header), skip any you have already processed, and write results as "set the score to 2–1" rather than "add one goal".

Rate limit, quota and 429also rate limit, quota, 429 Too Many Requests, Retry-After, rate_limited, quota_exceeded, throttling

Two ceilings on usage, requests per minute and requests per day or month; going over either returns HTTP 429 with a Retry-After header.

The rate limit absorbs bursts: Free allows 10 requests a minute. The quota caps volume: 1,000 requests a day on Free and a monthly allowance on paid plans, both following the UTC calendar. Both apply per account, so extra keys do not raise them. Responses report the quota in RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset.

Past either ceiling the API answers 429, with rate_limited or quota_exceeded as the error code and Retry-After giving the seconds to wait. Pause that long instead of retrying in a tight loop, and keep showing your last good data meanwhile. Per-minute refusals do not use up quota. Details are on the limits and errors pages.

Response envelope and paginationalso envelope, data and meta, pagination, paging, hasNextPage

Every response wraps its result in a data field, with facts about it in a meta field; long lists come in pages you request one after another.

A successful call returns { data, meta }: data holds the object or list you asked for, meta the counts, sport, season or page applied. A failed call returns a proper HTTP status with { error: { code, message } }. Branch on error.code, which is stable; the message is written for people and may change.

Some lists are too long for one response, such as every fixture of a sport on a busy Saturday. Request page 0, then the next, until meta.hasNextPage is false. Each page costs one request, so filter narrowly, by league or country, when you can.

In the API: GET /v2/fixtures

API keyalso secret key, bearer token, access token

A secret string that identifies your account on every request and decides which plan's limits and endpoints apply.

Send the key in the Authorization: Bearer … header. Keep it on a server or in an environment variable; anything shipped to a browser or a mobile app can be read by its users.

If a key leaks, revoke it in the dashboard and create another. The WebSocket uses a short-lived ticket so the key never appears in a URL, and widgets use separate keys that are limited to the sites you register.

Stable idsalso identifiers, ids, primary key

Identifiers that never change for the same team, player, league or match, so you can store them and join data safely.

Names are bad keys: clubs rename, players change spelling across languages, and two teams can share a name. Each object in the API carries a numeric id that we assign, the same in every endpoint and on the WebSocket.

A postponed match keeps its id, and odds markets and match events have keys that stay fixed within their fixture. Store ids in your database and look up names only for display.

ISO 8601 UTC timestampsalso ISO 8601, UTC, timestamp, time zone

Dates and times written in the international standard format and in Coordinated Universal Time, such as 2026-11-18T19:45:00.000Z.

The trailing Z means UTC. Every time in the API is UTC, so a kick-off is one instant wherever your users are, and day queries follow the UTC calendar. Convert to the viewer's time zone only when you display it.

Late kick-offs in the Americas fall on the next UTC day, so a local "today" view may need two day queries. WebSocket frames also carry ts, the server time in Unix milliseconds.

CDN imagesalso team logos, crests, player photos, image CDN

Logos, crests and photos served from a content delivery network, close to the user, rather than from the API servers.

Objects carry an image URL, for a team in the form /v2/teams/{id}/logo. Point an img tag straight at it and let the CDN cache it near your visitors, instead of copying files to your own server.

Logos and photos are included on every plan. Set a fixed width and height in your layout so pages do not jump while images load, and keep a fallback for the rare object without one.

OpenAPI and JSON Schemaalso OpenAPI, Swagger, JSON Schema, API spec

Machine-readable descriptions of an API: OpenAPI lists its paths and parameters, JSON Schema the shape of each object.

An OpenAPI document lets tools generate typed clients, mock servers and test suites, and lets AI assistants and API explorers understand an API without reading prose. OpenAPI 3.1 describes request and response bodies with JSON Schema.

Our spec is published at /openapi.json and regenerated on every build of the site, so it always matches the API reference.

SDKalso client library, software development kit, wrapper

A library for one programming language that wraps an API's calls, types and error handling so you write less plumbing.

A good SDK handles authentication, retries after 429 and typed responses. For a stream it also takes care of tickets, heartbeats, reconnects and replay, which is easy to get subtly wrong by hand.

Official packages exist for TypeScript and Python, along with a Go client and a command-line tool. Installation and examples are in the SDK docs.

Freshness and latencyalso latency, data freshness, delay, real-time

Latency is the delay between something happening and your app showing it; freshness is how current a piece of data is.

End-to-end latency has several parts: the source reporting the event, our processing, and delivery to you. Delivery is where your choice matters: polling adds up to one interval, while a stream or webhook pushes the change as soon as it is published.

Not everything changes at the same speed: a live score moves within seconds, a league table once a day. The freshness page lists how current each endpoint is.

Put the terms to work: use a premier league table api in python, build a discord bot for live football scores, build a football fixtures calendar as an ics feed, or the odds converter.

Your key is one form away.

1,000 free requests a day during the beta. No card, no sales call.