Expectations, not team sheets
A predicted line-up is an expectation of which players will start, published before a club announces its team. It is useful because the real team sheet usually appears only shortly before kick-off, while readers start planning much earlier: fantasy managers choosing a captain, fans discussing selection, journalists writing previews. The feed meets that need by supplying expected selections for matches in a competition.
What it is not matters as much. It is not the confirmed starting eleven, and it can be wrong. Managers rotate, players pick up knocks in the warm-up, and tactical surprises happen. It is also not a prediction about the result. FootballAPI.net is a data provider rather than a bookmaker, and an expected line-up says nothing about who will win.
One request per competition
The feed takes one required parameter, leagueId, a positive numeric competition identifier sent as a string. A single request returns predictions for the competition as supplied, which means one call can serve every preview page in a round. The cache time is about five minutes.
Responses come in the standard gateway envelope. The data object holds the source structure without a normalised schema of ours; meta records the feed, UTC fetch time, cache time and qualification. Team and player identifiers are strings, and source attributes keep their at-sign prefix. Which matches have predictions, how far ahead they appear and what detail accompanies each player vary by competition, so treat their presence as a bonus rather than a guarantee.
const url = "https://footballapi.net/api/v1/football/predicted-lineups?leagueId=1204";
const res = await fetch(url, { headers: { "X-API-Key": process.env.FOOTBALLAPI_KEY } });
const body = await res.json();
if (!res.ok) throw new Error(`${body.code} ${body.requestId}`);
// select each match by its string identifier using your mapping,
// and store with body.meta.fetchedAt so pages can show when it was checked
await savePredictions("1204", body);Labelling that readers cannot miss
The single most important design decision for this feed is the label. Use words such as predicted line-up or expected eleven in the heading, not just in small print. Give the section a visual treatment distinct from confirmed selections, perhaps outlined player markers instead of filled ones, so the difference is obvious at a glance even to someone who skims.
Add the time your server last checked the prediction. A prediction from two days before kick-off and one from two hours before are different things, and readers deserve to know which they are looking at.
- Put the word predicted in the section heading.
- Use a visual style distinct from confirmed selections.
- Show when the prediction was last checked.
- Never mix predicted and confirmed players in one list.
Refreshing around team news
Predictions move as information arrives: a press conference two days out, a training-ground update, injury news on the morning of the match. A practical rhythm is a refresh a couple of times a day in the days before a round, then more often on match day itself, stopping at kick-off. Polling faster than the five-minute cache returns the same body and still counts as a successful request.
Track changes between refreshes. A player dropping out of a prediction the morning of a match is news to a fantasy manager. If your product sends alerts for that kind of change, phrase them carefully: a player has dropped out of the predicted line-up, not a player has been dropped.
Handing over to the confirmed selection
Once the source supplies the actual selection for a match, the prediction has done its job. Replace it on your match page rather than showing both side by side, which invites confusion about which is real. If you want to keep the prediction for analysis, store it, but do not display it as current.
Some products like to show how accurate predictions were. If you do that, compare against the selection the source supplies for the match, and present the comparison as your own analysis. Avoid presenting it as a reliability score for the feed, because accuracy varies by competition and by how late team news broke.
Keeping predictions away from betting language
Predicted line-ups sometimes end up on sites that also discuss betting. If yours is one of them, keep a clear boundary. Do not describe expected line-ups as tips, edges or insider information, and do not tie them to prices. Our acceptable use terms and our guide comparing predicted line-ups with betting predictions explain the distinction in more detail.
This is not just caution on our part. Readers who act on a prediction believing it to be confirmed can lose out, and any product that blurs that line takes on responsibility for the confusion.
Pairing with squads and injuries
A preview page is richer when the prediction sits beside the full squad and, on Growth and Pro, supplied injury information. The squad shows who else is available. The injury feed shows who the source reports as unavailable. Together they help readers understand the prediction without you inventing any reasoning for it.
Join all three on player identifiers, never names, and keep each layer visually and textually distinct. If a player appears in the prediction and also in the injury feed, show both facts and let the reader see the tension, rather than silently removing the player from one list.
Timing predictions against team news
Predictions are most useful in the day or two before kick-off and least useful in the hour before, when clubs publish official team sheets. Design your page to change mode at that point: before team news, show the prediction labelled as predicted with its refresh time; once you have confirmed line-ups from an official source, replace or clearly separate the prediction. Leaving a prediction on the page after the official team is known, without labelling, confuses readers.
Refresh predictions a few times on the day before a match and again on matchday morning. More often rarely changes anything.
Joining predictions to squads
Join predicted players to your stored squads by player identifier, not by name. A predicted player missing from your squad table may be a new signing or a youth call-up; keep the row with its supplied name and queue the identifier for review instead of dropping it.
Errors and stale predictions
If a refresh fails, keep the last stored prediction with its refresh time visible, and never upgrade it to confirmed. Retry with backoff after 502 or 504 responses, wait for Retry-After on 429, and log every requestId so support can trace failures.
Plan scope
Predicted line-ups is league addressed and available on all three plans for entitled leagues. Starter at EUR 29 a month is limited to your five saved leagues. Growth at EUR 99 and Pro at EUR 249 cover all available package leagues. The injuries feed, which pairs naturally with predictions, is a global service not included in Starter.
A busy match week with ten refreshes a day for five leagues is fifty successful requests a day. Requests above the daily inclusion are EUR 0.002 each on the monthly EUR invoice; failed and denied requests are not billed.
Questions developers ask
- Is a predicted line-up the official team sheet?
- No. It is an expectation published before the team is announced and it can be wrong.
- Is this a betting prediction?
- No. It describes expected starting players only and says nothing about the result.
- What parameter is required?
- leagueId, a positive numeric competition identifier sent as a string.
- How often should I refresh predictions?
- A couple of times a day before a round and more often on match day, no faster than the five-minute cache.
- What should happen once the real line-up is known?
- Replace the prediction with the selection the source supplies. Do not display both as current.
- Is the feed on Starter?
- Yes, for your five saved leagues.
Guides and documentation
Check the plan before you write the integration.
Starter EUR 29, Growth EUR 99, Pro EUR 249 per month. No free trial. No VAT currently charged.