Overview
On May 20, 2022 I released v4 for public use. I revised the entire reference documentation that you find here.
While v2 will remain available until further notice, I encourage you to migrate to v4. It's really worth it.
Available resources
See all available endpoints underneath. See Filtering table at the very bottom to see how to pass filters in an adequate format.
You can also get an overview by running all available calls through Postman by
importing this collection after download.
(Sub)Resource | Action | URI | Filters | Sample |
---|---|---|---|---|
Area | List one particular area. | /v4/areas/{id} | - |
Open
Areas
Request:
|
Areas | List all available areas. | /v4/areas/ | - |
Open
Areas
Request:
|
Competition | List one particular competition. | /v4/competitions/PL | - |
Open
Competition
Request:
|
Competition | List all available competitions. | /v4/competitions/ | areas={AREAS} |
Open
Competitions
Request:
|
Competition / Standings | Show Standings for a particular competition. | /v4/competitions/{id}/standings | matchday={MATCHDAY} season={YEAR} date={DATE} |
Open
LeagueTable
Request:
|
Competition / Match | List all matches for a particular competition. | /v4/competitions/{id}/matches | dateFrom={DATE} dateTo={DATE} stage={STAGE} status={STATUS} matchday={MATCHDAY} group={GROUP} season={YEAR} |
Open
Matches for a particular competition
Request:
|
Competition / Teams | List all teams for a particular competition. | /v4/competitions/{id}/teams | season={YEAR} |
Open
Teams for a particular competition
Request:
|
Competition / (Top)Scorers | List top scorers for a particular competition. | /v4/competitions/{id}/scorers | limit={LIMIT} season={YEAR} |
Open
Scorers for a particular competition
Request:
|
Team | Show one particular team. | /v4/teams/{id} | - |
Open
Team
Request:
|
Team | List teams. | /v4/teams/ | limit={LIMIT} offset={OFFSET} |
Open
Team
Request:
|
Match | Show all matches for a particular team. | /v4/teams/{id}/matches/ | dateFrom={DATE} dateTo={DATE} season={YEAR} competitions={competitionIds} status={STATUS} venue={VENUE} limit={LIMIT} |
Open
Matches for a particular team
Request:
|
Person | List one particular person. | /v4/persons/{id} | - |
Open
Players
Request:
|
Person / Match | Show all matches for a particular person. | /v4/persons/{id}/matches | dateFrom={DATE} dateTo={DATE} status={STATUS} competitions={competitionIds} limit={LIMIT} offset={OFFSET} |
Open
Players
Request:
|
Match | Show one particular match. | /v4/matches/{id} |
Open
Match
Request:
|
|
Match | List matches across (a set of) competitions. | /v4/matches | competitions={competitionIds} ids={matchIds} dateFrom={DATE} dateTo={DATE} status={STATUS} |
Open
Matches across (a set of) competitions
Request:
|
Match / Head2Head | List previous encounters for the teams of a match. | /v4/matches/{id}/head2head | limit={LIMIT} dateFrom={DATE} dateTo={DATE} competitions={competitionIds} |
Open
Matches between two teams of a match
Request:
|
Filters and their data types
Filter | Type | Description / Possible values |
---|---|---|
id | Integer /[0-9]+/ | The id of a resource. |
ids | Integer /[0-9]+/ | Comma separated list of ids. |
matchday | Integer /[1-4]+[0-9]*/ | |
season | String /yyyy/ | The starting year of a season e.g. 2017 or 2016 |
status | Enum /[A-Z]+/ | The status of a match. [SCHEDULED | LIVE | IN_PLAY | PAUSED | FINISHED | POSTPONED | SUSPENDED | CANCELLED] |
venue | Enum /[A-Z]+/ | Defines the venue (type). [HOME | AWAY] |
date / dateFrom / dateTo | String /yyyy-MM-dd/ | e.g. 2018-06-22 |
stage | Enum /[A-Z]+/ | FINAL | THIRD_PLACE | SEMI_FINALS | QUARTER_FINALS | LAST_16 | LAST_32 | LAST_64 | ROUND_4 | ROUND_3 | ROUND_2 | ROUND_1 | GROUP_STAGE | PRELIMINARY_ROUND | QUALIFICATION | QUALIFICATION_ROUND_1 | QUALIFICATION_ROUND_2 | QUALIFICATION_ROUND_3 | PLAYOFF_ROUND_1 | PLAYOFF_ROUND_2 | PLAYOFFS | REGULAR_SEASON | CLAUSURA | APERTURA | CHAMPIONSHIP | RELEGATION | RELEGATION_ROUND |
plan | String /[A-Z]+/ | TIER_ONE | TIER_TWO | TIER_THREE | TIER_FOUR |
competitions | String /\d+,\d+/ | Comma separated list of competition ids. |
areas | String /\d+,\d+/ | Comma separated list of area ids. |
group | String /[A-Z_]+/ | Allows filtering for groupings in a competition. |
limit | Integer /\d+/ | Limits your result set to the given number. Defaults to 10. |
offset | Integer /\d+/ | Skip offset no. of records when using a limit to page the result list. |
Example Requests
See todays' matches of your subscribed competitions:
https://api.football-data.org/v4/matches
Get all matches of the Champions League:
https://api.football-data.org/v4/competitions/CL/matches
See all upcoming matches for Real Madrid:
https://api.football-data.org/v4/teams/86/matches?status=SCHEDULED
Get all matches where Gigi Buffon was in the squad:
https://api.football-data.org/v4/persons/2019/matches?status=FINISHED
Check schedules for Premier League on matchday 11:
https://api.football-data.org/v4/competitions/PL/matches?matchday=11
Get the league table for Eredivisie:
https://api.football-data.org/v4/competitions/DED/standings
See best 10 scorers of Italy's top league (scorers subresource defaults to limit=10):
https://api.football-data.org/v4/competitions/SA/scorers