Football player profiles API for player pages

The player service takes one required parameter, playerId, a positive numeric player identifier sent as a string. Take it from squads, leaderboards, line-ups or match data. Names are especially unreliable keys for players: transliteration varies between alphabets, shirt names differ from full names, and two players in the same league can share a name. The identifier is how you know you have the right person.

Keep the identifier as a string throughout your system, and make it the key of your player table. A player who moves clubs or competitions keeps the same identifier in the source system, which is what lets a single profile page follow a career.

Responses use the standard envelope: data with the profile as supplied, meta with the feed, UTC fetch time, cache time of about an hour and qualification. We publish no normalised player schema. Identifiers are strings and source attributes keep their at-sign prefix.

Biographical depth varies enormously. A well-known international might have a full record; a young squad player in a lower division might have a name and little else. When a field such as date of birth, height or nationality is missing, it means the source did not supply it. It does not mean the value is unknown to the world, and it certainly does not mean the value is zero or empty. Leave it out of the page rather than writing unknown in a way that implies a fact.

Equally, do not treat supplied biographical values as verified beyond question. They are the source's record. If your editors find an error, raise it with support and add an editorial correction note rather than silently overwriting the data.

Player pages are often built in bulk, for example every player in a competition's squads. The example walks a list of identifiers with a pause between requests and skips profiles fetched recently. A squad of thirty players across twenty clubs is six hundred requests; spreading them over time keeps you far from the 100 requests per second account ceiling and makes failures easy to retry.

A player profile is personal information about a real person, even when the person is famous. Use it for what readers expect: who the player is, where they play and what the source records about their career. Avoid combining profile data with other sources to build speculative features about private life, and avoid sensational presentation of personal details.

Young players warrant extra care. Many squads include teenagers, and their pages should be restrained. If a player, club or representative asks you to correct or remove something, respond promptly and contact support if the underlying data seems wrong.

A good player page joins the profile to everything else you hold for the same identifier: leaderboard positions from scorers, assists and cards; squad memberships across competitions; appearances in predicted line-ups, clearly labelled; and on Growth and Pro, a portrait from the player image service where available. Each join uses the string player identifier.

Render the page on the server, include the date each component was refreshed, and give it a stable URL keyed on the identifier. Player names change spelling surprisingly often in data; a stable URL protects your links when they do.

Profiles change when players transfer, when details are corrected and occasionally when the source enriches a record. Refreshing every profile daily is wasteful. Use the updated-players service on Growth and Pro as a hint about which identifiers to refresh, and run a slow full sweep periodically to catch anything the hint missed. The hint is helpful but not a complete change log.

Before transfer deadlines, refresh profiles for players in your followed squads more often. That is when club and competition details are most likely to change.

Some profile fields change often. A squad number can change at the start of a season, a listed position can shift as a player's role evolves, and a club field can change on deadline day. Treat these as volatile and display them with the date you last refreshed the profile. Others, such as a date of birth, should rarely change; when one does, it is usually a correction worth noting.

Where the same information is available from squads for a competition, for example a squad number, prefer the competition-specific value on competition pages and the profile value on the general player page, and do not present the two as contradicting each other without explanation.

Player names travel badly between alphabets and conventions. A player may be known by a single name, by a shortened name on the shirt, or by a transliteration that differs between sources. The profile carries whatever names the source supplies. If your product serves several languages, keep supplied names as the default and store any editorial preferred spellings separately, keyed by player identifier.

Search should match all known spellings. Index supplied names and your editorial alternatives together so readers find the player whichever version they type.

Player pages draw a large share of search traffic to football sites. Pre-render them with the supplied name in the title, the current club and competition, and links to leaderboards and squads where the player appears. Avoid generating thin pages for every player in the database; a page with a name and nothing else helps nobody. Publish pages for players with meaningful supplied data or appearances in competitions you cover, and add others as their records grow.

A 404 for a player usually means the identifier is wrong or the source holds no profile; check where the identifier came from. A 403 points to entitlement, typically a Starter key or an inactive service. A 504 means the upstream request timed out; retry later with backoff rather than immediately in parallel. Log the requestId from every error body for support.

Player profiles are a global service, not included in Starter. The service requires Growth at EUR 99 a month or Pro at EUR 249 and activation for your account. A Starter key receives a 403 response with the subscription_required code, which is not billed.

A large initial build can use hundreds or thousands of requests, so plan it across a few days on Growth or run it on Pro, which includes 250,000 successful requests per UTC day. Above the inclusion, requests are EUR 0.002 each on the monthly EUR invoice; failed and denied requests are not billed. No free trial is offered.