football-data.org
App · Sports · 16 actions
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.
Actions
| Action | What it does |
|---|---|
| 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. |
| 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. |
| 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. |
| 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. |
| Get an area | Look up one country, continent or football region by id, along with the areas nested inside it. |
| 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. |
| List a competition's matches | List the fixtures and results of one league or cup, filtered by matchday, stage, group, status or date range. |
| List a competition's teams | List every club playing in a competition's season, each with its ground, colours, founding year and squad. |
| 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. |
| 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. |
| List areas | List every country, continent and football region football-data.org tracks, each with its id, flag and the area it sits inside. |
| 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. |
| 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. |
| 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. |
| List teams | Page through every club in the football-data.org database. |
| List top scorers | List a competition's leading scorers with their goals, assists, penalties and matches played, plus the club each plays for. |
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
competitiontextRequired - 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
areaobject- The country or region this belongs to.
codetext- Short league code, e.g. PL. Usable anywhere an id is. Null for a few competitions.
current_seasonobject- A season of the competition.
emblemtext- Competition emblem image URL.
idnumber- The competition's numeric id.
last_updatedtext- When this record last changed, ISO 8601 in UTC.
nametext- Competition name, e.g. Premier League.
number_of_available_seasonsnumber- Null here: the API only reports it on the competition list. Count the seasons instead.
plantext- Null here: the API only reports the plan on the competition list.
seasonslist- Every season on file, most recent first.
typetext- One of LEAGUE, LEAGUE_CUP, CUP or PLAYOFFS.
Example output
{
"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_idtextRequired - The match's numeric id, for example 544214. Any of the match lists returns these ids.
- Include lineups and events
include_detailstrue/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
areaobject- The country or region this belongs to.
attendancenumber- Crowd size, where known.
away_teamobject- 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.
bookingslist- Cards shown, where the match was read with events included.
competitionobject- The competition this belongs to.
goalslist- Every goal, in order. Only filled in when the match is read with lineups and events included.
grouptext- Group, e.g. GROUP_A. Null outside a group stage.
home_teamobject- 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.
idnumber- The match id. Use with Get a match.
injury_timenumber- Added minutes, where known.
last_updatedtext- When this match last changed, ISO 8601 in UTC.
matchdaynumber- Matchday number.
minutenumber- Minute played, while in progress.
oddsobject- Betting odds. Null unless the connected token has the paid odds package.
penaltieslist- Penalties, including shootout kicks.
refereeslist- The match officials.
scoreobject- How the match stood, or finished.
seasonobject- A season of the competition.
stagetext- Stage, e.g. REGULAR_SEASON, GROUP_STAGE or SEMI_FINALS.
statustext- SCHEDULED, TIMED, IN_PLAY, PAUSED, EXTRA_TIME, PENALTY_SHOOTOUT, FINISHED, SUSPENDED, POSTPONED, CANCELLED or AWARDED.
substitutionslist- Substitutions, where the match was read with events included.
utc_datetext- Kick-off time, ISO 8601 in UTC.
venuetext- The ground the match is played at.
Example output
{
"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_idtextRequired - The person's numeric id, for example 3754. A team's squad and a competition's scorers both carry these ids.
Outputs
contractobject- Contract dates as year-month, e.g. 2024-07. Only on paid plans; both ends are null otherwise.
current_teamobject- The club the person is at now, with their contract there where the plan includes it.
date_of_birthtext- Date of birth, yyyy-MM-dd.
first_nametext- First name.
idnumber- The person's id. Use with Get a person.
last_nametext- Last name.
last_updatedtext- When this record last changed, ISO 8601 in UTC.
market_valuenumber- Estimated market value in euros. Paid plans only.
nametext- Full name.
nationalitytext- Nationality, e.g. Germany.
positiontext- 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.
sectiontext- Broad grouping, e.g. Offence. Not always present.
shirt_numbernumber- Squad number, where known.
Example output
{
"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_idtextRequired - The club's numeric id, for example 57 for Arsenal. List a competition's teams to find one.
Outputs
addresstext- The club's postal address.
areaobject- The country or region this belongs to.
club_colorstext- Club colours, e.g. Red / White.
coachobject- A player, coach or member of staff.
contractobject- Contract dates as year-month, e.g. 2024-07. Only on paid plans; both ends are null otherwise.
cresttext- Club crest image URL.
foundednumber- Year the club was founded.
idnumber- The team's id. Use it with Get a team.
last_updatedtext- When this record last changed, ISO 8601 in UTC.
market_valuenumber- Squad market value in euros. Paid plans only.
nametext- Full club name, e.g. Arsenal FC.
running_competitionslist- The competitions this team is currently playing in.
short_nametext- Shorter name, e.g. Arsenal.
squadlist- People, each with their position and nationality.
stafflist- Backroom staff. Empty on the free plan.
tlatext- Three-letter abbreviation, e.g. ARS.
typetext- MEN_CLUB, MEN_NATIONAL, WOMEN_CLUB or WOMEN_NATIONAL, where the API reports it.
venuetext- Home ground name.
websitetext- The club's website.
Example output
{
"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_idtextRequired - The area's numeric id, for example 2072 for England or 2077 for Europe. List areas to find one.
Outputs
child_areaslist- The areas that sit inside this one.
codetext- Three-letter area code, e.g. ENG. Null for some regions.
flagtext- Flag image URL. Null if there is none.
idnumber- The area's id.
nametext- Area name, e.g. England.
parent_areatext- Name of the area this one sits inside, e.g. Europe.
parent_area_idnumber- Id of the area this one sits inside.
Example output
{
"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
competitiontextRequired - 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
seasonnumber - 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
matchdaynumber - 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_datedate - Optional. The table as it stood on this date, for example who led at new year.
Outputs
areaobject- The country or region this belongs to.
competitionobject- The competition this belongs to.
countnumber- How many tables were returned.
seasonobject- A season of the competition.
standingslist- 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
{
"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
competitiontextRequired - 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
seasonnumber - 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
matchdaynumber - Optional. Only this matchday, counting from 1.From 1 to 99.
- Match status
statuslist - 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
stagetext - 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
grouptext - 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_fromdate - Optional. Only matches on or after this date. Must be set together with the to date.
- To date
date_todate - Optional. Only matches on or before this date. Must be set together with the from date.
Outputs
competitionobject- The competition this belongs to.
countnumber- How many matches this response returned.
matcheslist- The matching matches, earliest kick-off first.
result_setobject- The API's own summary of the match list.
Example output
{
"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
competitiontextRequired - 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
seasonnumber - 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
competitionobject- The competition this belongs to.
countnumber- How many teams were returned.
seasonobject- A season of the competition.
teamslist- The teams taking part.
Example output
{
"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_idtextRequired - The person's numeric id, for example 3754.
- Match status
statuslist - 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
competitionslist - Optional. Only matches in these competitions. All of them are included when nothing is chosen.
- Started or benched
lineuptext - Optional. Only matches the player started, or only those they began on the bench.One of:
STARTING(Starting XI),BENCH. - Player event
eventtext - 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_fromdate - Optional. Only matches on or after this date. Must be set together with the to date.
- To date
date_todate - Optional. Only matches on or before this date. Must be set together with the from date.
- Maximum matches
limitnumber - Optional. How many matches to return, up to 100.From 1 to 100.
- Skip
offsetnumber - Optional. Skip this many matches before reading a page.From 0 to 100. Default:
0.
Outputs
aggregationsobject- The player's totals across the matched matches. Null on the free plan, which does not compute them.
countnumber- How many matches this response returned.
matcheslist- The matching matches, earliest kick-off first.
personobject- A player, coach or member of staff.
result_setobject- The API's own summary of the match list.
Example output
{
"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_idtextRequired - The club's numeric id, for example 57 for Arsenal.
- Season
seasonnumber - 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
statuslist - 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
venuetext - Optional. Only the club's home matches, or only its away matches. Both are included when nothing is chosen.One of:
HOME,AWAY. - Competitions
competitionslist - Optional. Only matches in these competitions. All of them are included when nothing is chosen.
- From date
date_fromdate - Optional. Only matches on or after this date. Must be set together with the to date.
- To date
date_todate - Optional. Only matches on or before this date. Must be set together with the from date.
- Maximum matches
limitnumber - Optional. How many matches to return, up to 500. football-data.org returns 100 when this is left empty.From 1 to 500.
Outputs
countnumber- How many matches this response returned.
matcheslist- The matching matches, earliest kick-off first.
result_setobject- The API's own summary of the match list.
Example output
{
"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
areaslist- Every area, as the API orders them.
countnumber- How many areas were returned.
Example output
{
"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
areaslist - 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
competitionslist- The matching competitions.
countnumber- How many competitions were returned.
Example output
{
"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_idtextRequired - The match whose two teams to compare, by numeric id.
- Competitions
competitionslist - Optional. Only matches in these competitions. All of them are included when nothing is chosen.
- From date
date_fromdate - Optional. Only matches on or after this date. Must be set together with the to date.
- To date
date_todate - Optional. Only matches on or before this date. Must be set together with the from date.
- Maximum meetings
limitnumber - 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
aggregatesobject- The record between the two sides across every meeting the API knows about, which can be more than the matches returned here.
countnumber- How many matches this response returned.
matcheslist- The matching matches, earliest kick-off first.
result_setobject- The API's own summary of the match list.
Example output
{
"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
competitionslist - Optional. Only matches in these competitions. All of them are included when nothing is chosen.
- Match IDs
idslist - Optional. Only these matches, by numeric id. Use it to refresh several matches in one request.
- Match status
statuslist - 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_datedate - Optional. Only matches played on this day.
- From date
date_fromdate - Optional. Only matches on or after this date. Must be set together with the to date.
- To date
date_todate - Optional. Only matches on or before this date. Must be set together with the from date.
Outputs
countnumber- How many matches this response returned.
matcheslist- The matching matches, earliest kick-off first.
result_setobject- The API's own summary of the match list.
Example output
{
"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
limitnumber - Optional. How many teams to return, up to 500. football-data.org returns 50 when this is left empty.From 1 to 500.
- Skip
offsetnumber - 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
countnumber- How many teams this page returned.
offsetnumber- How many teams were skipped to reach it.
teamslist- One page of teams.
Example output
{
"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
competitiontextRequired - 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
seasonnumber - 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
matchdaynumber - Optional. Only this matchday, counting from 1.From 1 to 99.
- Maximum players
limitnumber - Optional. How many scorers to return, up to 500. football-data.org returns 10 when this is left empty.From 1 to 500.
Outputs
competitionobject- The competition this belongs to.
countnumber- How many scorers were returned.
scorerslist- The top scorers, most goals first.
seasonobject- A season of the competition.
Example output
{
"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
}
}