footballdata-api-v2

Football Data API

Usage no npm install needed!

<script type="module">
  import footballdataApiV2 from 'https://cdn.skypack.dev/footballdata-api-v2';
</script>

README

Football Data API

npm (scoped) NPM

npm badge

Installation

$ npm install footballdata-api-v2

Get the API key (free) from football data

Import

import FootballData from 'footballdata-api-v2';
const footballData = new FootballData(YOUR_API_KEY);

Usages

See football data quickstart for more information about filters and data types

Get header data

You can attach additional data from the API header response by adding true in the second argument in every methods below to get some meta info like remaining requests until blocked

The free plan allows 10 API calls/minute

footballData.getCompetitions({
    areas: 2088, // Germany
    plan: 'TIER_TWO',
}, true).then((data) => {
    console.log(JSON.stringify(data, null, 4));
})
Result
{
    ...
    "api": {
        "version": "v2",
        "client": "NearHuscarl",
        "secLeftUntilReset": 60,
        "remainingRequests": 9
    }
}

Get all competitions

footballData.getCompetitions({
    areas: 2088, // Germany
    plan: 'TIER_TWO',
}).then((data) => {
    console.log(JSON.stringify(data, null, 4));
})
Result
{
    "count": 3,
    "filters": {
        "areas": [
            2088
        ],
        "plan": "TIER_TWO"
    },
    "competitions": [
        {
            "id": 2002,
            "area": {
                "id": 2088,
                "name": "Germany"
            },
            "name": "Bundesliga",
            "code": "BL1",
            "emblemUrl": null,
            "plan": "TIER_ONE",
            "currentSeason": {
                "id": 155,
                "startDate": "2018-08-24",
                "endDate": "2019-05-18",
                "currentMatchday": 28,
                "winner": null
            },
            "numberOfAvailableSeasons": 23,
            "lastUpdated": "2019-04-06T00:00:38Z"
        },
        {
            "id": 2011,
            "area": {
                "id": 2088,
                "name": "Germany"
            },
            "name": "DFB-Pokal",
            "code": "DFB",
            "emblemUrl": null,
            "plan": "TIER_TWO",
            "currentSeason": {
                "id": 12,
                "startDate": "2018-08-17",
                "endDate": "2019-05-25",
                "currentMatchday": null,
                "winner": null
            },
            "numberOfAvailableSeasons": 2,
            "lastUpdated": "2019-04-03T23:46:40Z"
        },
        ...
    ]
}

Get specific competition

footballData.getCompetition({
    id: 2021, // Premier League
}).then((data) => {
    console.log(JSON.stringify(data, null, 4));
})
Result
{
    "id": 2021,
    "area": {
        "id": 2072,
        "name": "England"
    },
    "name": "Premier League",
    "code": "PL",
    "emblemUrl": null,
    "plan": "TIER_ONE",
    "currentSeason": {
        "id": 151,
        "startDate": "2018-08-10",
        "endDate": "2019-05-12",
        "currentMatchday": 33,
        "winner": null
    },
    "seasons": [
        {
            "id": 151,
            "startDate": "2018-08-10",
            "endDate": "2019-05-12",
            "currentMatchday": 33,
            "winner": null
        },
        {
            "id": 23,
            "startDate": "2017-08-11",
            "endDate": "2018-05-13",
            "currentMatchday": 38,
            "winner": {
                "id": 65,
                "name": "Manchester City FC",
                "shortName": "Man City",
                "tla": "MCI",
                "crestUrl": "https://upload.wikimedia.org/wikipedia/en/e/eb/Manchester_City_FC_badge.svg"
            }
        },
        ...
    ],
    "lastUpdated": "2019-04-06T00:00:38Z"
}

Get teams from competition

