football-data.org

Implementation notes

When to use football-data.org

football-data.org is the most credible free football API: real fixtures, live scores, standings, squads, and scorer tables for twelve competitions including the Premier League, La Liga, Serie A, Bundesliga, Ligue 1, the Champions League, and the World Cup. A free key arrives instantly and the data is properly maintained rather than crowd-sourced, which puts it well ahead of TheSportsDB anywhere correctness matters. Use it for league table widgets, fixture calendars, fantasy tools, and Slack or Discord bots that post results. The free tier is genuinely usable — ten requests a minute is ample for a cached dashboard — and the paid tiers scale sensibly if the project grows into something. Where it stops is real time: minute-by-minute in-play data, deep historical seasons, and the long tail of smaller leagues all sit behind paid plans, and the free tier's competition whitelist is narrower than the endpoint surface makes it look.

Common pitfalls

• The free tier gates competitions, and the gate returns 403 rather than 404. Querying the Eredivisie or the Championship with a free key produces a permission error that is indistinguishable at the status-code level from a bad token, which sends people re-issuing keys that were never the problem. Read the message body — it names the restriction explicitly.
• Authentication is the X-Auth-Token request header. There is no api_key or token query parameter, and passing one returns 403 with the same shape as a restricted-competition error. That also means anything unable to set custom headers — an img tag, a bare browser URL, a webhook that only accepts a URL — cannot call this API directly and needs a proxy.
• Every response carries an X-Requests-Available-Minute header telling you exactly how many calls remain in the window. Read it rather than guessing. The free tier is ten per minute, and a page rendering standings plus fixtures plus scorers is already three calls before you add a second competition. Cache tables for at least a minute — they do not change faster than that outside match hours.
• In-play data is delayed on the free tier. Match status transitions and minute markers lag the actual match, so a bot posting goals as they happen will be visibly behind social media. The free tier is for tables, fixtures, and post-match results; anything resembling live commentary needs a paid plan.

Quick start (bash)

curl -s -H 'X-Auth-Token: YOUR_KEY' 'https://api.football-data.org/v4/competitions/PL/standings' | jq '.standings[0].table[0:3] | .[] | {position, team: .team.shortName, points}'
# restricted competitions return 403, not 404 - and check your remaining budget:
curl -sD - -o /dev/null -H 'X-Auth-Token: YOUR_KEY' 'https://api.football-data.org/v4/competitions/PL/matches' | grep -i x-requests-available

Embed this badge

Add a live status badge to your README, docs, or website.

Markdown

[![football-data.org Status](https://api.freeapi.watch/badge/football-data.svg)](https://freeapi.watch/football-data)

HTML

<a href="https://freeapi.watch/football-data"><img src="https://api.freeapi.watch/badge/football-data.svg" alt="football-data.org Status"/></a>