Data model¶
One model for every product. An event (a game or a competition) has participants and markets; a market has selections, each with a price. Scores add the scoresheet, and grading the grading (our verdicts); both hang off the event's id.
Every field is always present: null when it is unknown or does not apply. The one exception is
an event's markets, which comes only with an event fetched with its markets or sent in a
snapshot.
Event¶
A game, a match or a competition. Pre-game example, live example.
| Field | Type | What it is |
|---|---|---|
id |
string | evt_…. The same game has the same id in every product |
product |
string | The product this copy of the event belongs to |
sport |
{id, name} |
Sport, from /v1/catalog/sports |
league |
{id, name, country} |
League or competition. id is lg_…; country is ISO 3166-1 alpha-2, or null |
name |
string | Display name: "Home vs Away" for a game; the competition's name for futures |
participants |
list of Participant | The teams or competitors. Empty for futures, whose competitors are in the selections |
startAt |
time or null |
Scheduled start; null when there is none (some futures) |
status |
string | See Event status |
score |
Score or null |
The live score (live and the scores board) |
clock |
Clock or null |
The game clock (live and the scores board) |
updatedAt |
time | When the event's own fields last changed. A change of its markets does not move it |
rotation |
Rotation or null |
The game's rotation numbers. See Rotation numbers |
schedule |
Schedule or null |
The first and the current start time. See Schedule |
details |
object or null |
The race's details in horse racing; null in every other product |
markets |
list of Market | Only on an event fetched with its markets, or in a snapshot message |
Participant¶
| Field | Type | What it is |
|---|---|---|
id |
string | par_… |
name |
string | Display name |
role |
string | home or away; runner in horse racing. Other values are reserved: ignore a participant whose role you do not know |
number |
string or null |
A runner's number in horse racing; null otherwise |
details |
object or null |
A runner's details in horse racing; null otherwise |
home and away are the teams' real roles in the game, in every product.
Score and Clock¶
score is {home, away, periods}, where periods lists {period, home, away} with period ids
from /v1/catalog/periods (1h, q3, p2, set1, i7…). In set
sports, home and away count sets.
clock is {period, seconds, running}: the current period id, the seconds elapsed in it, and
whether the clock is running. Any of them is null when the sport or the game does not give it.
Event status¶
| Status | Meaning |
|---|---|
scheduled |
Not started |
live |
In play |
interrupted |
Stopped during play; it may resume |
finished |
Over |
postponed |
Moved to a later date |
cancelled |
Will not be played |
abandoned |
Stopped and will not resume |
How a game ended, for settlement, is in its scoresheet.
Market¶
Something to bet on in an event. One market holds one line: alternate lines are markets of their own.
| Field | Type | What it is |
|---|---|---|
id |
string | mkt_… |
eventId |
string | The event it belongs to |
type |
string | Market type, from /v1/catalog/market-types. Its form says how to read the selections |
name |
string | Display name, in English: "Total – 1st Half", "Patrick Mahomes Passing Yards" |
period |
string | Period id, from /v1/catalog/periods |
line |
number or null |
The market's line. See Lines |
participant |
{id, name, number} or null |
The team or player the market is about (a team total, a player prop) |
main |
boolean | false on alternate lines |
book |
{id, name} or null |
The sportsbook whose line this is; null on our own lines. See Sportsbooks |
status |
string | open, suspended or closed. See Status |
selections |
list of Selection | Its outcomes |
updatedAt |
time | When the market last changed |
legs, raceEventIds |
integer and list of strings, or null |
A pool's runners per bet and its races in horse racing; null otherwise |
Selection¶
One outcome of a market.
| Field | Type | What it is |
|---|---|---|
id |
string | sel_… |
name |
string | Display name, in English: "Boston Celtics -4.5", "Over 2.5", "Yes" |
side |
string | What the selection backs. See Sides |
participant |
{id, name, number} or null |
The team, player or competitor it backs, when it backs one |
line |
number or null |
Its own line: the handicap of its side, the total, a player's figure |
range |
{min, max} or null |
A band (player_band form): the figure must fall in it |
price |
Price or null |
null when no price is available |
status |
string | open, suspended or closed |
opening |
{line, price, at} or null |
On a book's pre-game market: the first line and price the book posted. null on our own lines, on a book's in-play market, and when the book's opening is not known |
leg, couplingGroup |
integer and string, or null |
A runner's race in a multi-race pool and its coupled entry in horse racing; null otherwise |
Sides¶
| Side | Backs |
|---|---|
home, away, draw |
That result, or that team (handicaps, team-first markets) |
home_or_draw, draw_or_away, home_or_away |
Double chance |
over, under |
The total or the player's figure against line |
yes, no |
A yes/no proposition |
odd, even |
Odd/even |
exact |
An exact figure, in line |
range |
A band, in range |
participant |
The selection's participant: a player, or a futures competitor |
other |
Read the selection's name: a correct score, a half-time/full-time pair, a margin, "No Goalscorer"… |
How each market form uses them is in the catalogs.
Price¶
{"decimal": 1.909, "american": -110}
Both figures, always together and always consistent: decimal has at most three decimals and
american is the integer it converts to. decimal includes the stake: a winning 10 at 1.909
returns 19.09.
price is null when there is no price. A selection without a price is never open.
Market and selection status¶
| Status | Meaning |
|---|---|
open |
Can be bet now |
suspended |
Cannot be bet right now. The last price is kept so you can show it, greyed out. It comes back as open when betting resumes |
closed |
Final. It will not reopen |
A suspended market is never dropped for being suspended. While the product's feed.status is
degraded, treat every open market of the product as suspended (see
Connecting).
Ids¶
Ids are opaque, stable strings: evt_…, mkt_…, sel_…, par_…, lg_…, bk_…. Store them and
join on them; never parse them.
- A game keeps its
evt_in every product:pregame,props,live,scoresandgrading, and from before the start to after the end. - A market or a selection keeps its id while it exists, whatever happens to its price, status or name.
- Our own lines are one market per line. When our line moves (a spread from
-4.5to-5), the market at the old line goes (market.remove) and a market at the new line comes (market.upsert), with newmkt_andsel_ids. A book's main market is the exception: it keeps its id while its line moves (see Sportsbooks). - A market id is unique within a product. The same game's market can carry the same
mkt_inliveand before the game: key your markets by product and id. - A selection id never names two different bets.
par_ids are per sport and name: a team'spar_is the same in all its games. A player'spar_is the same in his markets and in a scoresheet's timeline, boxscore and lineups when they spell his name the same way (some names are spelled differently: check the name too). A futures competitor has apar_of its own, which is not the one the same team has in its games.
Times¶
Every time the API sends is ISO 8601 in UTC with milliseconds: 2026-11-14T20:00:00.000Z. The
filters that take a time also accept other ISO 8601 forms with their zone, and a date alone (see
Filters).
Lines¶
Lines are numbers.
- Handicaps: the market's
lineis the home team's handicap, and each selection carries its own: home-4.5, away+4.5. A0handicap is a pick'em. - Totals: the market's
lineis the total; both selections carry it. - Quarter lines (
-0.25,2.75) split the stake in two halves on the lines either side (see Grading rules). - Player props: the market's
lineis the player's figure. - One market, one line. The main line has
main: true; each alternate line is another market of the same type and period, withmain: false.
Sportsbooks¶
Besides our own lines (book: null), pregame and live carry the lines of the sportsbooks,
such as bet365, DraftKings or Pinnacle, each market with its book:
{"book": {"id": "bk_kqlifwyx2m3ast3f", "name": "DraftKings"}}
One game carries the same type and period from many books, each its own market, next to ours.
The books whose lines your products carry now are at /v1/catalog/books.
What a book's market is
- Types: a game's moneyline (
moneyline, ormatch_resultwhen the game has a draw), its spread (spread, with the book's alternate spreads as markets withmain: false), its total (total) and each team's total (team_total, with the team asparticipant). All of them are main lines, so a book's markets are inpregamebefore the game and inliveonce it is under way, never inprops. - Periods: the whole game in every sport. The moneyline, the main spread and the total also come for the halves and quarters in basketball and American football, the halves in soccer and the periods in ice hockey; team totals and alternate spreads are for the whole game only.
- Sides:
homeandawayare the teams' roles in our event, as in our own lines; a handicap's marketlineis the home team's.
How it changes
- A book's main market keeps its id while its line moves. It is "this book's spread for this
game": its
lineand prices change in place, so its history is one market. This is the one difference from our own lines, which are one market per line. - Alternate spreads (
main: false) are markets of their own, one per line, as ours: when a book moves its alternate spread, the market at the old line goes (market.remove) and one at the new line comes. updatedAtis when the book last posted a line of the market.- Opening line.
opening, on each selection of a book's pre-game market, is the first line and price the book posted for it:{"line", "price", "at"};nullwhen it is not known. The current ones arelineandprice. - Closing line. A book's
pregamemarket isclosedwhen the game starts, with its lastlineandprice: the closing line. ItsupdatedAtis then the start. A closed market stays closed, also if the start later moves. It goes when the game leaves thepregameboard, so keep the closing line from the stream'smarket.upsertthat closes it: REST may no longer have it soon after the start. - When the books' lines are interrupted, every book's market is
suspended, with its last prices, until they come again; it then comes backopenwith amarket.upsert, as any other. Only the books' markets: our own lines and the product'sfeed.statusare not affected. - If the books' lines stop altogether for about ten minutes, the books' markets are removed
(
market.remove), and so are the games only the books list (event.remove). When the lines return, so do they, with the same ids. - Not graded. The grading add-on gives no verdict on a book's market:
it never appears in a grading's
marketsorheld, and does not count forcomplete. - A selection without a price is
suspended, as in our own lines. A market can beopenwhile some of its selections aresuspended: check each selection'sstatus. - In play,
livecarries the books' lines of the games under way, from the start until the game is over: markets of their own, with their own ids andopening: null, holding only the lines each book posted since the start. Their prices are updated every few seconds. - In play, after an interruption, a game's book markets stay
suspendeduntil a new line of that game comes: a price that may have missed a change is never reopened as it was. A game whose lines do not move stays suspended until it leaveslive.
Games only the books list are events of their own in pregame and, once under way, in
live, with the books' rotation numbers (official: true) and the same model as any other game.
They carry only the books' lines: in play no score or clock, no scoresheet in scores and no
verdicts in grading. They leave live with an event.remove when the game is over, without a
finished status.
- If the game later comes in our own lines too, it keeps its
evt_and our markets join the books'; from then on it is a game like any other. - In the rare case the two cannot be matched for sure in time (the sides listed the other way
round, for example), the first event is removed (
event.remove) and the game goes on under anotherevt_; ids are never reused. - Postponed or cancelled, such a game is removed (
event.remove): it does not come with apostponedorcancelledstatus. - A game whose competition we cannot name for sure is under its sport's generic league, such as
Soccer.
REST and the stream have no filter by book: they send every book's markets with ours. To show only
our lines, keep the markets with book: null; to show one book, keep those with its book.id; to
compare books, group by type, period, participant and main.
Rotation numbers¶
rotation is a game's rotation numbers, as sportsbooks print them on the board and on the
ticket:
{"away": 501, "home": 502, "draw": null, "official": true, "added": false}
Games with a home and an away side usually have one, in live, pregame, props and the
scores board; it is null while a game has no numbers yet, and elsewhere.
drawis the draw's number, in games with a three-way result.official: true: the official numbers the sportsbooks use.false: provisional, or ours while there are no official ones (ours run from 5 000 000 up, apart from the official ones). They may change: a provisional number gets its definitive one, and ours give way to the official ones when there are some.added: true: a game the books added outside the main schedule; its numbers are the books' own.- Numbers are not ids. They are reused across days, and a game keeps its
evt_when its numbers change. Join onevt_; show the numbers. - A game's periods and props share its numbers: the market says the period.
Schedule¶
schedule is {originalStartAt, startAt, timeConfirmed} in live, pregame, props,
futures and the scores board:
originalStartAt: the first start time we published for the game. It never changes.startAt: the current one, the same as the event'sstartAt.timeConfirmed:falsewhile the hour is still to be announced (the date is known);nullwhen it is not known.
A start that moves, and a postponement (status: postponed), comes as an event.upsert. What a
changed start means for bets already taken is your rule to apply. A start that moves, and the official
rotation numbers, can take up to 10 minutes to show.
One game, everything about it¶
Everything about a game hangs off its evt_:
- the whole game, halves, quarters, periods, innings and sets are markets of the same event,
told apart by
period; - team markets and player props are markets of the same event; the team or player is the
market's
participant; - before the start, its main lines are in
pregameand the rest inprops; in play, everything is inlive; afterwards its scoresheet is inscoresand our verdicts ingrading.
GET /v1/events/{eventId} (example) answers, for the products of
your key:
| Field | What it is |
|---|---|
event |
The event, without markets, from the product where it is most current. null once the game has left every board and only its scoresheet or verdicts are kept |
products |
One entry per product that offers the game now: {product, status, markets, updatedAt, href}, where markets is how many it has there and href the event with its markets |
scoresheet |
The link to its scoresheet, once there is one and your key includes scores; otherwise null |
grading |
One {product, href} per product of lines your key includes that has verdicts on the game, when your key includes grading |
result |
The link to the race's result in horse racing, once there is one; null otherwise |
The links are paths: prefix them with https://api.lineval.com.
Every market type belongs to a group, for building tabs: game, team, stats, player
and futures (Market groups). To fetch one tab, add groups to the
event call or to the stream, for example ?groups=player.
Scoresheet and Grading¶
The scoresheet (how a game ended: score, periods, statistics, timeline, boxscore, lineups, and how sure we are) is described in Scores. The grading (our verdict on each selection) is described in Grading.