footballData.getTeamsFromCompetition({
    competitionId: 2021,
}).then((data) => {
    console.log(JSON.stringify(data, null, 4));
})
Result
{
    "count": 20,
    "filters": {},
    "competition": {
        "id": 2021,
        "area": {
            "id": 2072,
            "name": "England"
        },
        "name": "Premier League",
        "code": "PL",
        "plan": "TIER_ONE",
        "lastUpdated": "2019-04-06T00:00:38Z"
    },
    "season": {
        "id": 151,
        "startDate": "2018-08-10",
        "endDate": "2019-05-12",
        "currentMatchday": 33,
        "winner": null
    },
    "teams": [
        {
            "id": 57,
            "area": {
                "id": 2072,
                "name": "England"
            },
            "name": "Arsenal FC",
            "shortName": "Arsenal",
            "tla": "ARS",
            "crestUrl": "http://upload.wikimedia.org/wikipedia/en/5/53/Arsenal_FC.svg",
            "address": "75 Drayton Park London N5 1BU",
            "phone": "+44 (020) 76195003",
            "website": "http://www.arsenal.com",
            "email": "info@arsenal.co.uk",
            "founded": 1886,
            "clubColors": "Red / White",
            "venue": "Emirates Stadium",
            "lastUpdated": "2019-04-04T02:50:20Z"
        },
        ...
    ]
}

Get standings

footballData.getStandingsFromCompetition({
    competitionId: 2021,
    standingType: 'TOTAL',
}).then((data) => {
    console.log(JSON.stringify(data, null, 4));
})
Result
{
    "filters": {},
    "competition": {
        "id": 2021,
        "area": {
            "id": 2072,
            "name": "England"
        },
        "name": "Premier League",
        "code": "PL",
        "plan": "TIER_ONE",
        "lastUpdated": "2019-04-06T00:00:38Z"
    },
    "season": {
        "id": 151,
        "startDate": "2018-08-10",
        "endDate": "2019-05-12",
        "currentMatchday": 33,
        "winner": null
    },
    "standings": [
        {
            "stage": "REGULAR_SEASON",
            "type": "TOTAL",
            "group": null,
            "table": [
                {
                    "position": 1,
                    "team": {
                        "id": 64,
                        "name": "Liverpool FC",
                        "crestUrl": "http://upload.wikimedia.org/wikipedia/de/0/0a/FC_Liverpool.svg"
                    },
                    "playedGames": 33,
                    "won": 25,
                    "draw": 7,
                    "lost": 1,
                    "points": 82,
                    "goalsFor": 75,
                    "goalsAgainst": 20,
                    "goalDifference": 55
                },
                {
                    "position": 2,
                    "team": {
                        "id": 65,
                        "name": "Manchester City FC",
                        "crestUrl": "https://upload.wikimedia.org/wikipedia/en/e/eb/Manchester_City_FC_badge.svg"
                    },
                    "playedGames": 32,
                    "won": 26,
                    "draw": 2,
                    "lost": 4,
                    "points": 80,
                    "goalsFor": 83,
                    "goalsAgainst": 21,
                    "goalDifference": 62
                },
                ...
            ]
        }
    ]
}

Get matches from competition

