# football-data.org > Follow football with football-data.org: league tables, fixtures and results, squads, top scorers and head-to-head records across the Premier League, La Liga, Serie A, the Bundesliga, Ligue 1, the Champions League, the World Cup and more. Listing the competitions and areas it covers needs no account at all; reading any of them needs a free API token. App · Sports · 16 actions. Web page: https://docs.lodol.com/docs/integrations/football-data ## Actions ### Get a competition Look up one league or cup by its code or id and get its current season, every season on file, and the winner of each. Needs a free API token: football-data.org serves the competition list anonymously but not a single competition. **Inputs** - Competition (`competition`, text, required): The competition to read. Pick one from the list, or pass a league code such as PL or a numeric id such as 2021 from an earlier step. **Outputs** - `area` (object): The country or region this belongs to. - `code` (text): Short league code, e.g. PL. Usable anywhere an id is. Null for a few competitions. - `current_season` (object): A season of the competition. - `emblem` (text): Competition emblem image URL. - `id` (number): The competition's numeric id. - `last_updated` (text): When this record last changed, ISO 8601 in UTC. - `name` (text): Competition name, e.g. Premier League. - `number_of_available_seasons` (number): Null here: the API only reports it on the competition list. Count the seasons instead. - `plan` (text): Null here: the API only reports the plan on the competition list. - `seasons` (list): Every season on file, most recent first. - `type` (text): One of LEAGUE, LEAGUE_CUP, CUP or PLAYOFFS. **Example output** ```json { "area": { "code": "ENG", "flag": "https://crests.football-data.org/770.svg", "id": 2072, "name": "England", "parent_area": "Europe", "parent_area_id": 2077 }, "code": "PL", "current_season": { "current_matchday": 24, "end_date": "2026-05-24", "id": 2287, "stages": [ "REGULAR_SEASON" ], "start_date": "2025-08-15", "winner": null }, "emblem": "https://crests.football-data.org/PL.png", "id": 2021, "last_updated": "2026-02-13T00:20:58Z", "name": "Premier League", "number_of_available_seasons": null, "plan": null, "seasons": [ { "current_matchday": 24, "end_date": "2026-05-24", "id": 2287, "stages": [ "REGULAR_SEASON" ], "start_date": "2025-08-15", "winner": null } ], "type": "LEAGUE" } ``` ### Get a match Look up one match by id and get both sides, the score at half and full time, the ground, the attendance and the officials, plus the goals, cards, substitutions and lineups where the API has them. Needs a free API token. **Inputs** - Match ID (`match_id`, text, required): The match's numeric id, for example 544214. Any of the match lists returns these ids. - Include lineups and events (`include_details`, true/false): Ask football-data.org to unfold the goals, cards, substitutions and lineups. On by default. Turn it off for a smaller response when only the score matters. Default: `true`. **Outputs** - `area` (object): The country or region this belongs to. - `attendance` (number): Crowd size, where known. - `away_team` (object): One side of the match. The lineup, bench, formation and statistics are only filled in when the match is read with lineups and events included. - `bookings` (list): Cards shown, where the match was read with events included. - `competition` (object): The competition this belongs to. - `goals` (list): Every goal, in order. Only filled in when the match is read with lineups and events included. - `group` (text): Group, e.g. GROUP_A. Null outside a group stage. - `home_team` (object): One side of the match. The lineup, bench, formation and statistics are only filled in when the match is read with lineups and events included. - `id` (number): The match id. Use with Get a match. - `injury_time` (number): Added minutes, where known. - `last_updated` (text): When this match last changed, ISO 8601 in UTC. - `matchday` (number): Matchday number. - `minute` (number): Minute played, while in progress. - `odds` (object): Betting odds. Null unless the connected token has the paid odds package. - `penalties` (list): Penalties, including shootout kicks. - `referees` (list): The match officials. - `score` (object): How the match stood, or finished. - `season` (object): A season of the competition. - `stage` (text): Stage, e.g. REGULAR_SEASON, GROUP_STAGE or SEMI_FINALS. - `status` (text): SCHEDULED, TIMED, IN_PLAY, PAUSED, EXTRA_TIME, PENALTY_SHOOTOUT, FINISHED, SUSPENDED, POSTPONED, CANCELLED or AWARDED. - `substitutions` (list): Substitutions, where the match was read with events included. - `utc_date` (text): Kick-off time, ISO 8601 in UTC. - `venue` (text): The ground the match is played at. **Example output** ```json { "area": { "code": "ENG", "flag": "https://crests.football-data.org/770.svg", "id": 2072, "name": "England", "parent_area": "Europe", "parent_area_id": 2077 }, "attendance": 60214, "away_team": { "bench": [], "coach": null, "crest": "https://crests.football-data.org/61.png", "formation": null, "id": 61, "league_rank": null, "lineup": [], "name": "Chelsea FC", "short_name": "Chelsea", "statistics": null, "tla": "CHE" }, "bookings": [ { "card": "YELLOW", "minute": 62, "player": { "id": 3374, "name": "Mois\u00e9s Caicedo" }, "team": { "id": 61, "name": "Chelsea FC" } } ], "competition": { "code": "PL", "emblem": "https://crests.football-data.org/PL.png", "id": 2021, "name": "Premier League", "type": "LEAGUE" }, "goals": [ { "assist": { "id": 3202, "name": "Martin \u00d8degaard" }, "injury_time": null, "minute": 23, "score": { "away": 0, "home": 1 }, "scorer": { "id": 3754, "name": "Bukayo Saka" }, "team": { "id": 57, "name": "Arsenal FC" }, "type": "REGULAR" } ], "group": null, "home_team": { "bench": [ { "contract": { "start": null, "until": null }, "date_of_birth": "1995-09-15", "first_name": "David", "id": 3305, "last_name": "Raya", "last_updated": "2026-01-08T10:12:33Z", "market_value": null, "name": "David Raya", "nationality": "Spain", "position": "Goalkeeper", "section": null, "shirt_number": 22 } ], "coach": null, "crest": "https://crests.football-data.org/57.png", "formation": "4-3-3", "id": 57, "league_rank": 1, "lineup": [ { "contract": { "start": null, "until": null }, "date_of_birth": "1995-09-15", "first_name": "David", "id": 3305, "last_name": "Raya", "last_updated": "2026-01-08T10:12:33Z", "market_value": null, "name": "David Raya", "nationality": "Spain", "position": "Goalkeeper", "section": null, "shirt_number": 22 }, { "contract": { "start": null, "until": null }, "date_of_birth": "2001-09-05", "first_name": "Bukayo", "id": 3754, "last_name": "Saka", "last_updated": "2026-01-08T10:12:33Z", "market_value": null, "name": "Bukayo Saka", "nationality": "England", "position": "Right Winger", "section": null, "shirt_number": 7 } ], "name": "Arsenal FC", "short_name": "Arsenal", "statistics": { "ball_possession": 58, "corner_kicks": 7, "fouls": 9, "red_cards": 0, "shots": 14, "shots_on_goal": 6, "yellow_cards": 1 }, "tla": "ARS" }, "id": 544214, "injury_time": null, "last_updated": "2026-02-13T00:20:58Z", "matchday": 24, "minute": null, "odds": null, "penalties": [], "referees": [ { "id": 43888, "name": "Michael Oliver", "nationality": "England", "type": "REFEREE" } ], "score": { "duration": "REGULAR", "extra_time": { "away": null, "home": null }, "full_time": { "away": 1, "home": 2 }, "half_time": { "away": 0, "home": 1 }, "penalties": { "away": null, "home": null }, "regular_time": { "away": null, "home": null }, "winner": "HOME_TEAM" }, "season": { "current_matchday": 24, "end_date": "2026-05-24", "id": 2287, "stages": [ "REGULAR_SEASON" ], "start_date": "2025-08-15", "winner": null }, "stage": "REGULAR_SEASON", "status": "FINISHED", "substitutions": [ { "minute": 71, "player_in": { "id": 149221, "name": "Leandro Trossard" }, "player_out": { "id": 3754, "name": "Bukayo Saka" }, "team": { "id": 57, "name": "Arsenal FC" } } ], "utc_date": "2026-02-08T16:30:00Z", "venue": "Emirates Stadium" } ``` ### Get a person Look up one player, coach or official by id and get their position, date of birth, nationality, shirt number and current club. Needs a free API token. **Inputs** - Person ID (`person_id`, text, required): The person's numeric id, for example 3754. A team's squad and a competition's scorers both carry these ids. **Outputs** - `contract` (object): Contract dates as year-month, e.g. 2024-07. Only on paid plans; both ends are null otherwise. - `current_team` (object): The club the person is at now, with their contract there where the plan includes it. - `date_of_birth` (text): Date of birth, yyyy-MM-dd. - `first_name` (text): First name. - `id` (number): The person's id. Use with Get a person. - `last_name` (text): Last name. - `last_updated` (text): When this record last changed, ISO 8601 in UTC. - `market_value` (number): Estimated market value in euros. Paid plans only. - `name` (text): Full name. - `nationality` (text): Nationality, e.g. Germany. - `position` (text): Playing position. The specific role on the person resource, e.g. Centre-Forward, and the broad grouping, e.g. Offence, where the person is embedded in a squad or scorer list. - `section` (text): Broad grouping, e.g. Offence. Not always present. - `shirt_number` (number): Squad number, where known. **Example output** ```json { "contract": { "start": null, "until": null }, "current_team": { "address": "75 Drayton Park London N5 1BU", "area": { "code": "ENG", "flag": "https://crests.football-data.org/770.svg", "id": 2072, "name": "England", "parent_area": "Europe", "parent_area_id": 2077 }, "club_colors": "Red / White", "coach": { "contract": { "start": null, "until": null }, "date_of_birth": "1982-03-26", "first_name": "Mikel", "id": 11592, "last_name": "Arteta", "last_updated": "2026-01-08T10:12:33Z", "market_value": null, "name": "Mikel Arteta", "nationality": "Spain", "position": null, "section": null, "shirt_number": null }, "contract": null, "crest": "https://crests.football-data.org/57.png", "founded": 1886, "id": 57, "last_updated": "2026-01-08T10:12:33Z", "market_value": null, "name": "Arsenal FC", "running_competitions": [ { "code": "PL", "emblem": "https://crests.football-data.org/PL.png", "id": 2021, "name": "Premier League", "type": "LEAGUE" } ], "short_name": "Arsenal", "squad": [ { "contract": { "start": null, "until": null }, "date_of_birth": "2001-09-05", "first_name": "Bukayo", "id": 3754, "last_name": "Saka", "last_updated": "2026-01-08T10:12:33Z", "market_value": null, "name": "Bukayo Saka", "nationality": "England", "position": "Right Winger", "section": null, "shirt_number": 7 } ], "staff": [], "tla": "ARS", "type": null, "venue": "Emirates Stadium", "website": "http://www.arsenal.com" }, "date_of_birth": "2001-09-05", "first_name": "Bukayo", "id": 3754, "last_name": "Saka", "last_updated": "2026-01-08T10:12:33Z", "market_value": null, "name": "Bukayo Saka", "nationality": "England", "position": "Right Winger", "section": null, "shirt_number": 7 } ``` ### Get a team Look up one club by id and get its ground, colours, founding year, website, the competitions it is currently playing in, its coach and its squad. Needs a free API token. **Inputs** - Team ID (`team_id`, text, required): The club's numeric id, for example 57 for Arsenal. List a competition's teams to find one. **Outputs** - `address` (text): The club's postal address. - `area` (object): The country or region this belongs to. - `club_colors` (text): Club colours, e.g. Red / White. - `coach` (object): A player, coach or member of staff. - `contract` (object): Contract dates as year-month, e.g. 2024-07. Only on paid plans; both ends are null otherwise. - `crest` (text): Club crest image URL. - `founded` (number): Year the club was founded. - `id` (number): The team's id. Use it with Get a team. - `last_updated` (text): When this record last changed, ISO 8601 in UTC. - `market_value` (number): Squad market value in euros. Paid plans only. - `name` (text): Full club name, e.g. Arsenal FC. - `running_competitions` (list): The competitions this team is currently playing in. - `short_name` (text): Shorter name, e.g. Arsenal. - `squad` (list): People, each with their position and nationality. - `staff` (list): Backroom staff. Empty on the free plan. - `tla` (text): Three-letter abbreviation, e.g. ARS. - `type` (text): MEN_CLUB, MEN_NATIONAL, WOMEN_CLUB or WOMEN_NATIONAL, where the API reports it. - `venue` (text): Home ground name. - `website` (text): The club's website. **Example output** ```json { "address": "75 Drayton Park London N5 1BU", "area": { "code": "ENG", "flag": "https://crests.football-data.org/770.svg", "id": 2072, "name": "England", "parent_area": "Europe", "parent_area_id": 2077 }, "club_colors": "Red / White", "coach": { "contract": { "start": null, "until": null }, "date_of_birth": "1982-03-26", "first_name": "Mikel", "id": 11592, "last_name": "Arteta", "last_updated": "2026-01-08T10:12:33Z", "market_value": null, "name": "Mikel Arteta", "nationality": "Spain", "position": null, "section": null, "shirt_number": null }, "contract": null, "crest": "https://crests.football-data.org/57.png", "founded": 1886, "id": 57, "last_updated": "2026-01-08T10:12:33Z", "market_value": null, "name": "Arsenal FC", "running_competitions": [ { "code": "PL", "emblem": "https://crests.football-data.org/PL.png", "id": 2021, "name": "Premier League", "type": "LEAGUE" } ], "short_name": "Arsenal", "squad": [ { "contract": { "start": null, "until": null }, "date_of_birth": "2001-09-05", "first_name": "Bukayo", "id": 3754, "last_name": "Saka", "last_updated": "2026-01-08T10:12:33Z", "market_value": null, "name": "Bukayo Saka", "nationality": "England", "position": "Right Winger", "section": null, "shirt_number": 7 } ], "staff": [], "tla": "ARS", "type": null, "venue": "Emirates Stadium", "website": "http://www.arsenal.com" } ``` ### Get an area Look up one country, continent or football region by id, along with the areas nested inside it. Needs a free API token: football-data.org serves the area list anonymously but not a single area. **Inputs** - Area ID (`area_id`, text, required): The area's numeric id, for example 2072 for England or 2077 for Europe. List areas to find one. **Outputs** - `child_areas` (list): The areas that sit inside this one. - `code` (text): Three-letter area code, e.g. ENG. Null for some regions. - `flag` (text): Flag image URL. Null if there is none. - `id` (number): The area's id. - `name` (text): Area name, e.g. England. - `parent_area` (text): Name of the area this one sits inside, e.g. Europe. - `parent_area_id` (number): Id of the area this one sits inside. **Example output** ```json { "child_areas": [ { "code": "ENG", "flag": "https://crests.football-data.org/770.svg", "id": 2072, "name": "England", "parent_area": "Europe", "parent_area_id": 2077 } ], "code": "EUR", "flag": "https://crests.football-data.org/EUR.svg", "id": 2077, "name": "Europe", "parent_area": "World", "parent_area_id": 2267 } ``` ### Get standings Read a competition's league table: position, points, form, goals for and against for every team, as an overall table plus separate home and away tables, or one table per group in a group stage. Cup and knockout competitions have no table. Needs a free API token. **Inputs** - Competition (`competition`, text, required): The competition to read. Pick one from the list, or pass a league code such as PL or a numeric id such as 2021 from an earlier step. - Season (`season`, number): Optional. The four-digit year the season starts in, so 2024 means the 2024/25 season. Defaults to the current season. Past seasons need a paid football-data.org plan. From 1900 to 2100. - Matchday (`matchday`, number): Optional. The table as it stood after this matchday, counting from 1. Points and goals are cumulative from the start of the season, not just this round. From 1 to 99. - As at date (`on_date`, date): Optional. The table as it stood on this date, for example who led at new year. **Outputs** - `area` (object): The country or region this belongs to. - `competition` (object): The competition this belongs to. - `count` (number): How many tables were returned. - `season` (object): A season of the competition. - `standings` (list): One table per stage and type. A league returns an overall, a home and an away table; a group stage returns one table per group. **Example output** ```json { "area": { "code": "ENG", "flag": "https://crests.football-data.org/770.svg", "id": 2072, "name": "England", "parent_area": "Europe", "parent_area_id": 2077 }, "competition": { "code": "PL", "emblem": "https://crests.football-data.org/PL.png", "id": 2021, "name": "Premier League", "type": "LEAGUE" }, "count": 1, "season": { "current_matchday": 24, "end_date": "2026-05-24", "id": 2287, "stages": [ "REGULAR_SEASON" ], "start_date": "2025-08-15", "winner": null }, "standings": [ { "group": null, "stage": "REGULAR_SEASON", "table": [ { "draw": 5, "form": [ "W", "D", "W", "W", "D" ], "goal_difference": 28, "goals_against": 20, "goals_for": 48, "lost": 3, "played_games": 24, "points": 53, "position": 1, "team": { "crest": "https://crests.football-data.org/57.png", "id": 57, "name": "Arsenal FC", "short_name": "Arsenal", "tla": "ARS" }, "won": 16 } ], "type": "TOTAL" } ] } ``` ### List a competition's matches List the fixtures and results of one league or cup, filtered by matchday, stage, group, status or date range. Each match comes with both sides, the score at half and full time, and the officials. Needs a free API token. **Inputs** - Competition (`competition`, text, required): The competition to read. Pick one from the list, or pass a league code such as PL or a numeric id such as 2021 from an earlier step. - Season (`season`, number): Optional. The four-digit year the season starts in, so 2024 means the 2024/25 season. Defaults to the current season. Past seasons need a paid football-data.org plan. From 1900 to 2100. - Matchday (`matchday`, number): Optional. Only this matchday, counting from 1. From 1 to 99. - Match status (`status`, list): Optional. Only matches in these states. Choosing none returns every state. Live is a shortcut for in play plus half time. One or more of: `SCHEDULED`, `TIMED`, `IN_PLAY` (In play), `PAUSED` (Paused (half time)), `EXTRA_TIME` (Extra time), `PENALTY_SHOOTOUT` (Penalty shootout), `FINISHED`, `SUSPENDED`, `POSTPONED`, `CANCELLED`, `AWARDED`, `LIVE` (Live (in play or paused)). - Stage (`stage`, text): Optional. Only matches at this stage, for example the group stage or the quarter-finals. One of: `FINAL`, `THIRD_PLACE` (Third place), `SEMI_FINALS` (Semi-finals), `QUARTER_FINALS` (Quarter-finals), `LAST_16` (Last 16), `LAST_32` (Last 32), `LAST_64` (Last 64), `ROUND_4` (Round 4), `ROUND_3` (Round 3), `ROUND_2` (Round 2), and 17 more. - Group (`group`, text): Optional. Only matches in this group. Applies to competitions with a group stage. One of: `GROUP_A` (Group A), `GROUP_B` (Group B), `GROUP_C` (Group C), `GROUP_D` (Group D), `GROUP_E` (Group E), `GROUP_F` (Group F), `GROUP_G` (Group G), `GROUP_H` (Group H), `GROUP_I` (Group I), `GROUP_J` (Group J), `GROUP_K` (Group K), `GROUP_L` (Group L). - From date (`date_from`, date): Optional. Only matches on or after this date. Must be set together with the to date. - To date (`date_to`, date): Optional. Only matches on or before this date. Must be set together with the from date. **Outputs** - `competition` (object): The competition this belongs to. - `count` (number): How many matches this response returned. - `matches` (list): The matching matches, earliest kick-off first. - `result_set` (object): The API's own summary of the match list. **Example output** ```json { "competition": { "code": "PL", "emblem": "https://crests.football-data.org/PL.png", "id": 2021, "name": "Premier League", "type": "LEAGUE" }, "count": 1, "matches": [ { "area": { "code": "ENG", "flag": "https://crests.football-data.org/770.svg", "id": 2072, "name": "England", "parent_area": "Europe", "parent_area_id": 2077 }, "attendance": null, "away_team": { "bench": [], "coach": null, "crest": "https://crests.football-data.org/61.png", "formation": null, "id": 61, "league_rank": null, "lineup": [], "name": "Chelsea FC", "short_name": "Chelsea", "statistics": null, "tla": "CHE" }, "bookings": [], "competition": { "code": "PL", "emblem": "https://crests.football-data.org/PL.png", "id": 2021, "name": "Premier League", "type": "LEAGUE" }, "goals": [], "group": null, "home_team": { "bench": [], "coach": null, "crest": "https://crests.football-data.org/57.png", "formation": null, "id": 57, "league_rank": null, "lineup": [], "name": "Arsenal FC", "short_name": "Arsenal", "statistics": null, "tla": "ARS" }, "id": 544214, "injury_time": null, "last_updated": "2026-02-13T00:20:58Z", "matchday": 24, "minute": null, "odds": null, "penalties": [], "referees": [ { "id": 43888, "name": "Michael Oliver", "nationality": "England", "type": "REFEREE" } ], "score": { "duration": "REGULAR", "extra_time": { "away": null, "home": null }, "full_time": { "away": 1, "home": 2 }, "half_time": { "away": 0, "home": 1 }, "penalties": { "away": null, "home": null }, "regular_time": { "away": null, "home": null }, "winner": "HOME_TEAM" }, "season": { "current_matchday": 24, "end_date": "2026-05-24", "id": 2287, "stages": [ "REGULAR_SEASON" ], "start_date": "2025-08-15", "winner": null }, "stage": "REGULAR_SEASON", "status": "FINISHED", "substitutions": [], "utc_date": "2026-02-08T16:30:00Z", "venue": "Emirates Stadium" } ], "result_set": { "competitions": [ "PL" ], "count": 1, "draws": null, "first": "2026-02-08", "last": "2026-02-08", "losses": null, "played": 1, "wins": null } } ``` ### List a competition's teams List every club playing in a competition's season, each with its ground, colours, founding year and squad. Needs a free API token. **Inputs** - Competition (`competition`, text, required): The competition to read. Pick one from the list, or pass a league code such as PL or a numeric id such as 2021 from an earlier step. - Season (`season`, number): Optional. The four-digit year the season starts in, so 2024 means the 2024/25 season. Defaults to the current season. Past seasons need a paid football-data.org plan. From 1900 to 2100. **Outputs** - `competition` (object): The competition this belongs to. - `count` (number): How many teams were returned. - `season` (object): A season of the competition. - `teams` (list): The teams taking part. **Example output** ```json { "competition": { "code": "PL", "emblem": "https://crests.football-data.org/PL.png", "id": 2021, "name": "Premier League", "type": "LEAGUE" }, "count": 1, "season": { "current_matchday": 24, "end_date": "2026-05-24", "id": 2287, "stages": [ "REGULAR_SEASON" ], "start_date": "2025-08-15", "winner": null }, "teams": [ { "address": "75 Drayton Park London N5 1BU", "area": { "code": "ENG", "flag": "https://crests.football-data.org/770.svg", "id": 2072, "name": "England", "parent_area": "Europe", "parent_area_id": 2077 }, "club_colors": "Red / White", "coach": { "contract": { "start": null, "until": null }, "date_of_birth": "1982-03-26", "first_name": "Mikel", "id": 11592, "last_name": "Arteta", "last_updated": "2026-01-08T10:12:33Z", "market_value": null, "name": "Mikel Arteta", "nationality": "Spain", "position": null, "section": null, "shirt_number": null }, "contract": null, "crest": "https://crests.football-data.org/57.png", "founded": 1886, "id": 57, "last_updated": "2026-01-08T10:12:33Z", "market_value": null, "name": "Arsenal FC", "running_competitions": [ { "code": "PL", "emblem": "https://crests.football-data.org/PL.png", "id": 2021, "name": "Premier League", "type": "LEAGUE" } ], "short_name": "Arsenal", "squad": [ { "contract": { "start": null, "until": null }, "date_of_birth": "2001-09-05", "first_name": "Bukayo", "id": 3754, "last_name": "Saka", "last_updated": "2026-01-08T10:12:33Z", "market_value": null, "name": "Bukayo Saka", "nationality": "England", "position": "Right Winger", "section": null, "shirt_number": 7 } ], "staff": [], "tla": "ARS", "type": null, "venue": "Emirates Stadium", "website": "http://www.arsenal.com" } ] } ``` ### List a person's matches List the matches a player was involved in, filtered by date range, competition, status, whether they started or were on the bench, and whether they scored, assisted or were substituted. Needs a free API token. **Inputs** - Person ID (`person_id`, text, required): The person's numeric id, for example 3754. - Match status (`status`, list): Optional. Only matches in these states. Choosing none returns every state. Live is a shortcut for in play plus half time. One or more of: `SCHEDULED`, `TIMED`, `IN_PLAY` (In play), `PAUSED` (Paused (half time)), `EXTRA_TIME` (Extra time), `PENALTY_SHOOTOUT` (Penalty shootout), `FINISHED`, `SUSPENDED`, `POSTPONED`, `CANCELLED`, `AWARDED`, `LIVE` (Live (in play or paused)). - Competitions (`competitions`, list): Optional. Only matches in these competitions. All of them are included when nothing is chosen. - Started or benched (`lineup`, text): Optional. Only matches the player started, or only those they began on the bench. One of: `STARTING` (Starting XI), `BENCH`. - Player event (`event`, text): Optional. Only matches where the player did this, for example scored a goal. One of: `GOAL` (Scored a goal), `ASSIST` (Made an assist), `SUB_IN` (Came on as a substitute), `SUB_OUT` (Was substituted off). - From date (`date_from`, date): Optional. Only matches on or after this date. Must be set together with the to date. - To date (`date_to`, date): Optional. Only matches on or before this date. Must be set together with the from date. - Maximum matches (`limit`, number): Optional. How many matches to return, up to 100. From 1 to 100. - Skip (`offset`, number): Optional. Skip this many matches before reading a page. From 0 to 100. Default: `0`. **Outputs** - `aggregations` (object): The player's totals across the matched matches. Null on the free plan, which does not compute them. - `count` (number): How many matches this response returned. - `matches` (list): The matching matches, earliest kick-off first. - `person` (object): A player, coach or member of staff. - `result_set` (object): The API's own summary of the match list. **Example output** ```json { "aggregations": null, "count": 1, "matches": [ { "area": { "code": "ENG", "flag": "https://crests.football-data.org/770.svg", "id": 2072, "name": "England", "parent_area": "Europe", "parent_area_id": 2077 }, "attendance": null, "away_team": { "bench": [], "coach": null, "crest": "https://crests.football-data.org/61.png", "formation": null, "id": 61, "league_rank": null, "lineup": [], "name": "Chelsea FC", "short_name": "Chelsea", "statistics": null, "tla": "CHE" }, "bookings": [], "competition": { "code": "PL", "emblem": "https://crests.football-data.org/PL.png", "id": 2021, "name": "Premier League", "type": "LEAGUE" }, "goals": [], "group": null, "home_team": { "bench": [], "coach": null, "crest": "https://crests.football-data.org/57.png", "formation": null, "id": 57, "league_rank": null, "lineup": [], "name": "Arsenal FC", "short_name": "Arsenal", "statistics": null, "tla": "ARS" }, "id": 544214, "injury_time": null, "last_updated": "2026-02-13T00:20:58Z", "matchday": 24, "minute": null, "odds": null, "penalties": [], "referees": [ { "id": 43888, "name": "Michael Oliver", "nationality": "England", "type": "REFEREE" } ], "score": { "duration": "REGULAR", "extra_time": { "away": null, "home": null }, "full_time": { "away": 1, "home": 2 }, "half_time": { "away": 0, "home": 1 }, "penalties": { "away": null, "home": null }, "regular_time": { "away": null, "home": null }, "winner": "HOME_TEAM" }, "season": { "current_matchday": 24, "end_date": "2026-05-24", "id": 2287, "stages": [ "REGULAR_SEASON" ], "start_date": "2025-08-15", "winner": null }, "stage": "REGULAR_SEASON", "status": "FINISHED", "substitutions": [], "utc_date": "2026-02-08T16:30:00Z", "venue": "Emirates Stadium" } ], "person": { "contract": { "start": null, "until": null }, "date_of_birth": "2001-09-05", "first_name": "Bukayo", "id": 3754, "last_name": "Saka", "last_updated": "2026-01-08T10:12:33Z", "market_value": null, "name": "Bukayo Saka", "nationality": "England", "position": "Right Winger", "section": null, "shirt_number": 7 }, "result_set": { "competitions": [ "PL" ], "count": 1, "draws": null, "first": "2026-02-08", "last": "2026-02-08", "losses": null, "played": 1, "wins": null } } ``` ### List a team's matches List one club's fixtures and results across every competition it plays, filtered by date range, season, status, competition or home and away. The summary also carries the club's win, draw and loss record over the matches returned. Needs a free API token. **Inputs** - Team ID (`team_id`, text, required): The club's numeric id, for example 57 for Arsenal. - Season (`season`, number): Optional. The four-digit year the season starts in, so 2024 means the 2024/25 season. Defaults to the current season. Past seasons need a paid football-data.org plan. From 1900 to 2100. - Match status (`status`, list): Optional. Only matches in these states. Choosing none returns every state. Live is a shortcut for in play plus half time. One or more of: `SCHEDULED`, `TIMED`, `IN_PLAY` (In play), `PAUSED` (Paused (half time)), `EXTRA_TIME` (Extra time), `PENALTY_SHOOTOUT` (Penalty shootout), `FINISHED`, `SUSPENDED`, `POSTPONED`, `CANCELLED`, `AWARDED`, `LIVE` (Live (in play or paused)). - Home or away (`venue`, text): Optional. Only the club's home matches, or only its away matches. Both are included when nothing is chosen. One of: `HOME`, `AWAY`. - Competitions (`competitions`, list): Optional. Only matches in these competitions. All of them are included when nothing is chosen. - From date (`date_from`, date): Optional. Only matches on or after this date. Must be set together with the to date. - To date (`date_to`, date): Optional. Only matches on or before this date. Must be set together with the from date. - Maximum matches (`limit`, number): Optional. How many matches to return, up to 500. football-data.org returns 100 when this is left empty. From 1 to 500. **Outputs** - `count` (number): How many matches this response returned. - `matches` (list): The matching matches, earliest kick-off first. - `result_set` (object): The API's own summary of the match list. **Example output** ```json { "count": 1, "matches": [ { "area": { "code": "ENG", "flag": "https://crests.football-data.org/770.svg", "id": 2072, "name": "England", "parent_area": "Europe", "parent_area_id": 2077 }, "attendance": null, "away_team": { "bench": [], "coach": null, "crest": "https://crests.football-data.org/61.png", "formation": null, "id": 61, "league_rank": null, "lineup": [], "name": "Chelsea FC", "short_name": "Chelsea", "statistics": null, "tla": "CHE" }, "bookings": [], "competition": { "code": "PL", "emblem": "https://crests.football-data.org/PL.png", "id": 2021, "name": "Premier League", "type": "LEAGUE" }, "goals": [], "group": null, "home_team": { "bench": [], "coach": null, "crest": "https://crests.football-data.org/57.png", "formation": null, "id": 57, "league_rank": null, "lineup": [], "name": "Arsenal FC", "short_name": "Arsenal", "statistics": null, "tla": "ARS" }, "id": 544214, "injury_time": null, "last_updated": "2026-02-13T00:20:58Z", "matchday": 24, "minute": null, "odds": null, "penalties": [], "referees": [ { "id": 43888, "name": "Michael Oliver", "nationality": "England", "type": "REFEREE" } ], "score": { "duration": "REGULAR", "extra_time": { "away": null, "home": null }, "full_time": { "away": 1, "home": 2 }, "half_time": { "away": 0, "home": 1 }, "penalties": { "away": null, "home": null }, "regular_time": { "away": null, "home": null }, "winner": "HOME_TEAM" }, "season": { "current_matchday": 24, "end_date": "2026-05-24", "id": 2287, "stages": [ "REGULAR_SEASON" ], "start_date": "2025-08-15", "winner": null }, "stage": "REGULAR_SEASON", "status": "FINISHED", "substitutions": [], "utc_date": "2026-02-08T16:30:00Z", "venue": "Emirates Stadium" } ], "result_set": { "competitions": [ "PL" ], "count": 1, "draws": 0, "first": "2026-02-08", "last": "2026-02-08", "losses": 0, "played": 1, "wins": 1 } } ``` ### List areas List every country, continent and football region football-data.org tracks, each with its id, flag and the area it sits inside. Use an area id to narrow the competition list. Works without an API token. **Inputs**: None. **Outputs** - `areas` (list): Every area, as the API orders them. - `count` (number): How many areas were returned. **Example output** ```json { "areas": [ { "code": "ENG", "flag": "https://crests.football-data.org/770.svg", "id": 2072, "name": "England", "parent_area": "Europe", "parent_area_id": 2077 } ], "count": 1 } ``` ### List competitions List the leagues and cups football-data.org covers, each with its league code, country, current season and which plan it belongs to. Without an API token this lists every competition the site tracks; with one it lists the competitions your plan covers. Works without an API token. **Inputs** - Areas (`areas`, list): Optional. Only competitions in these countries or regions. All areas are included when nothing is chosen. The list offers the areas that have a competition, since filtering by any other returns nothing. **Outputs** - `competitions` (list): The matching competitions. - `count` (number): How many competitions were returned. **Example output** ```json { "competitions": [ { "area": { "code": "ENG", "flag": "https://crests.football-data.org/770.svg", "id": 2072, "name": "England", "parent_area": "Europe", "parent_area_id": 2077 }, "code": "PL", "current_season": { "current_matchday": 24, "end_date": "2026-05-24", "id": 2287, "stages": [ "REGULAR_SEASON" ], "start_date": "2025-08-15", "winner": null }, "emblem": "https://crests.football-data.org/PL.png", "id": 2021, "last_updated": "2026-02-13T00:20:58Z", "name": "Premier League", "number_of_available_seasons": 33, "plan": "TIER_ONE", "type": "LEAGUE" } ], "count": 1 } ``` ### List head-to-head matches List the previous meetings of the two teams in a match, with a summary of how many each side has won, drawn and lost. Needs a free API token. **Inputs** - Match ID (`match_id`, text, required): The match whose two teams to compare, by numeric id. - Competitions (`competitions`, list): Optional. Only matches in these competitions. All of them are included when nothing is chosen. - From date (`date_from`, date): Optional. Only matches on or after this date. Must be set together with the to date. - To date (`date_to`, date): Optional. Only matches on or before this date. Must be set together with the from date. - Maximum meetings (`limit`, number): Optional. How many previous meetings to return, up to 500. football-data.org returns 10 when this is left empty. From 1 to 500. **Outputs** - `aggregates` (object): The record between the two sides across every meeting the API knows about, which can be more than the matches returned here. - `count` (number): How many matches this response returned. - `matches` (list): The matching matches, earliest kick-off first. - `result_set` (object): The API's own summary of the match list. **Example output** ```json { "aggregates": { "away_team": { "draws": 5, "id": 61, "losses": 7, "name": "Chelsea FC", "wins": 3 }, "home_team": { "draws": 5, "id": 57, "losses": 3, "name": "Arsenal FC", "wins": 7 }, "number_of_matches": 15, "total_goals": 41 }, "count": 1, "matches": [ { "area": { "code": "ENG", "flag": "https://crests.football-data.org/770.svg", "id": 2072, "name": "England", "parent_area": "Europe", "parent_area_id": 2077 }, "attendance": null, "away_team": { "bench": [], "coach": null, "crest": "https://crests.football-data.org/61.png", "formation": null, "id": 61, "league_rank": null, "lineup": [], "name": "Chelsea FC", "short_name": "Chelsea", "statistics": null, "tla": "CHE" }, "bookings": [], "competition": { "code": "PL", "emblem": "https://crests.football-data.org/PL.png", "id": 2021, "name": "Premier League", "type": "LEAGUE" }, "goals": [], "group": null, "home_team": { "bench": [], "coach": null, "crest": "https://crests.football-data.org/57.png", "formation": null, "id": 57, "league_rank": null, "lineup": [], "name": "Arsenal FC", "short_name": "Arsenal", "statistics": null, "tla": "ARS" }, "id": 544214, "injury_time": null, "last_updated": "2026-02-13T00:20:58Z", "matchday": 24, "minute": null, "odds": null, "penalties": [], "referees": [ { "id": 43888, "name": "Michael Oliver", "nationality": "England", "type": "REFEREE" } ], "score": { "duration": "REGULAR", "extra_time": { "away": null, "home": null }, "full_time": { "away": 1, "home": 2 }, "half_time": { "away": 0, "home": 1 }, "penalties": { "away": null, "home": null }, "regular_time": { "away": null, "home": null }, "winner": "HOME_TEAM" }, "season": { "current_matchday": 24, "end_date": "2026-05-24", "id": 2287, "stages": [ "REGULAR_SEASON" ], "start_date": "2025-08-15", "winner": null }, "stage": "REGULAR_SEASON", "status": "FINISHED", "substitutions": [], "utc_date": "2026-02-08T16:30:00Z", "venue": "Emirates Stadium" } ], "result_set": { "competitions": [ "PL" ], "count": 1, "draws": null, "first": "2026-02-08", "last": "2026-02-08", "losses": null, "played": null, "wins": null } } ``` ### List matches List matches across competitions: today's fixtures by default, or a chosen day, a date range, a set of competitions, or a specific list of match ids. Needs a free API token. **Inputs** - Competitions (`competitions`, list): Optional. Only matches in these competitions. All of them are included when nothing is chosen. - Match IDs (`ids`, list): Optional. Only these matches, by numeric id. Use it to refresh several matches in one request. - Match status (`status`, list): Optional. Only matches in these states. Choosing none returns every state. Live is a shortcut for in play plus half time. One or more of: `SCHEDULED`, `TIMED`, `IN_PLAY` (In play), `PAUSED` (Paused (half time)), `EXTRA_TIME` (Extra time), `PENALTY_SHOOTOUT` (Penalty shootout), `FINISHED`, `SUSPENDED`, `POSTPONED`, `CANCELLED`, `AWARDED`, `LIVE` (Live (in play or paused)). - On date (`on_date`, date): Optional. Only matches played on this day. - From date (`date_from`, date): Optional. Only matches on or after this date. Must be set together with the to date. - To date (`date_to`, date): Optional. Only matches on or before this date. Must be set together with the from date. **Outputs** - `count` (number): How many matches this response returned. - `matches` (list): The matching matches, earliest kick-off first. - `result_set` (object): The API's own summary of the match list. **Example output** ```json { "count": 1, "matches": [ { "area": { "code": "ENG", "flag": "https://crests.football-data.org/770.svg", "id": 2072, "name": "England", "parent_area": "Europe", "parent_area_id": 2077 }, "attendance": null, "away_team": { "bench": [], "coach": null, "crest": "https://crests.football-data.org/61.png", "formation": null, "id": 61, "league_rank": null, "lineup": [], "name": "Chelsea FC", "short_name": "Chelsea", "statistics": null, "tla": "CHE" }, "bookings": [], "competition": { "code": "PL", "emblem": "https://crests.football-data.org/PL.png", "id": 2021, "name": "Premier League", "type": "LEAGUE" }, "goals": [], "group": null, "home_team": { "bench": [], "coach": null, "crest": "https://crests.football-data.org/57.png", "formation": null, "id": 57, "league_rank": null, "lineup": [], "name": "Arsenal FC", "short_name": "Arsenal", "statistics": null, "tla": "ARS" }, "id": 544214, "injury_time": null, "last_updated": "2026-02-13T00:20:58Z", "matchday": 24, "minute": null, "odds": null, "penalties": [], "referees": [ { "id": 43888, "name": "Michael Oliver", "nationality": "England", "type": "REFEREE" } ], "score": { "duration": "REGULAR", "extra_time": { "away": null, "home": null }, "full_time": { "away": 1, "home": 2 }, "half_time": { "away": 0, "home": 1 }, "penalties": { "away": null, "home": null }, "regular_time": { "away": null, "home": null }, "winner": "HOME_TEAM" }, "season": { "current_matchday": 24, "end_date": "2026-05-24", "id": 2287, "stages": [ "REGULAR_SEASON" ], "start_date": "2025-08-15", "winner": null }, "stage": "REGULAR_SEASON", "status": "FINISHED", "substitutions": [], "utc_date": "2026-02-08T16:30:00Z", "venue": "Emirates Stadium" } ], "result_set": { "competitions": [ "PL" ], "count": 1, "draws": null, "first": "2026-02-08", "last": "2026-02-08", "losses": null, "played": 1, "wins": null } } ``` ### List teams Page through every club in the football-data.org database. This list is the short form, without the area, competitions or squad. Use Get a team for the full record. Needs a free API token. **Inputs** - Teams per page (`limit`, number): Optional. How many teams to return, up to 500. football-data.org returns 50 when this is left empty. From 1 to 500. - Skip (`offset`, number): Optional. Skip this many teams before reading a page, adding the page size each time to walk through them. football-data.org caps this at 500, so this action reaches the first 500 teams plus one page. Use List a competition's teams to reach a particular league's clubs. From 0 to 500. Default: `0`. **Outputs** - `count` (number): How many teams this page returned. - `offset` (number): How many teams were skipped to reach it. - `teams` (list): One page of teams. **Example output** ```json { "count": 1, "offset": 0, "teams": [ { "address": "75 Drayton Park London N5 1BU", "area": null, "club_colors": "Red / White", "coach": null, "contract": null, "crest": "https://crests.football-data.org/57.png", "founded": 1886, "id": 57, "last_updated": "2026-01-08T10:12:33Z", "market_value": null, "name": "Arsenal FC", "running_competitions": [], "short_name": "Arsenal", "squad": [], "staff": [], "tla": "ARS", "type": null, "venue": "Emirates Stadium", "website": "http://www.arsenal.com" } ] } ``` ### List top scorers List a competition's leading scorers with their goals, assists, penalties and matches played, plus the club each plays for. Returns 10 players unless you ask for more. Needs a free API token. **Inputs** - Competition (`competition`, text, required): The competition to read. Pick one from the list, or pass a league code such as PL or a numeric id such as 2021 from an earlier step. - Season (`season`, number): Optional. The four-digit year the season starts in, so 2024 means the 2024/25 season. Defaults to the current season. Past seasons need a paid football-data.org plan. From 1900 to 2100. - Matchday (`matchday`, number): Optional. Only this matchday, counting from 1. From 1 to 99. - Maximum players (`limit`, number): Optional. How many scorers to return, up to 500. football-data.org returns 10 when this is left empty. From 1 to 500. **Outputs** - `competition` (object): The competition this belongs to. - `count` (number): How many scorers were returned. - `scorers` (list): The top scorers, most goals first. - `season` (object): A season of the competition. **Example output** ```json { "competition": { "code": "PL", "emblem": "https://crests.football-data.org/PL.png", "id": 2021, "name": "Premier League", "type": "LEAGUE" }, "count": 1, "scorers": [ { "assists": 9, "goals": 14, "penalties": 2, "played_matches": 24, "player": { "contract": { "start": null, "until": null }, "date_of_birth": "2001-09-05", "first_name": "Bukayo", "id": 3754, "last_name": "Saka", "last_updated": "2026-01-08T10:12:33Z", "market_value": null, "name": "Bukayo Saka", "nationality": "England", "position": "Right Winger", "section": null, "shirt_number": 7 }, "team": { "address": "75 Drayton Park London N5 1BU", "area": { "code": "ENG", "flag": "https://crests.football-data.org/770.svg", "id": 2072, "name": "England", "parent_area": "Europe", "parent_area_id": 2077 }, "club_colors": "Red / White", "coach": { "contract": { "start": null, "until": null }, "date_of_birth": "1982-03-26", "first_name": "Mikel", "id": 11592, "last_name": "Arteta", "last_updated": "2026-01-08T10:12:33Z", "market_value": null, "name": "Mikel Arteta", "nationality": "Spain", "position": null, "section": null, "shirt_number": null }, "contract": null, "crest": "https://crests.football-data.org/57.png", "founded": 1886, "id": 57, "last_updated": "2026-01-08T10:12:33Z", "market_value": null, "name": "Arsenal FC", "running_competitions": [ { "code": "PL", "emblem": "https://crests.football-data.org/PL.png", "id": 2021, "name": "Premier League", "type": "LEAGUE" } ], "short_name": "Arsenal", "squad": [ { "contract": { "start": null, "until": null }, "date_of_birth": "2001-09-05", "first_name": "Bukayo", "id": 3754, "last_name": "Saka", "last_updated": "2026-01-08T10:12:33Z", "market_value": null, "name": "Bukayo Saka", "nationality": "England", "position": "Right Winger", "section": null, "shirt_number": 7 } ], "staff": [], "tla": "ARS", "type": null, "venue": "Emirates Stadium", "website": "http://www.arsenal.com" } } ], "season": { "current_matchday": 24, "end_date": "2026-05-24", "id": 2287, "stages": [ "REGULAR_SEASON" ], "start_date": "2025-08-15", "winner": null } } ```