football-data.org

football-data.org

This connector reads the football-data.org API v4 (https://api.football-data.org/v4): competitions, league tables, fixtures and results, head-to-head, teams and squads, players, top scorers and areas.

Setup

Register at football-data.org (free) and copy the API token from the e-mail you receive, or from your account page. Put it in FOOTBALL_DATA_API_TOKEN. It is sent as the X-Auth-Token header.

Plans and coverage

• The free plan covers 12 competitions: Premier League (PL), Championship (ELC), Bundesliga (BL1), Serie A (SA), LaLiga (PD), Ligue 1 (FL1), Eredivisie (DED), Primeira Liga (PPL), Brasileirao Serie A (BSA), Champions League (CL), European Championship (EC) and FIFA World Cup (WC). It includes fixtures, results, league tables and scorers. Scores and schedules are delayed on the free plan; live scores, lineups and match statistics need a paid plan.
• A competition or resource outside the plan answers 403 "restricted ... check your subscription". That is the plan, not a broken token. Single matches of past seasons can answer 403 on the free plan as well. An invalid token answers 400 "Your API token is invalid".
• Rate limit: 10 requests per minute on the free plan, more on paid plans. On 429 wait about a minute before retrying. One competition match list returns a whole season, so prefer it to many single-match calls.

Which football connector

football-data.org is free and covers the big leagues well. The API-Football connector (api-football) covers over 1,000 leagues and cups and adds lineups, player statistics, injuries, predictions and betting odds, but needs a paid plan beyond 100 requests a day. Use this one for tables, fixtures, results and scorers of the major competitions; use API-Football for smaller leagues and deep match data.

Ids and codes

• Competitions take a code (PL, BL1, SA, PD, FL1, CL, WC ...) or a numeric id. football_data_list_competitions lists the ones your token can read.
• Team, match and person ids are integers that appear in every list. Find a team with football_data_list_competition_teams, a match with football_data_list_competition_matches or football_data_list_matches.
• season is the starting year: 2025 means 2025/26.
• All times are UTC (utcDate). Convert before quoting a kickoff time.

Match lists

List endpoints hide goals, bookings, lineups and substitutions to keep answers small. Set unfold_goals (and the other unfold_* flags) to include them, or call football_data_get_match for one match. A date range on football_data_list_matches may span at most 10 days.

Where to start

football_data_list_competitions to see what the token covers, then football_data_get_standings or football_data_list_competition_matches with a code. For a preview: find the match id, then football_data_get_head2head and football_data_list_team_matches for both teams' recent form.