Preparing player pages from a known roster
A lineup screen or squad page often needs several player biographies at once. The players operation lets your server request up to fifty known player IDs together instead of opening a separate profile request for every person. It is designed for controlled enrichment of identifiers discovered from football data, not for guessing numbers until you have scraped a global directory. Decide which competitions and players your product covers, retain their IDs and prepare the required profiles in the background. That keeps match-day rendering separate from a potentially large import and allows a reader to open a player page using an already saved record.
The playerIds parameter and authentication
Use GET /api/v1/football/players with playerIds containing one to fifty comma-separated positive numeric identifiers. Spaces, underscore prefixes, path fragments and arbitrary URLs are not accepted. Store the IDs as strings and deduplicate your import queue before splitting it into batches. Growth or Pro and service activation are required, independently of whether a player appears in a Starter league. The X-API-Key header belongs on your server-side request. A successful response follows the standard data and meta envelope; malformed or unauthorized requests should be handled as explicit failures rather than converted into an empty list of apparently valid biographies.
curl --fail-with-body --get 'https://footballapi.net/api/v1/football/players' -H "X-API-Key: $FOOTBALLAPI_KEY" --data-urlencode 'playerIds=138653,193'Player identity survives name and club changes
Join each returned profile by its own player identifier, never by response order. A batch can omit unavailable records, and the output should not be assumed to reproduce the input sequence. Names are especially unsafe keys because of transliteration, accents, shortened shirt names and players with identical surnames. Club membership can also change during a career without changing the person's identity. Keep your own editorial player identifier separate if your application needs one, and maintain an explicit mapping to the source ID. The same mapping then joins portraits, squad appearances, lineup records, match ratings and transfer history without relying on text matching at render time.
Rendering biography fields without inventing facts
A supplied profile may contain nationality, birth information, position and other biographical attributes, but depth varies considerably. An absent height is not zero centimetres, and a missing date is not the current day. Hide a field or mark it unavailable instead of presenting a fabricated default as a fact. Treat position labels as source context rather than a full tactical description: an attacking midfielder's profile position need not match the exact formation slot used in a particular match. If an editor adds a correction, preserve its provenance separately from the original response so future imports do not silently overwrite the distinction between supplied and editorial data.
Season, competition and career statistics
Player profiles can include domestic, cup, international and career statistical sections. Preserve their competition and season dimensions, along with appearances, minutes, goals, assists, cards and any other supplied metrics. Combining all sections into a single total can double-count overlapping summaries or mix competitions with different reporting coverage. A career aggregate may not be directly comparable with the sum of every season row you currently hold. Keep the original values and label any derived total as your calculation. When a record contains several club spells in one season, retain those relationships rather than assuming that the latest club owns every historical appearance.
Aggregate ratings are not the current match score
Ratings in season or competition profile statistics are aggregates tied to that context. They must not replace a missing rating in an active match panel. Live match performance is supplied under each team's player_stats.player in covered statistics responses, with the player's @id and optional @rating. Model profile averages and match ratings as separate values with separate timestamps and keys. Do not interpret either as a win probability or betting confidence, and do not impose an undocumented scale. If your application calculates its own fantasy score, distinguish that calculation from both the supplied profile aggregate and the supplied individual match rating.
Transfers, honours and sidelined records
Where available, the profile can contain transfers, trophies and sidelined history. Use the supplied dates and descriptions without turning an absent end date into confirmation that an injury is ongoing. A transfer entry records a reported movement; it is not a substitute for current competition squad membership. Trophy lists also need their original competition and season context so an application does not confuse a team honour with an individual award. These sections are useful for a richer player page, but they should not block the basic identity screen when unavailable. Design each section to stand independently rather than requiring every biography to match the richest profile in your first sample.
Matching portraits and preparing media in advance
Portrait delivery uses player ID, so save that association when preparing the profile. A profile image reference is not permission to embed a customer API key in a public image URL. Follow the authenticated media route and applicable rights, validate the returned image payload and retain a safe cached copy where your licence permits it. If no portrait exists, use a neutral player silhouette rather than borrowing another person's image. Preparing portraits alongside the selected roster avoids forcing every lineup viewer to wait on a chain of new image-source requests. Keep failures retriable without replacing a valid saved portrait with an error document.
Refreshing profiles while preserving completed imports
The batch player-profile gateway cache is one hour. The updated-players endpoint can supply changed-ID hints, optionally scoped by date, but it should not be treated as an exhaustive transaction log or webhook. Refresh relevant profiles on a controlled schedule, record successful retrieval per player and preserve your import cursor between worker restarts. When a batch partially succeeds, save the identified profiles and retry the unresolved subset separately. Bound concurrency and honor retry guidance instead of sending the same fifty-player query repeatedly from several browser sessions. Store stable career data independently from short-lived match polling so one background task does not determine the freshness of every screen.
Testing a player-profile integration before release
Test a one-player batch, an input near the fifty-ID boundary, reordered output and a requested ID that is absent from the response. Include a transferred player, a missing portrait, a biography with sparse fields and a profile with several competition statistics sections. Check that opening a profile from either team's lineup resolves to the same identity and never changes the currently selected match. Your own pages should read a prepared server-side record while refresh work proceeds independently. Consult the profile and statistics guides together: the profile explains who the player is and their broader history, while the match record explains the supplied performance in a specific game.
Questions developers ask
- What is the maximum player batch size?
- Fifty positive player IDs per request. Deduplicate and split larger imports into explicit batches.
- Can a profile be missing from a successful batch?
- Yes. Match returned IDs individually and track unresolved requested IDs without shifting array positions.
- Can profile ratings populate today's match panel?
- Not as a replacement for missing match ratings. Profile statistics describe their own season or competition context.
- Do transferred players require a new portrait key?
- Keep the supplied player ID as the association; do not use the club or shirt number as the portrait key.
- How often should player profiles refresh?
- The gateway cache is one hour. Use background refreshes and changed-ID hints rather than per-visitor imports.
Guides and documentation
Check the plan before you write the integration.
Starter £29, Growth £99, Pro £249 per month. Starter only: 7 days free, once per account, card required. Then £29/month unless cancelled. No VAT currently charged. Existing EUR subscriptions are unchanged.