Skip to main content
SportriX organizes all sports content into a three-level hierarchy: sports contain leagues, leagues contain matches, and each match can carry a live snapshot or a final result. Understanding this structure helps you navigate the API efficiently and know which endpoint to call at each stage of a match’s lifecycle.

​
The hierarchy

Every piece of data in SportriX 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: Your account has an enabled-sports allowlist. Requests for sports, leagues, or matches outside that allowlist return empty results rather than an error — see Scopes and Permissions for details.

​
League

A league belongs to a sport and groups a set of matches together.

​
TeamTeam

A team belongs to a league. Use GET /teams to list the teams in a league along with their kit thumbnailteam belongs to a league. Use GET /teams to list the teams in a league along with their kit thumbnails.
Team id values are opaque strings — treat them as such. They are stable and safe to store or compare for equality, but do not try to parse, decode, or sort by them.
Team names also appear directly on match objects as home_team and away_team strings — you do not need to call /teams to render a match. Use /teams when you need the team id, silk image, or the full team roster for a league.

​
Match

A match represents a single fixture between two teams.

​
Match status values

CLOSE_OF_PLAY counts as live/ongoing alongside STARTED. The “active” endpoints (/leagues/active, /matches/active) and the per-sport /matches/live feed all include matches in this state, and you can pass status=CLOSE_OF_PLAY to filter /matches.
Team id values are opaque strings — treat them as such. They are stable and safe to store or compare for equality, but do not try to parse, decode, or sort by them.
Team names also appear directly on match objects as home_team and away_team strings — you do not need to call /teams to render a match. Use /teams when you need the team id, silk image, or the full team roster for a league.

​
Match

A match represents a single fixture between two teams.

​
Match status values

CLOSE_OF_PLAY counts as live/ongoing alongside STARTED. The “active” endpoints (/leagues/active, /matches/active) and the per-sport /matches/live feed all include matches in this state, and you can pass status=CLOSE_OF_PLAY to filter /matches.
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 by GET /matches/{id}/live and delivered over the WebSocket stream. It contains:
  • score — current home and away goals
  • clock — current minute, second, period, whether the clock is running, and added time
  • stats — a map of stat keys (e.g. shots_on_target, possession, corners) to per-side integers
  • events — 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 by GET /matches/{id}/result and contains two frozen snapshots taken at key moments: Each snapshot inside the result is a live snapshot object in the same format described above.

​
Timestamps

All timestamps throughout the API — including start_time on matches and updated_at on live snapshots — are ISO 8601 in UTC, for example:
Query parameters that accept a datetime (start_after, start_before) use the same format.