Football squads API for competition rosters

The squads feed takes one required parameter, leagueId, and returns the squads the source supplies for that competition. One request gives you every club's roster in the league, which makes it far more efficient than building squad pages team by team. The cache time is about an hour, reflecting how slowly squads change outside transfer windows.

Responses arrive in the gateway envelope. The data object holds the source structure as supplied, without a normalised schema of ours, and meta records the feed, UTC fetch time, cache time and qualification. Team and player identifiers are strings, and attributes from source attributes keep their at-sign prefix. Read a sample response to find how teams and players are nested before you write a mapping.

Which details accompany each player, such as a shirt number or a position label, depends on what the source records for the competition. Treat every such attribute as optional.

A squad tells you who is registered or associated with a club for a competition. It does not tell you who will play on Saturday, who is fit, or who started last week. Products sometimes blur those lines, for example by showing the first eleven names in a squad as if they were a team. Readers who know the club will spot it immediately, and readers who do not will be misled.

Keep the concepts separate in your data model and your interface. Squad pages list the roster. Predicted line-up pages show an expected selection, clearly labelled as a prediction. Match pages show selections that the source confirms for that match. Injury information, where your plan includes it, is a separate layer again and should not be inferred from a player's absence from anything.

The Python example requests a competition's squads and records the date of each copy. Comparing successive copies by player identifier within each team tells you who joined and who left. That comparison is the basis for a transfer tracker, a squad changes page, or simply an alert to your editors that a club page needs attention.

Do not delete a player from your database because they vanished from one squad response. They may have moved to another club in the same competition, in which case they appear under a new team, or they may have left the competition entirely. Record the departure with a date and let your data keep the history.

Squads change most around transfer windows and least in the middle of a season. A sensible refresh rhythm is daily during windows and weekly otherwise, with an extra refresh before the first round of a new season. Polling hourly in October spends requests for very little benefit.

Loans complicate squad pages. A player on loan may appear in the squad of the club they are playing for, and how the source represents the parent club, if at all, varies. Do not infer a loan relationship from two appearances; show what the response contains and, if your editors know more, add it as editorial context rather than data.

Players sometimes appear in more than one competition's squad for the same club, for example a domestic league and a continental cup. Joining on the player identifier lets you show one player profile with several competition memberships rather than duplicated people.

Club sites and fan communities often want a squad page grouped by position. If the source supplies position labels, group by them and keep the labels as given; different competitions may use different conventions. If it does not, an alphabetical or shirt-number order is more honest than a position grouping you invented.

Add the date of your last refresh to the page. Squad information has a natural shelf life, and readers trust a page that tells them when it was last checked. Link each player to a profile page if your plan includes player profiles, joining on the player identifier.

Fantasy tools use squads as the player pool from which managers pick. That use raises two specific questions. First, what happens when a player leaves the competition mid-season? Your tool needs a rule, and the squad history you stored gives you the date to apply it. Second, how do you present a player whose details are thin? Show what is supplied and let the manager decide, rather than hiding the player or filling gaps with guesses.

Pair squads with predicted line-ups to help managers plan, but keep the prediction label visible. A manager who picks a player because a predicted line-up included them should understand that the prediction was not a team sheet.

A squad is a snapshot. Players join and leave in transfer windows, loans begin and end, and youth players are promoted. Refresh squads weekly in ordinary periods and daily during transfer windows, and record when each player first and last appeared. That history lets you show who left a club rather than silently removing them, which matters for archive pages that link to former players.

Being in a squad means a player is registered or listed for the competition, as the source records it. It does not mean the player is fit, in form or likely to play. Label squad lists accordingly and keep them visually distinct from predicted or confirmed line-ups.

A 400 invalid_parameter response usually means a malformed leagueId. A 403 means the competition is outside your plan's selection. If a refresh fails, keep the stored squad with its last-checked time and retry later; never empty a squad page because one request failed.

Squads is a league-addressed feed and is available on all three plans for entitled leagues. On Starter at EUR 29 a month, the leagueId must be one of your five saved leagues. Growth at EUR 99 and Pro at EUR 249 cover all available package leagues. Player and team profile services are separate global services that are not included in Starter, so a Starter squad page can list players but cannot link to profile data from those services.

Five leagues refreshed daily is five successful requests a day, which barely registers against any inclusion. Requests above the inclusion are EUR 0.002 each on the monthly EUR invoice; failed and denied requests are not billed.