Skip to content
Tutorials/Build a football productIntermediate10 min read

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.

Flow / Different player features need different evidence
  1. Step 1: Squad

    Player identity and roster

  2. Step 2: Match teams

    Confirmed roles and formation

  3. Step 3: Player stats

    Minutes and optional match ratings

  4. 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.

All 51 tutorials