footballData.getMatchesFromCompetition({
    competitionId: 2021,
    season: 2017,
    matchday: 12,
}).then((data) => {
    console.log(JSON.stringify(data, null, 4));
})
Result
{
    "count": 10,
    "filters": {
        "matchday": "12"
    },
    "competition": {
        "id": 2021,
        "area": {
            "id": 2072,
            "name": "England"
        },
        "name": "Premier League",
        "code": "PL",
        "plan": "TIER_ONE",
        "lastUpdated": "2019-04-06T00:00:38Z"
    },
    "matches": [
        {
            "id": 205266,
            "season": {
                "id": 23,
                "startDate": "2017-08-11",
                "endDate": "2018-05-13",
                "currentMatchday": 38
            },
            "utcDate": "2017-11-18T12:30:00Z",
            "status": "FINISHED",
            "matchday": 12,
            "stage": "REGULAR_SEASON",
            "group": "Regular Season",
            "lastUpdated": "2018-06-22T10:04:00Z",
            "score": {
                "winner": "HOME_TEAM",
                "duration": "REGULAR",
                "fullTime": {
                    "homeTeam": 2,
                    "awayTeam": 0
                },
                "halfTime": {
                    "homeTeam": 2,
                    "awayTeam": 0
                },
                "extraTime": {
                    "homeTeam": null,
                    "awayTeam": null
                },
                "penalties": {
                    "homeTeam": null,
                    "awayTeam": null
                }
            },
            "homeTeam": {
                "id": 57,
                "name": "Arsenal FC"
            },
            "awayTeam": {
                "id": 73,
                "name": "Tottenham Hotspur FC"
            },
            "referees": [
                {
                    "id": 11575,
                    "name": "Mike Dean",
                    "nationality": null
                },
                {
                    "id": 11495,
                    "name": "Ian Hussin",
                    "nationality": null
                },
                {
                    "id": 11480,
                    "name": "Eddie Smart",
                    "nationality": null
                },
                {
                    "id": 11487,
                    "name": "Kevin Friend",
                    "nationality": null
                }
            ]
        },
        ...
    ]
}

Get scorers

footballData.getScorersFromCompetition({
    competitionId: 2002,
}).then((data) => {
    console.log(JSON.stringify(data, null, 4));
})
Result
{
    "count": 10,
    "filters": {
        "limit": 10
    },
    "competition": {
        "id": 2002,
        "area": {
            "id": 2088,
            "name": "Germany"
        },
        "name": "Bundesliga",
        "code": "BL1",
        "plan": "TIER_ONE",
        "lastUpdated": "2019-04-06T00:00:38Z"
    },
    "season": {
        "id": 155,
        "startDate": "2018-08-24",
        "endDate": "2019-05-18",
        "currentMatchday": 28,
        "winner": null
    },
    "scorers": [
        {
            "player": {
                "id": 371,
                "name": "Robert Lewandowski",
                "firstName": "Robert",
                "lastName": null,
                "dateOfBirth": "1988-08-21",
                "countryOfBirth": "Poland",
                "nationality": "Poland",
                "position": "Attacker",
                "shirtNumber": null,
                "lastUpdated": "2019-04-05T05:12:21Z"
            },
            "team": {
                "id": 5,
                "name": "FC Bayern München"
            },
            "numberOfGoals": 19
        },
        ...
    ]
}

Get matches

footballData.getMatches({
    dateFrom: '2019-04-01',
    dateTo: '2019-04-05',
    competitions: [2021, 2002], // Premier League and Bundesliga
}).then((data) => {
    console.log(JSON.stringify(data, null, 4));
})
Result
{
    "count": 8,
    "filters": {
        "dateFrom": "2019-04-01",
        "dateTo": "2019-04-05",
        "permission": "TIER_ONE",
        "competitions": [
            2021,
            2002
        ]
    },
    "matches": [
        {
            "id": 233335,
            "competition": {
                "id": 2021,
                "name": "Premier League"
            },
            "season": {
                "id": 151,
                "startDate": "2018-08-10",
                "endDate": "2019-05-12",
                "currentMatchday": 33,
                "winner": null
            },
            "utcDate": "2019-04-01T19:00:00Z",
            "status": "FINISHED",
            "matchday": 32,
            "stage": "REGULAR_SEASON",
            "group": "Regular Season",
            "lastUpdated": "2019-04-02T21:35:06Z",
            "score": {
                "winner": "HOME_TEAM",
                "duration": "REGULAR",
                "fullTime": {
                    "homeTeam": 2,
                    "awayTeam": 0
                },
                "halfTime": {
                    "homeTeam": 1,
                    "awayTeam": 0
                },
                "extraTime": {
                    "homeTeam": null,
                    "awayTeam": null
                },
                "penalties": {
                    "homeTeam": null,
                    "awayTeam": null
                }
            },
            "homeTeam": {
                "id": 57,
                "name": "Arsenal FC"
            },
            "awayTeam": {
                "id": 67,
                "name": "Newcastle United FC"
            },
            "referees": [
                {
                    "id": 11580,
                    "name": "Anthony Taylor",
                    "nationality": null
                },
                {
                    "id": 11581,
                    "name": "Gary Beswick",
                    "nationality": null
                },
                {
                    "id": 11615,
                    "name": "Adam Nunn",
                    "nationality": null
                },
                {
                    "id": 11556,
                    "name": "David Coote",
                    "nationality": null
                }
            ]
        },
        ...
    ]
}

