Football assist leaders API for competition leaderboards

Goals are rarely disputed; assists often are. Different organisations credit them differently. Some count only the final pass. Some include a shot that is parried to a teammate, a penalty won, or a deflected pass. Fantasy games frequently have their own rules that differ from any official record. None of these is wrong, but they produce different numbers for the same player.

The assists feed gives you the source's leaderboard for a competition, under the source's definition. Present it as that, labelled simply as assists, and do not mix in numbers from another definition. If your product also runs a fantasy game with its own assist rules, keep the two clearly separate and name your own metric differently, so a reader never sees two conflicting assist counts for the same player without explanation.

The feed takes one required parameter, leagueId, a positive numeric competition identifier sent as a string. It is cached for about fifteen minutes. Responses use the gateway envelope: data holds the leaderboard as supplied, and meta records the feed, UTC fetch time, cache time and qualification. Player and team identifiers are strings, and source attributes keep their at-sign prefix. We have not published a normalised leaderboard schema, so map from a real sample.

Render rows in the order supplied. If the source provides a rank or position attribute, display it; if it provides only counts, show tied players as tied. Re-sorting the list yourself can reorder tied players in a way that contradicts the competition's own handling.

When assists are missing or sparse for a competition, it is tempting to fill the gap with something nearby: key passes, chances created, or goal involvements computed by adding goals to some estimate. Each of those is a different metric. Presenting one under the assists heading misleads readers, and computing one from incomplete data compounds the problem.

If you want to show a creative-player leaderboard from other statistics, build it as its own feature, from data the source actually supplies, with its own name and an explanation of how it is calculated. Leave the assists leaderboard as the supplied list, or leave it out.

Assist recording depends on the depth of event data a source keeps for a competition. Top divisions are usually well covered. Lower tiers, youth competitions and some cups may have short lists or no assist data at all. An empty or very short leaderboard in those cases reflects what is recorded, not a season in which nobody created anything.

Handle this per competition. If the assists feed returns little for a league, hide the assists tab for that league and say that assists are not recorded there, rather than showing an empty table. Revisit the decision each season, because coverage can improve.

Assist leaders and top scorers are natural companions. A combined page that shows both lists side by side, each in its own supplied order, gives readers the full attacking picture without inventing anything. Join the two on player identifiers if you want to highlight players who appear in both lists.

If you add a column that sums goals and assists, label it as your own calculation and keep the components visible. Readers should be able to see that a combined figure came from two supplied numbers, and that definitions of each come from the source.

Assist counts change when matches are played and recorded, and sometimes in the days afterwards when an assist is reassigned. Refreshing after each round of matches, plus once on the following day to pick up corrections, keeps a leaderboard accurate. Polling during matches is not useful; the cache is about fifteen minutes and the source typically updates after events are recorded.

Store each refresh with its fetch time if you want to show movement, such as a player climbing three places after a weekend. That history also helps you explain a sudden change to a reader who noticed an assist disappear.

A single leaderboard is a snapshot of one moment. The story readers enjoy is the race: who led after ten rounds, when a midfielder overtook a winger, how a late-season run changed the order. Telling that story requires your own history, because the feed returns the current list rather than past versions. Store each refresh with its fetch time and the competition identifier, and you can draw a simple line chart of the leading players' totals over the season.

Keep the chart honest. Plot only values you actually stored, mark gaps where a refresh failed, and note that totals reflect the source's records at each moment, including any later corrections. If an assist was removed after review, the line should fall, and a brief annotation explaining why is better than smoothing it away.

Each row in the leaderboard represents a player, and the player identifier is the reliable way to link that row to anything else. On Growth and Pro you can join it to a player profile and, where available, a portrait. On every plan you can join it to squads for the same competition, which lets you show the player's current club even if the leaderboard row carries a club name that changed after a transfer.

Avoid matching rows to players by name. Two players with the same surname in the same league is common, and a leaderboard that attaches the wrong photo to a row is the kind of mistake readers screenshot. If an identifier in the leaderboard is not in your stored squads, keep the row with its supplied name and queue the identifier for review.

Save a real assists response for each competition you cover and build your table component against it. Include one response where players are tied, and one where the list is short early in the season. Tests that render saved samples catch mapping mistakes before readers do, and they make it safe to change layouts without re-requesting data.

Assists is league addressed and available on all three plans for entitled leagues. Starter at EUR 29 a month is limited to your five saved leagues. Growth at EUR 99 and Pro at EUR 249 cover all available package leagues. Player profiles and player images, which enrich leaderboard rows, are global services not included in Starter.

A leaderboard refreshed eight times a day for five leagues is forty successful requests. Above the daily inclusion, requests cost EUR 0.002 each on the monthly EUR invoice; failed and denied requests are not billed. No free trial is offered, and no VAT is currently charged.