Skip to content

Scores

Product id: scores

The facts of every game, without odds and without our reading of them: the live scoreboard while it is played, and the scoresheet of how it ended. Use it to show results, or to settle with your own rules. A key with only scores receives no prices.

The live board

The games in play, as events without markets: status, score and clock, with rotation and schedule, under the same evt_ as in live, pregame and props.

  • GET /v1/scores/events lists them (example); the stream follows them with products=scores.
  • A game leaves the board when it ends; its scoresheet follows.

Scoresheets

How a game ended. Complete example.

Field What it is
eventId, sport, league, participants, startAt As in the event: a scoresheet outlives it
status How it ended. Played out: finished. Stopped part way, with its completed periods standing: retired, abandoned, incomplete. Not played: postponed, cancelled, walkover, not_played
score The final {home, away}: sets in tennis, volleyball and the other set sports. null when the game was not played, and when one source alone says it did not finish: a score nobody saw is never published
periods {period, home, away} for each period we are sure of, with ids from /v1/catalog/periods (1h, q1, p1, i1, set1…). Extra time and shoot-outs are not listed here: regulation says whether the game went to them
regulation null when the final is the score at the end of regulation time. Otherwise, see Regulation time
stats Per team: {key, home, away}, with keys from /v1/catalog/stat-keys (corners, yellowCards, shotsOnTarget…)
timeline Goals and cards, in order: {type, minute, addedTime, team, player, participantId, ownGoal, penalty}. See Timeline
players The boxscore: {name, participantId, team, stats}
appearances Who played, from the lineups. See Appearances
confidence confirmed, provisional or disputed. See Confidence
sources {agreeing, disagreeing}: how many independent sources report this final, and how many report another
revision Grows with every change of the facts, and may skip numbers. A higher revision replaces a lower one, never the other way round
corrected true when this scoresheet replaces a confirmed one with other facts, or withdraws its confirmation. It stays true in later revisions
updatedAt When this revision was published: what updatedSince filters on

Confidence

Value Meaning
confirmed At least two independent sources agree on the final
provisional One source says so. It may change, or turn out to be another game's end
disputed The sources disagree

Settle only on confirmed. provisional and disputed scoresheets are published so that you can show them, always marked. An end other than finished that only one source gives is never confirmed.

Ask for confidence=confirmed (REST and stream) and you receive only scoresheets whose confidence is confirmed. A correction is among them when it is confirmed itself (corrected: true, other facts): check what you settled on the earlier one.

Withdrawn confirmations

Rarely, a confirmation is withdrawn: a new revision of the game's scoresheet is provisional or disputed, with corrected: true. That revision is not in confidence=confirmed, which then has no scoresheet for the game (REST answers 404). Check anything you settled on the game.

  • On the stream, both come. The new revision itself comes as a scoresheet message (provisional or disputed, corrected: true) to every client without confidence=confirmed. And every client whose filters include the game, with confidence=confirmed too, gets a scoresheet.withdrawn message, {"eventId", "revision", "confidence", "updatedAt"}. A withdrawal that happened while you were away comes in the messages a resume with since replays.
  • A snapshot does not carry it. After every snapshot of scores (not after a resume), catch up with GET /v1/scores?updatedSince=<the newest updatedAt you hold> without the confidence filter: a withdrawal is a scoresheet with corrected: true whose confidence is not confirmed.
  • On REST, confidence=confirmed never shows a withdrawal. If you poll instead of following the stream, poll without the filter and settle only on the confirmed scoresheets.

Regulation time

regulation is given for soccer, futsal, handball, rugby union, rugby league, basketball, American football, ice hockey and baseball, when the game may have gone past regulation time:

  • home, away: the score when regulation time ended; null when not known for certain;
  • wentTo: extra_time (extra time, overtime or extra innings) or shootout;
  • shootout: the shoot-out's {home, away}, or null.

wentTo is null when the records do not say: overtime or the shoot-out in ice hockey, or not even whether the game went past regulation (then every field is null). In that case, do not settle a regulation-time market on the final.

Timeline

Goals and cards, in order. type is goal, yellow_card or red_card. minute is the game clock's minute, with stoppage time apart: a goal at 45+2 is minute: 45, addedTime: 2. A goal's team is the side it counted for: an own goal counts for the opponent of the player who scored it (ownGoal: true). A card's team is the player's side; a second yellow comes as the red_card it is.

participantId is the player's par_, the one his markets use when they spell his name the same way: check the name too.

Appearances

Who played, from the lineups: {name, participantId, team, status, minute, addedTime, sources}.

  • status: started, came_on (a substitute who came on; minute and addedTime say when) or unused (on the bench, never came on): the one most sources give.
  • sources: {agreeing, disagreeing} for that status.
  • A player the sources split evenly on is left out, and so is one no lineup lists.
  • Given for soccer, in games with player markets that need it (goals, goalscorers, cards); empty otherwise.

It is a fact, not a rule: whether a player's prop is void is the grading's decision.

Revisions

A scoresheet can arrive several times; each revision replaces the last. Statistics, the timeline and the boxscore can come in a later revision than the score. If you settled on an earlier revision, compare its facts with the new one.

Getting scoresheets

  • On the stream, a scoresheet message, with the whole scoresheet. In a snapshot of scores, each event on the board is followed by its scoresheet when it has one. A correction to a game that has already left the board still comes as a scoresheet message: match it by eventId.
  • GET /v1/scores/{eventId}: the latest scoresheet of one game. With confidence=confirmed, 404 while the latest is not confirmed.
  • GET /v1/scores?updatedSince=…: every scoresheet revised since then, paginated, oldest first. After a fresh snapshot, catch up on the games that already left the board with updatedSince set to the newest updatedAt you hold.

A scoresheet is kept 30 days after its last revision, also once the game has left the board.

Combine it with

  • Any product of lines, to settle with your own rules: the scoresheet uses the same evt_ and the same player par_ ids.
  • Grading, to take our verdicts instead.