Get specific match

footballData.getMatch({
    id: 233325,
}).then((data) => {
    console.log(JSON.stringify(data, null, 4));
})
Result
{
    "head2head": {
        "numberOfMatches": 10,
        "totalGoals": 17,
        "homeTeam": {
            "wins": 8,
            "draws": 0,
            "losses": 2
        },
        "awayTeam": {
            "wins": 2,
            "draws": 0,
            "losses": 8
        }
    },
    "match": {
        "id": 233325,
        "competition": {
            "id": 2021,
            "name": "Premier League"
        },
        "season": {
            "id": 151,
            "startDate": "2018-08-10",
            "endDate": "2019-05-12",
            "currentMatchday": 33,
            "winner": null
        },
        "utcDate": "2019-04-03T18:45:00Z",
        "status": "FINISHED",
        "venue": "Tottenham Hotspur Stadium",
        "matchday": 31,
        "stage": "REGULAR_SEASON",
        "group": "Regular Season",
        "lastUpdated": "2019-04-03T23:44:40Z",
        "score": {
            "winner": "HOME_TEAM",
            "duration": "REGULAR",
            "fullTime": {
                "homeTeam": 2,
                "awayTeam": 0
            },
            "halfTime": {
                "homeTeam": 0,
                "awayTeam": 0
            },
            "extraTime": {
                "homeTeam": null,
                "awayTeam": null
            },
            "penalties": {
                "homeTeam": null,
                "awayTeam": null
            }
        },
        "homeTeam": {
            "id": 73,
            "name": "Tottenham Hotspur FC"
        },
        "awayTeam": {
            "id": 354,
            "name": "Crystal Palace FC"
        },
        "referees": [
            {
                "id": 11610,
                "name": "Andre Marriner",
                "nationality": null
            },
            {
                "id": 11611,
                "name": "Scott Ledger",
                "nationality": null
            },
            {
                "id": 11504,
                "name": "Simon Long",
                "nationality": null
            },
            {
                "id": 11443,
                "name": "Chris Kavanagh",
                "nationality": null
            }
        ]
    }
}

Get matches from team

footballData.getMatchesFromTeam({
    teamId: 62, // Everton
    status: 'SCHEDULED',
}).then((data) => {
    console.log(JSON.stringify(data, null, 4));
})
Result
{
    "count": 6,
    "filters": {
        "permission": "TIER_ONE",
        "status": [
            "SCHEDULED"
        ],
        "limit": 100
    },
    "matches": [
        {
            "id": 233348,
            "competition": {
                "id": 2021,
                "name": "Premier League"
            },
            "season": {
                "id": 151,
                "startDate": "2018-08-10",
                "endDate": "2019-05-12",
                "currentMatchday": 33,
                "winner": null
            },
            "utcDate": "2019-04-07T13:05:00Z",
            "status": "SCHEDULED",
            "matchday": 33,
            "stage": "REGULAR_SEASON",
            "group": "Regular Season",
            "lastUpdated": "2019-04-06T00:00:38Z",
            "score": {
                "winner": null,
                "duration": "REGULAR",
                "fullTime": {
                    "homeTeam": null,
                    "awayTeam": null
                },
                "halfTime": {
                    "homeTeam": null,
                    "awayTeam": null
                },
                "extraTime": {
                    "homeTeam": null,
                    "awayTeam": null
                },
                "penalties": {
                    "homeTeam": null,
                    "awayTeam": null
                }
            },
            "homeTeam": {
                "id": 62,
                "name": "Everton FC"
            },
            "awayTeam": {
                "id": 57,
                "name": "Arsenal FC"
            },
            "referees": []
        },
        ...
    ]
}

