Football cards leaders API for disciplinary leaderboards

The cards feed takes one required parameter, leagueId, a positive numeric competition identifier sent as a string, and returns that competition's disciplinary leaderboard. It is cached for about fifteen minutes. Responses use the standard envelope, with data holding the leaderboard as supplied and meta recording the feed, UTC fetch time, cache time and qualification. Identifiers are strings and source attributes keep their at-sign prefix.

How card types are represented, and whether second yellows that lead to a red are counted separately, is something to read from a real response for the competitions you cover. Label every count with the card type the source gives it. A column headed cards with a single number is ambiguous; a column headed yellow cards or red cards, matching the source, is not.

Disciplinary numbers are easy to misread because readers bring assumptions. Some assume a red card count includes dismissals for two yellows; some assume it does not. Some assume yellow counts reset at a point in the season; the data does not do that for you. Your labels and a short explanatory note carry the burden of clarity.

Keep the competition visible too. A player's card count in a league says nothing about their cards in a cup, and suspensions in many competitions are tracked per competition. A leaderboard heading that names the competition and season prevents a reader from adding numbers that should not be added.

A popular feature is a warning that a player is one booking away from a suspension. The cards feed supplies counts; it does not supply suspension thresholds, amnesty dates or the disciplinary decisions of a competition authority. Those come from the competition's rules, which differ between leagues and can change between seasons.

If you build the feature, document the rules you apply for each competition, cite where they come from, and show the reader that the warning is your calculation. Never state that a player is suspended on the basis of a count alone; a suspension is a decision by a governing body, and the count may not reflect appeals, rescinded cards or other adjustments.

The example fetches a cards leaderboard and passes it to a function that adds your own annotations from a rules file you maintain. Keeping the rules in a separate, versioned file makes it obvious which parts of the page come from data and which from your interpretation.

A disciplinary leaderboard can easily become a list of villains. Positions and roles shape card counts: defensive midfielders and full-backs collect more bookings than wingers, and a player with many minutes will accumulate more than a substitute. If you present the list, keep the tone neutral. Avoid headlines that rank players as the dirtiest or most reckless on the basis of counts alone.

Context helps. If the source supplies appearances or minutes for the same competition, showing them next to card counts lets readers judge rates for themselves. If you compute a rate, label it as your calculation.

Cards are occasionally rescinded on appeal or reassigned when a referee booked the wrong player. Those changes reach the leaderboard only when the source records them, which may be days after the match. Refresh the leaderboard after each round and again a day or two later, and store each copy with its fetch time so you can see when a count went down.

If a card count falls, do not treat it as an error. It is often the most accurate update you will receive.

Card counts are sometimes used to discuss referees: which officials show the most cards, which matches were the most heated. The cards feed is a player leaderboard and does not attribute cards to officials. If you want to write about refereeing, you need other data, and you should be careful that a player-level leaderboard does not become an implied criticism of officials it says nothing about.

Similarly, a team's total cards can be computed by summing player rows that share a club, but that sum is your calculation, and players who moved clubs mid-season will distort it. Label any team totals as derived and explain how transfers are handled.

Many fantasy games deduct points for bookings and dismissals. If your tool uses the cards feed to inform those deductions, remember that the leaderboard is a season total, not a per-match record. Per-match scoring needs match-level data, which comes from match statistics or match detail where your plan includes them. Using leaderboard deltas between refreshes to infer which match a card came from is fragile, because corrections and refresh timing can misattribute it.

Use the leaderboard for what it does well: showing who has accumulated the most cards in a competition so far, as the source records it.

Disciplinary tables have more columns than most leaderboards: one or more card types, perhaps appearances, perhaps your own rate. On a phone, show the player, club and the most important supplied count, and let readers expand a row for the rest. Use text labels rather than coloured squares alone to indicate card types, because colour by itself is not accessible to everyone. A small amber or red marker beside a written label works for all readers.

Keep saved cards responses for each competition you cover and test your table component against them, including a response early in a season when lists are short and one where several players share a total. Assert that rows render in the supplied order and that card types are labelled in words. Those tests protect you from regressions when you redesign the table.

Always state the competition and the card type in the table heading, so a screenshot shared out of context still makes sense.

Cards is league addressed and available on all three plans for entitled leagues. Starter at EUR 29 a month covers your five saved leagues. Growth at EUR 99 and Pro at EUR 249 cover all available package leagues. Player profiles and images for row enrichment are global services not included in Starter.

Refreshing after each round and once more the next day is a handful of successful requests a week per league. 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.