The hierarchy
Every piece of data in Sportrix Data flows down from a sport through a league to a match, with live and result data attached to individual matches.Sport
The top-level category (e.g. Soccer). Your account is configured with an enabled-sports allowlist — you only ever see sports, leagues, and matches within that allowlist.
League
A competition or tournament within a sport (e.g. USA MLS Next Pro League). Every league belongs to exactly one sport and is identified by a numeric
id.Match
A single fixture between two teams within a league. Identified by a numeric
id and carries scheduling and status information.Live Snapshot / Result
Real-time or frozen point-in-time data attached to a match. A live snapshot reflects the current state; a result holds the half-time and full-time snapshots.
Sport
A sport object has two fields:| Field | Type | Description |
|---|---|---|
id | integer | Numeric sport identifier — use this as the sport parameter on /leagues |
name | string | Display name, e.g. "Soccer" |
League
A league belongs to a sport and groups a set of matches together.| Field | Type | Description |
|---|---|---|
id | integer | Numeric league identifier — use this as the league parameter on /matches |
name | string | Display name, e.g. "USA USL W-League Women" |
Match
A match represents a single fixture between two teams.| Field | Type | Description |
|---|---|---|
id | integer | Numeric match identifier — use this for /matches/{id}, /matches/{id}/live, /matches/{id}/result, and WebSocket subscriptions |
home_team | string | Home team name |
away_team | string | Away team name |
start_time | datetime | Scheduled kick-off time (ISO 8601, UTC) |
status | string | Current match status — see table below |
Match status values
| Status | Meaning |
|---|---|
NOT_STARTED | Scheduled, not yet kicked off |
STARTED | In play (including half-time) |
FINISHED | Completed |
Matches that a data provider has marked as suspended or postponed are never returned by the API — they are filtered out of every catalog response automatically.
Live snapshot
A live snapshot is attached to a match and represents its state at a particular moment. It is returned byGET /matches/{id}/live and delivered over the WebSocket stream. It contains:
score— current home and away goalsclock— current minute, second, period, whether the clock is running, and added timestats— a map of stat keys (e.g.shots_on_target,possession,corners) to per-side integersevents— a timeline of match incidents (goals, cards, corners, substitutions, etc.)ball— last event-anchored ball position as normalized x/y coordinates (0–1)phase— a decoded description of the current game state (e.g."Dangerous attack","Safe possession")
The live snapshot uses its own lowercase
status field that is separate from the catalog match status. The values are: live, ht (half-time), ft (full-time), and not_started. These differ deliberately from the uppercase NOT_STARTED / STARTED / FINISHED values on the match object.Result
A result object is returned byGET /matches/{id}/result and contains two frozen snapshots taken at key moments:
| Field | Type | Description |
|---|---|---|
half_time | object | null | Snapshot frozen at half-time (status: "ht"). Does not include events — the full timeline lives in full_time. null if not captured. |
full_time | object | null | Snapshot frozen at full-time (status: "ft"), including the complete events timeline. null if the match has not yet finished. |
Timestamps
All timestamps throughout the API — includingstart_time on matches and updated_at on live snapshots — are ISO 8601 in UTC, for example:
start_after, start_before) use the same format.