Football top scorers API for competition leaderboards

You could, in principle, build a top scorers list by counting goal events across every match in a season. In practice that is expensive, fragile and often wrong. Own goals, goals later credited to a different player and matches with incomplete event data all distort a home-made count. A competition leaderboard published by the source has already been through those decisions.

The scorers feed gives you that leaderboard for one competition at a time. Two sibling feeds, assists and cards, follow the same pattern for creators and discipline. Together they cover the three races readers follow most often.

All are marked sample received in the public catalogue, which means a response has returned and final freshness, coverage and licensing qualification is pending. Each league feed has a cache time of around fifteen minutes.

Suppose an editor wants a compact top-ten strip on a league homepage. The request is a single call per league. The component then takes the first rows in the order supplied, shows the player name and club name as display text, and keeps the player identifier as a hidden string key for links and for deduplication.

Notice what the widget does not do: it does not re-sort the list. The order the source supplies already reflects whatever tie-break the competition uses. If you sort by goals yourself, you will reshuffle tied players in a way that may contradict the official standing of the race.

Scoring races are often level. Some competitions separate tied players by fewer minutes played, some by fewer penalties, some by assists, and some simply share the place. If the source supplies a rank or position attribute, display it. If it supplies only counts, show tied players as tied rather than inventing a tie-break.

Penalty goals are worth surfacing where the source records them, since readers care about the difference, but present them as the source does. Do not derive a non-penalty figure unless both numbers come from the same response.

A striker who moves clubs in January keeps their goals in the competition leaderboard but changes the club shown next to their name. Joining on the player identifier, stored as a string, is what keeps your history straight. If you key on the player name and club together, the January move creates a second row for the same person and splits their tally in two.

Transfers between competitions are different: goals scored in one league do not move to the other league's leaderboard. A cross-competition total is something you build yourself by summing per-competition rows on the player identifier, and you should label it as your own aggregate.

Leaderboards move only when goals are scored and recorded. Refreshing after each round of matches, plus once or twice on quiet days, is usually enough. During a match, readers who want to see a striker move up the list in real time are better served by a live score panel that says scored today, with the leaderboard catching up after the match.

For a five-league site on Starter, three leaderboard feeds refreshed eight times a day is 120 requests, a small share of the daily inclusion.

A leaderboard is also raw material for editorial work. A club site can filter the competition list to its own players and show where each sits in the race. A fantasy tool can pair goals with assists to highlight players who are involved in many attacks. A disciplinary tracker can watch the cards feed to warn that a player is one booking away from a suspension threshold, provided you know the competition rules and state them alongside.

Each of these is a view over the same supplied rows. Filter and annotate, but keep the underlying counts as supplied. When you combine scorers and assists into a single involvement figure, label it as your own calculation and make the components visible so readers can check it.

Season-end pages are another strong use. Once a competition ends, request the final leaderboards once, store them with the season label, and build an archive page from your own copy. That page then costs nothing to serve in future seasons. Where a final tally is later corrected, a single manual refresh brings your copy back in line.

A word on scope: the leaderboard feeds report what the source records for each competition. Smaller competitions may have shorter lists or omit assists entirely. If an assists feed returns nothing useful for a league, hide that tab for that league rather than showing an empty table, and say that assists are not recorded there.

Finally, think about how leaderboards appear in search and on social cards. A static page per competition that renders the supplied list on the server will be read reliably by crawlers, and a short sentence above the list stating which competition and season it covers helps readers who arrive from elsewhere understand what they are looking at.

Leaderboard bugs tend to surface on the busiest days, so test against saved responses before then. Keep a handful of real responses from your own requests: one early in a season with many tied players on one goal, one late in a season, and one from a competition with sparse records. Run your component against each and confirm it keeps the supplied order, shows ties as ties, handles a missing club name gracefully and does not crash when the list is short or empty.

Check your joins too. If you attach profile data on Growth or Pro, confirm that a player whose profile request fails still appears in the leaderboard with the supplied name, rather than disappearing. A leaderboard that silently drops a row is worse than one with a missing photo, because readers notice a missing top scorer immediately.

Finally, confirm that your cache key includes the leagueId, so that two competitions never overwrite each other's leaderboard in your own storage.

Starter is EUR 29 a month for five selected leagues and 5,000 successful requests per UTC day, and includes league-scoped leaderboards for those leagues. Player profiles and images are not on Starter, so leaderboards with headshots and player pages need Growth at EUR 99, with all available package leagues and 25,000 requests a day, or Pro at EUR 249 with 250,000.

Successful requests above the inclusion cost EUR 0.002 each, billed monthly on the EUR subscription; failed and denied requests are not billed. The account safety ceiling is 100 requests per second. There is no free trial, and no VAT is currently charged.