Football scores and results API for score centres

If you could only call one football endpoint on a match day, it would probably be this one. The scores feed takes no parameters and returns scores and results for the current window across the competitions your account is entitled to. It covers matches not yet started, in progress and finished, so a single response can populate the whole of a score centre: fixtures still to come at the top of the page, games in play in the middle, full-time results below.

It sits between two narrower feeds. The live feed returns only matches the source currently reports as in play, and is cached for about fifteen seconds. Recent results returns finished matches for a chosen day in the past week and is cached for about five minutes. The scores feed, cached for about thirty seconds, is the general-purpose view in the middle, and for many products it is the only score feed they need.

Each response is a snapshot. The data object contains the source structure as supplied, and the meta object records which feed answered, when it was fetched in UTC, the cache time and the feed's qualification. We have not published a normalised schema for scores, and we do not rename source attributes. Fields that came from the source as attributes keep their at-sign prefix, and every identifier is a string.

That design has a practical consequence for your code. Write a small mapping layer that reads the attributes you need from a real response, and keep it in one place. When the source adds an attribute, your mapping keeps working and you can choose to use the new value. When an attribute you rely on is missing from a particular match, the mapping should return nothing for it rather than throwing, because missingness is normal across a wide range of competitions.

The meta timezone note applies too. fetchedAt is UTC. Match dates and times inside data are as supplied and not necessarily UTC, so do not label them as such until you have confirmed the convention for the competitions you show.

Readers look for their competition first and their team second. A score centre that lists every match in one long sequence sorted by time is hard to use on a busy Saturday. Group by competition as the source structure suggests, and order the groups in a way that makes sense for your audience: domestic leagues first for a national publisher, followed teams first for a personalised app.

Inside each group, order by supplied kick-off time and keep finished matches visible until the end of the day. Readers who arrive late want to see what they missed, and removing a result the moment it is final makes the page feel as if something broke.

The Python example polls the scores feed on a thirty-second rhythm, matching the cache, and writes the envelope to your own store only when the body changes. Your web pages read that store. Readers never call the API, the key never leaves your server, and a page with ten thousand visitors costs the same number of requests as a page with ten.

Note the slower retry after an error. A 429 response includes a Retry-After header; honour it. A 502 or 504 response means the upstream request failed or timed out, and the right reaction is a calm retry with backoff rather than a burst of parallel attempts.

A score is only meaningful alongside its match state. A two-one scoreline means one thing at half-time and another at full time, and something else again if the match was abandoned. Display the state the source supplies next to every score, and never infer one. In particular, do not treat a match as finished because its scheduled duration has passed. Stoppage time, delays and suspensions all extend matches beyond the clock.

Corrections happen. A goal can be credited and then removed, or a result amended after review. Because each request is a fresh snapshot, your page will pick up the correction on the next refresh, provided you replace stored values with new ones rather than only ever appending changes. Design notifications cautiously for the same reason: if you alert readers to a goal, be prepared for the next snapshot to disagree.

International breaks, mid-season pauses and the summer all produce days with few or no matches in the competitions you follow. A response with little in it is not an error. Your page should look deliberate when that happens: say there are no matches today in your followed competitions and point to the upcoming feed's next match day, rather than showing an empty frame with a spinner.

Equally, an unexpected empty response on a busy day is worth investigating. Check the HTTP status, the meta qualification value and your account entitlement before assuming the source has nothing. A Starter account, for instance, only sees its five saved leagues, so a match in a sixth league is correctly absent.

Scores is filtered by league on Starter. At EUR 29 a month you receive only your five saved leagues, filtered on our side before the response reaches you. Growth at EUR 99 and Pro at EUR 249 receive the available package competitions. Coverage still varies by competition and date on every plan, and the feed qualification is sample received: a response has returned, while final freshness, coverage and licensing checks are pending.

Polling every thirty seconds for a full day is 2,880 requests, comfortably inside the Starter inclusion of 5,000 successful requests per UTC day. Most products poll that often only around match windows and much less otherwise. Extra successful requests beyond the inclusion cost EUR 0.002 each on the monthly EUR invoice; failed and denied requests are not billed.

As a score centre grows, it usually adds detail pages. A reader taps a match and expects statistics, line-ups and a timeline. The scores feed is the entry point for that journey but not the destination. The match detail service on Growth and Pro returns a focused record for one match using its static identifier and league, and the competition match statistics feed returns statistics for many matches at once. Plan your data model so that the identifiers you take from scores can be used to reach those services without lookups by name.

We also run a separate scores-new service that groups matches by competition. Both are published; evaluate each against your product before deciding which to build on.