Documentation
Alpha Release (opens in new window/tab) deprecated.
v1 Release (opens in new window/tab) new!
Quickstart-Information
Available Resources
(Sub)Resource Action URI Filters Sample
Competition List all available competitions. /v1/competitions/ season=/\d\d\d\d/
Request:curl -H 'X-Response-Control: minified' -X GET http://api.football-data.org/v1/competitions/?season=2015
(Abbreviated) Response:HTTP/1.1 200 OK
Content-Type application/json;charset=UTF-8
X-Response-Control: minified
... 
[
    {
        "id": 394,
        "caption": "1. Bundesliga 2015/16",
        "league": "BL1",
        "year": "2015",
        "numberOfTeams": 18,
        "numberOfGames": 306,
        "lastUpdated": "2015-10-25T19:06:29Z"
    },
    {
        "id": 395,
        "caption": "2. Bundesliga 2015/16",
        "league": "BL2",
        "year": "2015",
        "numberOfTeams": 18,
        "numberOfGames": 306,
        "lastUpdated": "2015-10-25T19:06:59Z"
    },
    {
        "id": 396,
        "caption": "Ligue 1 2015/16",
        "league": "FL1",
        "year": "2015",
        "numberOfTeams": 20,
        "numberOfGames": 380,
        "lastUpdated": "2015-10-26T07:40:20Z"
    },
    {
        "id": 397,
        "caption": "Ligue 2 2015/16",
        "league": "FL2",
        "year": "2015",
        "numberOfTeams": 20,
        "numberOfGames": 380,
        "lastUpdated": "2015-10-27T08:15:17Z"
    },
    {
        "id": 398,
        "caption": "Premier League 2015/16",
        "league": "PL",
        "year": "2015",
        "numberOfTeams": 20,
        "numberOfGames": 380,
        "lastUpdated": "2015-10-25T19:08:18Z"
    },
    {
        "id": 399,
        "caption": "Primera Division 2015/16",
        "league": "PD",
        "year": "2015",
        "numberOfTeams": 20,
        "numberOfGames": 380,
        "lastUpdated": "2015-10-27T08:14:21Z"
    },
    {
        "id": 400,
        "caption": "Segunda Division 2015/16",
        "league": "SD",
        "year": "2015",
        "numberOfTeams": 22,
        "numberOfGames": 462,
        "lastUpdated": "2015-10-26T07:40:01Z"
    },
    {
        "id": 401,
        "caption": "Serie A 2015/16",
        "league": "SA",
        "year": "2015",
        "numberOfTeams": 20,
        "numberOfGames": 380,
        "lastUpdated": "2015-10-30T07:08:40Z"
    },
    {
        "id": 402,
        "caption": "Primeira Liga 2015/16",
        "league": "PPL",
        "year": "2015",
        "numberOfTeams": 18,
        "numberOfGames": 306,
        "lastUpdated": "2015-10-27T08:14:41Z"
    },
    {
        "id": 403,
        "caption": "3. Bundesliga 2015/16",
        "league": "BL3",
        "year": "2015",
        "numberOfTeams": 20,
        "numberOfGames": 380,
        "lastUpdated": "2015-10-25T19:07:17Z"
    },
    {
        "id": 404,
        "caption": "Eredivisie 2015/16",
        "league": "DED",
        "year": "2015",
        "numberOfTeams": 18,
        "numberOfGames": 306,
        "lastUpdated": "2015-10-25T19:12:52Z"
    },
    {
        "id": 405,
        "caption": "Champions League 2015/16",
        "league": "CL",
        "year": "2015",
        "numberOfTeams": 32,
        "numberOfGames": 96,
        "lastUpdated": "2015-10-21T21:01:58Z"
    }
]
Team List all teams for a certain competition. /v1/competitions/{id}/teams -
Request:curl -H 'X-Response-Control: minified' -X GET http://api.football-data.org/v1/competitions/398/teams
(Abbreviated) Response:HTTP/1.1 200 OK
Content-Type application/json;charset=UTF-8
X-Response-Control: minified
... 
{
    "count": 20,
    "teams":
    [
        {
            "id": 66,
            "name": "Manchester United FC",
            "shortName": "ManU",
            "squadMarketValue": "377,250,000 €",
            "crestUrl": "http://upload.wikimedia.org/wikipedia/de/d/da/Manchester_United_FC.svg"
        },
        {
            "id": 73,
            "name": "Tottenham Hotspur FC",
            "shortName": "Spurs",
            "squadMarketValue": "288,000,000 €",
            "crestUrl": "http://upload.wikimedia.org/wikipedia/de/b/b4/Tottenham_Hotspur.svg"
        },
        {
    { ... },
    { ... }
}
LeagueTable Show League Table / current standing. /v1/competitions/{id}/leagueTable matchday=/\d+/
Request:curl -H 'X-Response-Control: minified' -X GET http://api.football-data.org/v1/competitions/398/leagueTable
(Abbreviated) Response:HTTP/1.1 200 OK
Content-Type application/json;charset=UTF-8
X-Response-Control: minified
...
{
    "leagueCaption": "Premier League 2015/16",
    "matchday": 10,
    "standing":
    [
        {
            "rank": 1,
            "team": "ManCity",
            "teamId": 65,
            "playedGames": 10,
            "crestURI": "http://upload.wikimedia.org/wikipedia/de/f/fd/ManCity.svg",
            "points": 22,
            "goals": 24,
            "goalsAgainst": 8,
            "goalDifference": 16
        },
        {
            "rank": 2,
            "team": "Arsenal",
            "teamId": 57,
            "playedGames": 10,
            "crestURI": "http://upload.wikimedia.org/wikipedia/en/5/53/Arsenal_FC.svg",
            "points": 22,
            "goals": 18,
            "goalsAgainst": 8,
            "goalDifference": 10
        },
        {
            "rank": 3,
            "team": "West Ham",
            "teamId": 563,
            "playedGames": 10,
            "crestURI": "http://upload.wikimedia.org/wikipedia/de/e/e0/West_Ham_United_FC.svg",
            "points": 20,
            "goals": 22,
            "goalsAgainst": 13,
            "goalDifference": 9
        },
        {
            "rank": 4,
            "team": "ManU",
            "teamId": 66,
            "playedGames": 10,
            "crestURI": "http://upload.wikimedia.org/wikipedia/de/d/da/Manchester_United_FC.svg",
            "points": 20,
            "goals": 15,
            "goalsAgainst": 8,
            "goalDifference": 7
        },
        { ... },
        { ... },
}
Fixture List all fixtures for a certain competition. /v1/competitions/{id}/fixtures timeFrame=/p|n[1-9]{1,2}/
matchday=/\d+/
Request:curl -H 'X-Response-Control: minified' -X GET http://api.football-data.org/v1/competitions/398/fixtures?matchday=8
(Abbreviated) Response:HTTP/1.1 200 OK
Content-Type application/json;charset=UTF-8
X-Response-Control: minified
...
{
    "count": 10,
    "fixtures":
    [
        {
            "id": 147011,
            "competitionId": 398,
            "date": "2015-10-03T11:45:00Z",
            "matchday": 8,
            "homeTeamName": "Crystal Palace FC",
            "homeTeamId": 354,
            "awayTeamName": "West Bromwich Albion FC",
            "awayTeamId": 74,
            "result":
            {
                "goalsHomeTeam": 2,
                "goalsAwayTeam": 0
            }
        },
        {
            "id": 147013,
            "competitionId": 398,
            "date": "2015-10-03T14:00:00Z",
            "matchday": 8,
            "homeTeamName": "Manchester City FC",
            "homeTeamId": 65,
            "awayTeamName": "Newcastle United FC",
            "awayTeamId": 67,
            "result":
            {
                "goalsHomeTeam": 6,
                "goalsAwayTeam": 1
            }
        },
        {
            "id": 147110,
            "competitionId": 398,
            "date": "2015-10-03T14:00:00Z",
            "matchday": 8,
            "homeTeamName": "AFC Bournemouth",
            "homeTeamId": 1044,
            "awayTeamName": "Watford FC",
            "awayTeamId": 346,
            "result":
            {
                "goalsHomeTeam": 1,
                "goalsAwayTeam": 1
            }
        },
        {
            "id": 147014,
            "competitionId": 398,
            "date": "2015-10-03T14:00:00Z",
            "matchday": 8,
            "homeTeamName": "Norwich City FC",
            "homeTeamId": 68,
            "awayTeamName": "Leicester City FC",
            "awayTeamId": 338,
            "result":
            {
                "goalsHomeTeam": 1,
                "goalsAwayTeam": 2
            }
        },
        { ... },
        { ... }
    ]
}
Fixture List fixtures across a set of competitions. /v1/fixtures/ timeFrame=/p|n[1-9]{1,2}/
league=leagueCode
Request:curl -H 'X-Response-Control: minified' -X GET http://api.football-data.org/v1/fixtures/
(Abbreviated) Response:HTTP/1.1 200 OK
Content-Type application/json;charset=UTF-8
X-Response-Control: minified
...
{
    "timeFrameStart": "2015-10-30",
    "timeFrameEnd": "2015-11-05",
    "count": 124,
    "fixtures":
    [
        {
            "id": 145863,
            "competitionId": 395,
            "date": "2015-10-30T17:30:00Z",
            "matchday": 13,
            "homeTeamName": "Fortuna Düsseldorf",
            "homeTeamId": 24,
            "awayTeamName": "SpVgg Greuther Fürth",
            "awayTeamId": 21,
            "result":
            {
                "goalsHomeTeam": null,
                "goalsAwayTeam": null
            }
        },
        {
            "id": 145862,
            "competitionId": 395,
            "date": "2015-10-30T17:30:00Z",
            "matchday": 13,
            "homeTeamName": "VfL Bochum",
            "homeTeamId": 36,
            "awayTeamName": "FC St. Pauli",
            "awayTeamId": 20,
            "result":
            {
                "goalsHomeTeam": null,
                "goalsAwayTeam": null
            }
        },
        { ... }
}
Fixture Show one fixture. /v1/fixtures/{id} head2head=/\d+/
Request:curl -H 'X-Response-Control: minified' -X GET http://api.football-data.org/v1/fixtures/149461
(Abbreviated) Response:HTTP/1.1 200 OK
Content-Type application/json;charset=UTF-8
X-Response-Control: minified
...
{
    {
        "fixture":
        {
            "id": 149461,
            "competitionId": 406,
            "date": "2014-07-08T20:00:00Z",
            "matchday": 6,
            "homeTeamName": "Brazil",
            "homeTeamId": 764,
            "awayTeamName": "Germany",
            "awayTeamId": 759,
            "result":
            {
                "goalsHomeTeam": 1,
                "goalsAwayTeam": 7
            }
        },
        "head2head":
        {
            "count": 2,
            "timeFrameStart": "2002-06-30",
            "timeFrameEnd": "2014-07-08",
            "homeTeamWins": 1,
            "awayTeamWins": 1,
            "draws": 0,
            "lastHomeWinHomeTeam": null,
            "lastWinHomeTeam":
            {
                "id": 141629,
                "competitionId": 367,
                "date": "2002-06-29T22:00:00Z",
                "matchday": 8,
                "homeTeamName": "Germany",
                "homeTeamId": 759,
                "awayTeamName": "Brazil",
                "awayTeamId": 764,
                "result":
                {
                    "goalsHomeTeam": 0,
                    "goalsAwayTeam": 2
                }
            },
            "lastAwayWinAwayTeam":
            {
                "id": 149461,
                "competitionId": 406,
                "date": "2014-07-08T20:00:00Z",
                "matchday": 6,
                "homeTeamName": "Brazil",
                "homeTeamId": 764,
                "awayTeamName": "Germany",
                "awayTeamId": 759,
                "result":
                {
                    "goalsHomeTeam": 1,
                    "goalsAwayTeam": 7
                }
            },
            "lastWinAwayTeam":
            {
                "id": 149461,
                "competitionId": 406,
                "date": "2014-07-08T20:00:00Z",
                "matchday": 6,
                "homeTeamName": "Brazil",
                "homeTeamId": 764,
                "awayTeamName": "Germany",
                "awayTeamId": 759,
                "result":
                {
                    "goalsHomeTeam": 1,
                    "goalsAwayTeam": 7
                }
            },
            "fixtures":
            [
                {
                    "id": 149461,
                    "competitionId": 406,
                    "date": "2014-07-08T20:00:00Z",
                    "matchday": 6,
                    "homeTeamName": "Brazil",
                    "homeTeamId": 764,
                    "awayTeamName": "Germany",
                    "awayTeamId": 759,
                    "result":
                    {
                        "goalsHomeTeam": 1,
                        "goalsAwayTeam": 7
                    }
                },
                {
                    "id": 141629,
                    "competitionId": 367,
                    "date": "2002-06-29T22:00:00Z",
                    "matchday": 8,
                    "homeTeamName": "Germany",
                    "homeTeamId": 759,
                    "awayTeamName": "Brazil",
                    "awayTeamId": 764,
                    "result":
                    {
                        "goalsHomeTeam": 0,
                        "goalsAwayTeam": 2
                    }
                }
            ]
        }
    }
}
Fixture Show all fixtures for a certain team. /v1/teams/{id}/fixtures/ season=/\d\d\d\d/
timeFrame=/p|n[1-9]{1,2}/
venue=/home|away/
Request:curl -H 'X-Response-Control: minified' -X GET http://api.football-data.org/v1/teams/66/fixtures?timeFrame=n14&venue=home
(Abbreviated) Response:HTTP/1.1 200 OK
Content-Type application/json;charset=UTF-8
X-Response-Control: minified
...
{
    "timeFrameStart": "2015-10-30",
    "timeFrameEnd": "2015-11-12",
    "count": 2,
    "fixtures":
    [
        {
            "id": 149348,
            "competitionId": 405,
            "date": "2015-11-03T19:45:00Z",
            "matchday": 4,
            "homeTeamName": "Manchester United FC",
            "homeTeamId": 66,
            "awayTeamName": "CSKA Moscow",
            "awayTeamId": 751,
            "result":
            {
                "goalsHomeTeam": null,
                "goalsAwayTeam": null
            }
        },
        {
            "id": 146976,
            "competitionId": 398,
            "date": "2015-11-07T15:00:00Z",
            "matchday": 12,
            "homeTeamName": "Manchester United FC",
            "homeTeamId": 66,
            "awayTeamName": "West Bromwich Albion FC",
            "awayTeamId": 74,
            "result":
            {
                "goalsHomeTeam": null,
                "goalsAwayTeam": null
            }
        }
    ]
}
Team Show one team. /v1/teams/{id} -
Request:curl -X GET http://api.football-data.org/v1/teams/66
(Abbreviated) Response:HTTP/1.1 200 OK
Content-Type application/json;charset=UTF-8
X-Response-Control: full
...
{ "_links": {
      "self": { "href": "http://api.football-data.org/v1/teams/66" },
      "fixtures": { "href": "http://api.football-data.org/v1/teams/66/fixtures" },
      "players": { "href": "http://api.football-data.org/v1/teams/66/players" }
    },
    "name": "Manchester United FC",
    "shortName": "ManU",
    "squadMarketValue": "377,250,000 €",
    "crestUrl": "http://upload.wikimedia.org/wikipedia/de/d/da/Manchester_United_FC.svg"
}
Player Show all players for a certain team. /v1/teams/{id}/players -
Request:curl -H "X-Response-Control: minified" -X GET http://api.football-data.org/v1/teams/66/players
(Abbreviated) Response:HTTP/1.1 200 OK
Content-Type application/json;charset=UTF-8
X-Response-Control: minified
...
{
    "count": 25,
    "players":
    [
        {
            "id": 16,
            "name": "Bastian Schweinsteiger",
            "position": "Central Midfield",
            "jerseyNumber": 31,
            "dateOfBirth": "1984-08-01",
            "nationality": "Germany",
            "contractUntil": "2018-06-30",
            "marketValue": "22,000,000 €"
        },
        {
            "id": 409,
            "name": "David de Gea",
            "position": "Keeper",
            "jerseyNumber": 1,
            "dateOfBirth": "1990-11-07",
            "nationality": "Spain",
            "contractUntil": "2016-06-30",
            "marketValue": "30,000,000 €"
        },
        {
            "id": 412,
            "name": "Phil Jones",
            "position": "Centre Back",
            "jerseyNumber": 4,
            "dateOfBirth": "1992-02-21",
            "nationality": "England",
            "contractUntil": "2019-06-30",
            "marketValue": "15,000,000 €"
        },
        {
            "id": 413,
            "name": "Marcos Rojo",
            "position": "Centre Back",
            "jerseyNumber": 5,
            "dateOfBirth": "1990-03-20",
            "nationality": "Argentina",
            "contractUntil": "2019-06-30",
            "marketValue": "18,000,000 €"
        },
        {
            "id": 414,
            "name": "Chris Smalling",
            "position": "Centre Back",
            "jerseyNumber": 12,
            "dateOfBirth": "1989-11-22",
            "nationality": "England",
            "contractUntil": "2019-06-30",
            "marketValue": "14,000,000 €"
        },
        {
            "id": 417,
            "name": "Patrick McNair",
            "position": "Centre Back",
            "jerseyNumber": 33,
            "dateOfBirth": "1995-04-27",
            "nationality": "Northern Ireland",
            "contractUntil": "2017-06-30",
            "marketValue": "4,500,000 €"
        },
        {
            "id": 418,
            "name": "Luke Shaw",
            "position": "Left-Back",
            "jerseyNumber": 23,
            "dateOfBirth": "1995-07-12",
            "nationality": "England",
            "contractUntil": "2018-06-30",
            "marketValue": "21,000,000 €"
        },
        { ... }
}
Filters and their data types.
Filter Type Description
idInteger /[0-9]+/The id of a resource.
matchdayInteger /[1-4]*[0-9]*/For the leageTable subresource, the matchday defaults to the current matchday. For former seasons the last matchday is taken. For the fixture resource, it's unset.
seasonString /\d\d\d\d/Defaults to the current year, given as 4 digit like '2015'.
head2headInteger /[0-9]+/Define the the number of former games to be analyzed in the head2head node. Defaults to 10.
venueString /away|home/Defines the venue of a fixture. Default is unset and means to return all fixtures.
league(comma separated) String /[\w\d]{2,4}(,[\w\d]{2,4})*/ A (list of, comma separated) league-code(s). Default is unset and means all available. See the competition list resource for currently available leagues or the appendix of the full documentation for a table of all league codes
timeFrameself-defined
p|n[1-9]{1,2}
The value of the timeFrame argument must start with either p(ast) or n(ext), representing a timeframe either in the past or future. It is followed by a number in the range 1..99. It defaults to n7 in the fixture resource and is unset for fixture as a subresource.
For instance: p6 would return all fixtures in the last 6 days, whereas n23 would result in returning all fixtures in the next 23 days.
Request- and Response-Headers.
Type Header-Name Value/Description
RequestX-Auth-Token: /[a-z1-9]+/Your authentication token.
RequestX-Response-Control: /full|minified|compressed/Control the appearance of the response. Default is 'full', give it a 'minified' and the response will lack some (meta) information and thus be much smaller. However, 'compressed' is only supported by the fixture resource.
ResponseX-API-VersionIndicates the API version you are using /alpha|v1/.
ResponseX-Response-ControlIndicates the supplied response format-specification /full|minified|compressed/.
ResponseX-Authenticated-ClientIndicates the recognized user /your_registered_name|anonymous/.
ResponseX-RequestCounter-ResetDefines the seconds left to reset your request counter.
ResponseX-Requests-AvailableIndicates the requests left.