Get specific team

footballData.getTeam({
    id: 86, // Real Madrid
}).then((data) => {
    console.log(JSON.stringify(data, null, 4));
})
Result
{
    "id": 86,
    "area": {
        "id": 2224,
        "name": "Spain"
    },
    "activeCompetitions": [
        {
            "id": 2001,
            "area": {
                "id": 2077,
                "name": "Europe"
            },
            "name": "UEFA Champions League",
            "code": "CL",
            "plan": "TIER_ONE",
            "lastUpdated": "2019-03-14T03:25:02Z"
        },
        {
            "id": 2014,
            "area": {
                "id": 2224,
                "name": "Spain"
            },
            "name": "Primera Division",
            "code": "PD",
            "plan": "TIER_ONE",
            "lastUpdated": "2019-04-06T00:00:38Z"
        },
        {
            "id": 2079,
            "area": {
                "id": 2224,
                "name": "Spain"
            },
            "name": "Copa del Rey",
            "code": "CDR",
            "plan": "TIER_THREE",
            "lastUpdated": "2019-02-28T23:39:16Z"
        }
    ],
    "name": "Real Madrid CF",
    "shortName": "Real Madrid",
    "tla": "RMA",
    "crestUrl": "http://upload.wikimedia.org/wikipedia/de/3/3f/Real_Madrid_Logo.svg",
    "address": "Avenida Concha Espina, 1 Madrid 28036",
    "phone": "+34 (913) 984300",
    "website": "http://www.realmadrid.com",
    "email": "atencionpublico@corp.realmadrid.com",
    "founded": 1902,
    "clubColors": "White / Purple",
    "venue": "Estadio Santiago Bernabéu",
    "squad": [
        {
            "id": 51,
            "name": "Keylor Navas",
            "position": "Goalkeeper",
            "dateOfBirth": "1986-12-15T00:00:00Z",
            "countryOfBirth": "Costa Rica",
            "nationality": "Costa Rica",
            "shirtNumber": null,
            "role": "PLAYER"
        },
        {
            "id": 3641,
            "name": "Thibaut Courtois",
            "position": "Goalkeeper",
            "dateOfBirth": "1992-05-11T00:00:00Z",
            "countryOfBirth": "Belgium",
            "nationality": "Belgium",
            "shirtNumber": null,
            "role": "PLAYER"
        },
        {
            "id": 3871,
            "name": "Luca Zidane",
            "position": "Goalkeeper",
            "dateOfBirth": "1998-05-13T00:00:00Z",
            "countryOfBirth": "France",
            "nationality": "France",
            "shirtNumber": 30,
            "role": "PLAYER"
        },
        ...
    ],
    "lastUpdated": "2019-04-04T02:40:06Z"
}

Get all areas

footballData.getAreas().then((data) => {
    console.log(JSON.stringify(data, null, 4));
})
Result
{
    "count": 273,
    "filters": {},
    "areas": [
        {
            "id": 2000,
            "name": "Afghanistan",
            "countryCode": "AFG",
            "ensignUrl": null,
            "parentAreaId": 2014,
            "parentArea": "Asia"
        },
        {
            "id": 2001,
            "name": "Africa",
            "countryCode": "AFR",
            "ensignUrl": null,
            "parentAreaId": 2267,
            "parentArea": "World"
        },
        {
            "id": 2002,
            "name": "Albania",
            "countryCode": "ALB",
            "ensignUrl": null,
            "parentAreaId": 2077,
            "parentArea": "Europe"
        },
        ...
    ]
}

