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/eventslists them (example); the stream follows them withproducts=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
scoresheetmessage (provisionalordisputed,corrected: true) to every client withoutconfidence=confirmed. And every client whose filters include the game, withconfidence=confirmedtoo, gets ascoresheet.withdrawnmessage,{"eventId", "revision", "confidence", "updatedAt"}. A withdrawal that happened while you were away comes in the messages a resume withsincereplays. - A snapshot does not carry it. After every snapshot of
scores(not after a resume), catch up withGET /v1/scores?updatedSince=<the newest updatedAt you hold>without theconfidencefilter: a withdrawal is a scoresheet withcorrected: truewhoseconfidenceis notconfirmed. - On REST,
confidence=confirmednever 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;nullwhen not known for certain;wentTo:extra_time(extra time, overtime or extra innings) orshootout;shootout: the shoot-out's{home, away}, ornull.
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;minuteandaddedTimesay when) orunused(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
scoresheetmessage, with the whole scoresheet. In a snapshot ofscores, 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 ascoresheetmessage: match it byeventId. GET /v1/scores/{eventId}: the latest scoresheet of one game. Withconfidence=confirmed,404while 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 withupdatedSinceset to the newestupdatedAtyou 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 playerpar_ids. - Grading, to take our verdicts instead.