Build formations, ratings and heatmap views
Use confirmed team positions, match-specific ratings and verified heatmap coordinates without confusing predictions, season averages or tracking coverage.
Step 1: Squad
Player identity and roster
Step 2: Match teams
Confirmed roles and formation
Step 3: Player stats
Minutes and optional match ratings
Step 4: Heatmaps
Separately verified coordinates
Put players on the pitch from supplied positions
Start with the single-match or competition statistics response. Confirmed teams can include formation, player position and formation_pos. Preserve the home/away orientation and use those supplied fields to organise each side.
Do not lay out a guessed formation from shirt numbers, list order or a generic squad roster. If a formation is missing, a readable team list is more accurate than an invented tactical diagram. Keep substitutes separate from the starting eleven.
Join minutes and substitutions by player ID
Use player_stats for supplied match minutes and explicit substitution records for on/off identity and entry minute. A player may have a portrait in your store even when they remained an unused substitute; image presence is not evidence of participation.
Do not derive precise minutes solely by subtracting an entry minute from 90 if the feed supplies a minutes-played field. Added time, dismissal and different statistical conventions can affect those values. Label supplied values honestly rather than silently reconciling them to an assumed formula.
Keep match ratings separate from season averages
Optional player_stats rating values belong to the specific match. A rating in a squad or profile collection can be a season average and must not be substituted when a match rating is absent.
Join on player ID and preserve a missing match rating as unavailable. An unrated player is not a player who scored zero. A live match with populated team statistics may still lack individual ratings until later, and no universal rating publication delay is promised.
Verify heatmap content before choosing the visualisation
The heatmap endpoint requires Growth or Pro; it is not part of Starter. Inspect the score feed's heatmap attribute and request the indicated coverage league collection. Verify actual coordinate records for the intended fixture and player. Basic score or statistics coverage alone does not establish player heatmap coverage.
Before rendering, inspect coordinate bounds, pitch orientation, weighting and any supplied time or period information. Do not advertise touches, continuous off-ball movement or half-by-half separation unless the actual payload establishes those semantics. The published route has no half or historical date query filter.
Prepare portraits and detail in the background
Save portraits by player ID and prepare the match-detail model before opening a lineup tab. Serve images with fixed display dimensions from your own stable media URLs.
Store confirmed teams, predictions, player ratings and heatmap records as distinct entities or sections. This keeps a stale prediction or empty coordinate response from overwriting a valid lineup and lets you refresh only the feature that actually changed.
Related tutorials
Endpoint tutorials / 6 min
Integrate heatmaps with verified coverage
Discover heatmap coverage flags, retrieve the correct competition collection and validate actual coordinates before building player visualisations.
Endpoint tutorials / 6 min
Display and label predicted football line-ups
Read predicted football lineup collections, check actual record dates and label forecasts separately from match-confirmed starting teams.
Build a football product / 9 min
Deliver team crests and player portraits fast
Decode supplied football images, save team crests and player portraits by ID, and serve fast public visuals without exposing customer API keys.