Updated football player IDs API for profile maintenance

A product covering a few top divisions can easily hold several thousand players. Re-requesting every profile daily would cost thousands of requests and mostly return unchanged data. Refreshing too rarely leaves transferred players at their old clubs on your pages. The updated players feed exists to resolve that tension: it tells you which player identifiers the source has recently updated, so you can spend requests where change is likely.

The feed takes no parameters and is cached for about an hour. Responses use the standard envelope, with data holding the source structure and meta recording the feed, UTC fetch time, cache time and qualification. Player identifiers are strings; keep them that way so they match the identifiers you store from squads and leaderboards.

Two limits shape how you use this feed. First, it is polled, not pushed. There is no webhook delivery; nothing arrives unless you ask. Second, it is not a guaranteed complete change log. A player whose record changed may not appear, the list does not reliably explain what changed, and the period it covers is defined by the source rather than certified by us.

Within those limits it is genuinely useful, because it is usually right about where change has happened. Treat it as a way to reorder your refresh work, not as permission to stop refreshing everything else.

The cleanest design is a refresh queue with priorities. Every player you hold sits in the queue with a next-refresh time, so the background sweep is simply the queue draining at a steady pace. When the update feed lists a player you hold, you move that player to the front. A worker takes players from the front at a controlled rate and requests their profiles.

This design has useful properties. Your request rate is constant and predictable, which keeps you far below the 100 requests per second account ceiling. Bursts in the update list do not create bursts in your traffic; they just reorder the queue. And no player can be forgotten, because everyone eventually reaches the front.

Deadline days concentrate change into hours. Poll the update feed more often then, perhaps every half hour, matching no faster than the hourly cache would justify on ordinary days but accepting some repeated bodies for responsiveness. Raise your worker's rate for the day if your plan's inclusion allows, and refresh squads for the competitions you follow, since a player moving clubs usually appears in a new squad as well as an updated profile.

Be careful with announcements. A profile showing a new club is the source's record, and it may lag or lead official confirmation. If your product publishes transfer news, rely on official confirmation for the headline and use the data to update pages.

When a player moves club, their portrait may change to show the new kit. If you use the player image service on Growth and Pro, consider refreshing the portrait for listed players too, at a lower priority than the profile. The portrait lookup returns a JSON record with an image payload rather than a ready-made picture, so decode, validate and cache the resulting image separately with its own expiry.

As with profiles, do not refresh every portrait on every listing; choose the players whose pages are most visited.

Each time a refresh changes a stored profile, record the difference and the time. Over a season, that audit trail tells you how often listed players actually changed, how often unlisted players changed during the sweep, and therefore how much you can rely on the hint for your competitions. It also gives your editors a clear history when a reader asks why a page said something different last week.

Store differences in your own system; the feed itself does not provide history.

A source covering many competitions will list players you never display. Intersect the list with the players you actually hold before queuing anything. If you hold players from squads of five leagues, there is no value in refreshing a profile for a player in a sixth. Keep the intersection step explicit in your code so it is obvious to anyone reading it why some listed identifiers are ignored.

Equally, if your product adds a competition mid-season, run an initial profile build for its players before relying on the update list for them.

After a few weeks, your audit trail tells you how useful the hint is for your competitions. Compare the share of listed players whose profiles actually changed with the share of unlisted players whose profiles changed during the background sweep. If the hint catches most real changes, you can lengthen the sweep cycle and save requests. If it misses many, shorten the sweep. The right balance depends on your competitions and how much staleness your readers will tolerate.

Queue workers fail and restart. Make each profile refresh idempotent: fetching a profile twice should leave your database in the same state as fetching it once. Record a refreshed-at time per player and skip players refreshed recently when the queue is rebuilt. This prevents a restart from re-fetching hundreds of profiles and keeps your request count predictable.

A 404 for a listed player can mean the source no longer holds a profile for that identifier; record it and stop refreshing until the player reappears in a squad or in the update list. A 403 usually means the player profile service is not activated even though the update feed is; both need activation. Keep requestIds from error bodies in your logs so support can trace individual calls if you need help.

Simulate a listed burst of several hundred identifiers in tests and confirm the worker's request rate stays constant, that only players you hold are queued and that a restart does not re-fetch recently refreshed profiles.

Updated players is a global service that is not included in Starter. It requires Growth at EUR 99 a month or Pro at EUR 249, with activation for your account. Player profiles and images, which it helps you maintain, are also Growth and Pro services.

Hourly polling is 24 successful requests a day. The profile refreshes it triggers depend on your player base; Growth includes 25,000 successful requests per UTC day and Pro 250,000. Above the inclusion, requests are EUR 0.002 each on the monthly EUR invoice, and failed or denied requests are not billed. No free trial is offered, and no VAT is currently charged.