Match statistics and line-ups

A match record usually contains both teams with identifiers, the final score, a list of events with minutes and player identifiers, starting line-ups, substitutes, and a statistics block for each team. Some competitions add individual player statistics such as minutes, shots and passes. Formations may be supplied as a string.

Event types include goals, own goals, penalties, cards and substitutions. Each event should carry the minute and, where applicable, added time. Render added time explicitly, since 90+3 and 93 mean the same in some systems and different things in others.

Keep the event list in the supplied order and use it as the basis for a timeline. Re-ordering by minute alone can scramble events that happened in the same minute.

Because the family is retrieved per competition, your job is to match each record to the fixture you already hold. Do it by match identifier. If you stored season fixtures keyed on that identifier, the join is a simple lookup and the match page can show fixture metadata and detail together.

If a match detail record arrives without a fixture you recognise, store it anyway and flag it. It may be a rescheduled match, a cup tie or a competition you do not yet track.

Line-ups are most readable as two columns or as a pitch diagram. A pitch diagram needs formation and position data, which is not always present, so build the column view first and add the diagram only when the data supports it. Mark the captain and goalkeeper where supplied, and show substitutes beneath with the minute they came on.

Link each player to their profile by identifier. Readers often move from a match page to a player page after a standout performance, and those links are where much of a football site's internal navigation happens.

Team statistics such as shots, shots on target, corners, fouls and possession give useful context. Present them side by side with clear labels and no editorial colouring. Avoid derived metrics unless you can explain how they were calculated and from what.

When a statistic is missing for one team, hide the row rather than showing a dash for one side and a number for the other, which invites readers to compare unlike things.

Detail often arrives after the final score. Line-ups may appear before kick-off, events during or after the match, and statistics later still. Design the match page to show whatever stage is available, with a note when more detail is expected.

Refresh the per-competition feed a few hours after the last match of the day, and again the next morning to pick up corrections. Store each version, or at least the latest good version, so that a temporarily empty response does not erase a page.

Some competitions also offer predicted line-ups before kick-off. These are forecasts of team selection, not betting predictions, and they should be labelled clearly as expected rather than confirmed. Replace them with the confirmed line-up once it arrives, and never mix the two on one page without labels.

Our separate guide on predicted line-ups covers how to present them responsibly.

Combine the fixture, the line-ups, the event timeline and the statistics into one page and you have a match centre. Cache the assembled data on your server, refresh it on a schedule, and show the refresh time. Remember that FootballAPI.net presents nothing as live, so describe the page as a match report rather than a live tracker.

Our match centre guide walks through the page structure in more detail, including empty and error states for each panel.

After the final match on a Saturday in league 1204, a job requests the competition's match detail, iterates through the records, and looks up each match identifier in the fixtures table. Matching records update the match page; unmatched ones go to a review queue. Line-up players are linked to profiles by identifier, and events are stored in supplied order with their minute and added time.

On Sunday morning the job runs again. Any corrections, such as a goal reassigned from one scorer to another, overwrite the earlier record for that match, and the page shows the updated timeline with a refreshed-at time. Because the job keeps the previous version until the new one validates, a failed request leaves Saturday's page intact.

Over a season, this simple two-pass pattern keeps match pages accurate with a modest number of requests, and the review queue surfaces cup ties or rescheduled games that need attention.

Event timelines should be readable as text, not only as icons. Give each event an accessible label such as goal, 34th minute, followed by the player's name. Make statistic bars accessible by including the numbers as text, and ensure line-up columns are announced with team names as headings.