Matches
A match is the central object in the API. Everything else hangs off of it.
Lifecycle
Every transition shows up as a change in status_code (and, often, period).
Match list vs. match detail
The API returns two shapes depending on the endpoint:
Match— compact view returned by list endpoints. Optimised for live scoreboards: ID, teams, score, status, kickoff, minute.MatchDetail— full record. Adds half-time scores, formations, referee, venue, attendance, finished-at timestamp.
See the API Reference for the authoritative schema of each.
Live indicators
When status_code is 2 (live), three fields tell you "where" the match is.
Football
| Field | Meaning |
|---|---|
period | 12 = 1st half, 13 = 2nd half, 38 = half-time. |
minute | Wall-clock minute (0–45 in H1; 45–90 in H2). |
added_time | Stoppage minutes added (e.g. 45+2 → added_time: 2). |
Basketball
| Field | Meaning |
|---|---|
period | 22–25 = Q1–Q4, 26–27 = OT1–OT2. |
game_clock_secs | Clock minutes remaining in the current period. -1 when the clock is stopped (timeout, free throw). |
The clock is stored at minute resolution and interpolated to seconds
server-side using updated_at — exactly the way real-time scoreboards do it
in the browser. See Timestamps.
Enrichment endpoints
| Endpoint | What it returns |
|---|---|
/matches/{id}/events | Goals, cards, substitutions — chronological. |
/matches/{id}/stats | In-game statistics (sport-aware). |
/matches/{id}/lineups | Starting XI + bench, with formation. |
/matches/{id}/standings | League table snapshot at this match. |
/matches/{id}/h2h | Recent meetings between the two teams. |
All five are populated while the match is in play and continue to be served forever after.
Statistics shape
The stats endpoint returns a JSON pass-through whose entries have this
shape:
{
"section": "Match", // or "1st Half", "2nd Half", "Q1"…
"name": "Ball Possession",
"home": "58%",
"away": "42%"
}
Common stat names per sport:
Football
- Ball Possession
- Expected Goals (xG)
- Total Shots / Shots on Target / Off Target / Blocked
- Corner Kicks
- Free Kicks
- Offsides
- Fouls
- Yellow / Red Cards
- Goalkeeper Saves
- Total Passes / Passes Completed
- Tackles
Basketball
- Field Goals attempts / made / %
- 2-Point / 3-Point splits
- Free Throws attempts / made / %
- Total Rebounds (offensive / defensive)
- Assists
- Steals
- Blocks
- Turnovers
- Personal Fouls
The exact set varies by competition and how far the match has progressed. Treat the response as a list and render whatever is present.
Identifiers
Match IDs (like abc123XY) are stable — they never change once issued.
Use them as foreign keys with confidence.