Get specific area

footballData.getArea({
    id: 2072,
}).then((data) => {
    console.log(JSON.stringify(data, null, 4));
})
Result
{
    "id": 2072,
    "name": "England",
    "countryCode": "ENG",
    "ensignUrl": "https://upload.wikimedia.org/wikipedia/en/a/ae/Flag_of_the_United_Kingdom.svg",
    "parentAreaId": 2077,
    "parentArea": "Europe",
    "childAreas": []
}

Get specific player

footballData.getPlayer({
    id: 2019,
}).then((data) => {
    console.log(JSON.stringify(data, null, 4));
})
Result
{
    "id": 2019,
    "name": "Gianluigi Buffon",
    "firstName": "Gianluigi",
    "lastName": null,
    "dateOfBirth": "1978-01-28",
    "countryOfBirth": "Italy",
    "nationality": "Italy",
    "position": "Goalkeeper",
    "shirtNumber": 1,
    "lastUpdated": "2019-02-21T05:10:20Z"
}

Get matches from player

footballData.getMatchesFromPlayer({
    playerId: 2019,
    dateFrom: '2016-01-01',
    dateTo: '2017-01-01',
    status: 'FINISHED',
}).then((data) => {
    console.log(JSON.stringify(data, null, 4));
})
Result
{
    "count": 5,
    "filters": {
        "permission": "TIER_ONE",
        "dateFrom": "2016-01-01",
        "dateTo": "2017-01-01",
        "status": [
            "FINISHED"
        ],
        "limit": 100
    },
    "player": {
        "id": 2019,
        "name": "Gianluigi Buffon",
        "firstName": "Gianluigi",
        "lastName": null,
        "dateOfBirth": "1978-01-28",
        "countryOfBirth": "Italy",
        "nationality": "Italy",
        "position": "Goalkeeper",
        "shirtNumber": 1,
        "lastUpdated": "2019-02-21T05:10:20Z"
    },
    "matches": [
        {
            "id": 228574,
            "competition": {
                "id": 2018,
                "name": "European Championship"
            },
            "season": {
                "id": 20,
                "startDate": "2016-06-10",
                "endDate": "2016-07-10",
                "currentMatchday": 3
            },
            "utcDate": "2016-07-02T19:00:00Z",
            "status": "FINISHED",
            "matchday": null,
            "stage": "QUARTER_FINALS",
            "group": "Quarter-finals",
            "lastUpdated": "2019-01-11T17:33:45Z",
            "score": {
                "winner": "HOME_TEAM",
                "duration": "PENALTY_SHOOTOUT",
                "fullTime": {
                    "homeTeam": 1,
                    "awayTeam": 1
                },
                "halfTime": {
                    "homeTeam": 0,
                    "awayTeam": 0
                },
                "extraTime": {
                    "homeTeam": 0,
                    "awayTeam": 0
                },
                "penalties": {
                    "homeTeam": 6,
                    "awayTeam": 5
                }
            },
            "homeTeam": {
                "id": 759,
                "name": "Germany"
            },
            "awayTeam": {
                "id": 784,
                "name": "Italy"
            },
            "referees": [
                {
                    "id": 43910,
                    "name": "Viktor Kassai",
                    "nationality": null
                },
                {
                    "id": 43911,
                    "name": "György Ring",
                    "nationality": null
                },
                {
                    "id": 43912,
                    "name": "Vencel Tóth",
                    "nationality": null
                },
                {
                    "id": 43888,
                    "name": "Szymon Marciniak",
                    "nationality": null
                },
                {
                    "id": 43827,
                    "name": "Tamás Bognár",
                    "nationality": null
                },
                {
                    "id": 57157,
                    "name": "Ádám Farkas",
                    "nationality": null
                }
            ]
        },
        ...
    ]
}

Testing

$ npm test

License

Mit License