Data model
All fields are camelCase. Prices are decimal numbers, times are ISO-8601 UTC, and a field that is unknown is absent (never null). The full schemas are in the API reference.
Event (core channel)
| Field | Type | Notes |
|---|---|---|
id |
ev_… |
Stable for the life of the event |
sport |
"soccer" |
|
competition |
{id, name} |
|
home, away |
{id, name, colors?} |
colors are kit colors when known |
startsAt |
datetime | Kick-off, when known |
state |
live | finished |
Finished events stay available for 48 h |
phase |
NS 1H HT 2H PAUSED FT |
|
clock |
{seconds, running, display} |
When running, keep counting locally from the moment you received it |
score |
{home, away, ht?} |
ht = half-time score |
channels |
string[] | Channels that currently have data |
Odds
markets is an object keyed by market id: <key>.<period> plus @<line> when there is a line. Keying by id (not an array) keeps WebSocket patches tiny: a price change is just {"markets":{"match_result.ft":{"selections":{"home":1.87}}}}.
| Market id | Selections |
|---|---|
match_result.ft |
home draw away |
match_result.1h |
home draw away (1st half) |
double_chance.ft |
home_draw home_away draw_away |
both_teams_score.ft |
yes no |
[email protected] |
over under |
odd_even.ft |
odd even |
correct_score.ft |
"H-A", e.g. "2-1" (home-away) |
A market has status: open | suspended. Suspended markets keep their last prices for display and carry a suspendReason:
goal: everything suspends for ~3 minutes after a goalline_settled: the line is already decided (e.g. over 2.5 after the 3rd goal)unavailable: the source suspended it
A selection that disappears is no longer offered. A market that disappears was withdrawn.
Stats
{ home: TeamStats, away: TeamStats } with any of corners, yellowCards, redCards, shotsOnTarget, shotsOffTarget, attacks, dangerousAttacks, possession (%).
Timeline
items (newest first): {id, type: goal | corner | card.yellow | card.red, side, minute, text}. goals lists goals with the shot position when known.
Pitch
ball {x, y} in 0..1, where x = 0 is the home goal (home attacks to the right) and y = 0 is the top touchline. action {type, side} is the current play, one of dangerous_attack, attack, possession, corner, goal_kick, free_kick, dangerous_free_kick, shot_on_target, shot_off_target, throw_in, goal, yellow_card, red_card, penalty, substitution, offside, unknown.
Timeline and pitch are produced on demand. The first subscriber (or REST call) starts them; data usually arrives within a few seconds.
Players
Published after full time (typically 2–4 h after kick-off) and kept 48 h. availability: "post_match", then home and away lists (starters first) of:
id, name, firstName, shirt, starter, goals, assists, shots, shotsOnTarget, passes, tackles, foulsCommitted, foulsSuffered, xg, yellowCards, redCards, firstGoal, lastGoal.
Revisions
Every channel of every event has its own revision (rev), an integer that grows by exactly 1 on each change. REST returns it in meta.rev; WebSocket frames carry it. If you hold rev n and receive n+2, you missed one: resubscribe with since (see WebSocket).