/v1/leagues. /games and
/matches share the schedule handler; /matches/{id} and /games/{id} share
fixture detail. Soccer-specific composites live under /matches/{id} and
require stats access.
Match detail
These routes have distinct schemas. Match commentary is provider text; momentum
is a provider series, not a universal forecast. Missing fields depend on source
coverage and match state. Missing live detail can coexist with a valid scheduled
match.
Lineup confidence
lineup-card reports lineup_source separately for home and away. A side has
either confirmed players or an estimated block. Soccer has no projected
rung in this cascade. Estimates use recent appearances, squad membership,
position/formation evidence, and absence reports; they must be labeled as
estimates. Doubtful players differ from players ruled out.
Use /lineup or /lineup-detail for stored provider detail and /lineup-card
for the confirmation/estimate workflow. Do not combine an estimate with a
confirmed eleven without retaining their source markers.
Competitions and identity
Soccer identity can span multiple competitions. A player’s squad history is
different from season statistics or national-team call-ups. Roster responses
can include
_meta.availability describing the coverage behind an empty list.
Computed soccer analytics
| Route | Parameters and meaning | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---- | --------------------------------------------------------- | |/leaders | measure, optional season, limit (default 20, 1–50). Counting-stat leaderboard over completed matches in the resolved competition. |
| /teams/{id}/season-stats | season, segment=all | home | away; record, goals, points, per-game and scoring rates. |
| /teams/{id}/form | segment, limit; recent completed matches and freshness context. |
| /head-to-head | teamA, teamB, limit; canonical meeting history. Distinct from fixture /h2h. |
| /players/{id}/match-log | measures CSV, segment, limit; per-match player series and context. |
These use the league’s resolved default competition. A supplied season can
steer competition selection on the season-based readers; it is not a generic
filter for every form/history endpoint. Stage scope excludes irrelevant
qualifying/play-off/all-star fixtures according to competition rules and uses
regular-season matches for league aggregates.
If a competition or measure cannot be resolved, the API can return
200 with data.available=false and a reason. Invalid segment or bounded
limit values return 422 invalid_query_parameter. Check found and
context.asOf, sampleSize, scopeApplied, and staleness before comparing
aggregates. Fields in these analytics retain camelCase, such as competitionId
and teamId; the reference preserves their exact spelling.