Updated football team IDs API for targeted refreshes

The updated teams feed takes no parameters and returns team identifiers that the source reports as recently updated. It 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. Identifiers are strings; keep them that way so they match the team identifiers you already store.

What counts as an update, and over what period the list looks back, is defined by the source and has not been certified by us. Read several samples over a few days to get a feel for how many identifiers appear and how often the list changes before you design around it.

The most important property of this feed is what it does not promise. It is not a complete change log. A team whose profile changed may not appear, the list may not say what changed, and an identifier may appear without any visible difference in the profile. It is also not a push notification or webhook; nothing is sent to you. You poll it like any other feed.

Used as a hint, it is very valuable. Most of the time it points you at the profiles that actually need refreshing, and lets you skip the hundreds that do not. Used as a guarantee, it will eventually let a stale profile sit on your site for weeks. Design for the first use.

The example polls the feed, keeps only identifiers for teams you actually hold, and refreshes each of those profiles with a pause between requests. Identifiers for teams you do not cover are ignored; there is no need to fetch profiles you will never show.

Because the list is not complete, combine it with a slow sweep that refreshes every profile you hold over a longer cycle. A common pattern is to refresh one seventh of your teams each day, so the whole set is refreshed weekly, alongside the hint-driven refreshes. The sweep catches changes the hint missed; the hint catches changes faster than the sweep would.

Spread the sweep evenly through the day rather than running it in one burst. It keeps your request rate smooth and well below the 100 requests per second account ceiling, and it means a transient upstream problem affects a small slice rather than the whole run.

If your product cares about what changed, compare the newly fetched profile with your stored copy. A simple structural diff of the data object will show added, removed and modified attributes. Record the differences with timestamps. That history is useful for editors and for spotting source corrections that might affect other pages, such as a renamed club whose name appears in archived match reports.

Do not assume that every listed team will show a difference. Sometimes nothing visible changes in the attributes you store. That is normal and not an error.

A team identifier appearing in the list can also be a cue to refresh related data you hold for that team, such as its crest from the team image service. Crest changes are infrequent but visible, and a club that has updated its badge will notice an outdated one on your site.

Be judicious. Refreshing every related service for every listed team multiplies requests. Choose the few that matter for your product.

The feed is cached for about an hour, so hourly polling is the natural upper bound on ordinary days. Many products poll less often, perhaps every few hours, because team profiles rarely change urgently. Around the start of a season and during transfer windows, clubs update details more often, and hourly polling is worthwhile. On quiet days in mid-season, three or four polls a day are usually enough.

Whatever cadence you choose, record the time of each poll and the identifiers it returned. That log lets you measure how often listed teams actually changed, which tells you how much to rely on the hint for your competitions.

The list may include teams from competitions you do not cover. Ignore them unless you have a reason to add those teams. Requesting profiles for every listed team regardless of relevance would waste requests and fill your database with clubs you never show. Intersect the list with your own set of team identifiers before doing anything else.

Conversely, a team you hold that never appears in the list is not necessarily unchanged. That is what the safety-net sweep is for.

Refresh jobs fail part-way through for ordinary reasons: a timeout, a deploy, a transient upstream error. Design the job so it can be re-run safely. Store a refreshed-at time per team, skip teams refreshed since the list was fetched, and process identifiers in a stable order. A job built this way can be interrupted and restarted without double-counting requests or leaving some teams permanently behind.

A 403 response with the subscription_required code during a refresh usually means the team profile service is not activated for your account, even though the update feed is. Both need activation. A 404 for a listed team can mean the source no longer holds a profile for that identifier; record it and stop refreshing that team until it reappears. Keep every requestId from error bodies in your logs so support can trace specific calls.

The feed does not record what changed. When a refresh alters a stored profile, write the old and new values with a timestamp to your own history table. That history answers editorial questions, supports corrections and shows how reliable the hint is for your competitions over time.

Test that only teams you hold are refreshed and that restarts skip teams refreshed recently.

Updated teams is a global service that is not included in Starter. It requires Growth at EUR 99 a month or Pro at EUR 249 and activation for your account. Because the profiles it helps you refresh are also Growth and Pro services, the two are typically used together.

Polling the list hourly is 24 successful requests a day, plus the profile refreshes it triggers. Requests above the daily inclusion cost EUR 0.002 each on the monthly EUR invoice; failed and denied requests are not billed. No free trial is offered.