footballdata-api-v2
v2.3.0
Published
Football Data API
Downloads
8
Maintainers
nearhuscarlReadme
Football Data API
Installation
$ npm install footballdata-api-v2Get 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));
}){
...
"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));
}){
"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));
}){
"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));
}){
"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": "[email protected]",
"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));
}){
"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));
}){
"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));
}){
"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));
}){
"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));
}){
"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));
}){
"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));
}){
"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": "[email protected]",
"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));
}){
"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));
}){
"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));
}){
"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));
}){
"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