Football operations

Fetch football data from the Fans United Football API

Football operations are responsible for communicating with the Football API.
Each method also converts your IDs to the desired ID provider for easier and quicker development.
Depending on the language set in your SDK configuration, the names in the responses will be returned in the corresponding language, if supported.
If a particular name is not translated, the language falls back to English.

The namespace is of course called football. All methods return promises. The general design of the namespace follows this pattern:

sdk.football.someMethod(filtersObject).then((responseObject) => {
    // do something with responseObject
});

The responses are comprised of different objects you can find here.

Player related methods

Get players

Method: getPlayers({}, disableCache?)

This method is used when you want to fetch a list of players based on different criteria. You can use it to fetch football
players from a country or a team, you can fetch specific players by ID or make a general search. You can scope your search
and get ordered paginated results.
If no value is passed to disableCache (undefined) it will be set to false.

Filters object:

  • countryId: string. Limits the players to the specified country
  • scope: string[]. A list of competition IDs. Limits the result set to players only in those competitions.
  • name: string. The value in this field will be used for search purposes.
  • playerIds: string[]. An array of player IDs. Returns all specified players.
  • limit: number. Determines how many items per page there will be.
  • page: number. The number of the page.
  • sortField: string. Determines the field used for the sorting.
  • sortOrder: string. Determines the sort order - asc or desc
sdk.football.getPlayers().then((responseObject) => {
    // do something with responseObject
});

Example result

{
   meta: {
      pagination: {
         currentPage: 1,
         itemsPerPage: 1,
         totalItems: 257697,
         numberOfPages: 12885
      }
   },
   data: [
      {
         id: "fb:p:43400",
         country: {
            id: "fb:cnt:3135",
            alias: null,
            countryCode: "PRT",
            assets: {
               flag: "https://football.fansunitedassets.com/country/3a92ec60-8e19-11eb-b60d-42010a84003b.png"
            },
            name: "Portugal"
         },
         birthDate: "1985-02-05",
         firstName: "Cristiano Ronaldo",
         lastName: "dos Santos Aveiro",
         name: "Cristiano Ronaldo",
         position: "forward",
         assets: {
            headshot: "https://football.fansunitedassets.com/player/41ff1b20-8c4e-11eb-aff3-42010a8400d1.jpeg"
         },
         teams: [
            {
               id: "fb:t:8102",
               country: {
                  id: "fb:cnt:1522",
                  alias: null,
                  countryCode: "ENG",
                  assets: {
                     flag: "https://football.fansunitedassets.com/country/3a930dd8-8e19-11eb-b60d-42010a84003b.png"
                  },
                  name: "England"
               },
               gender: "male",
               assets: {
                  logo: "https://football.fansunitedassets.com/team/41fba11d-8c4e-11eb-aff3-42010a8400d1.png"
               },
               name: "Manchester United",
               code: "MNU",
               national: false,
               fullName: null,
               shortName: null
            },
            {
               id: "fb:t:81651",
               country: {
                  id: "fb:cnt:3135",
                  alias: null,
                  countryCode: "PRT",
                  assets: {
                     flag: "https://football.fansunitedassets.com/country/3a92ec60-8e19-11eb-b60d-42010a84003b.png"
                  },
                  name: "Portugal"
               },
               gender: "male",
               assets: {
                  logo: "https://football.fansunitedassets.com/team/4217ec5f-8c4e-11eb-aff3-42010a8400d1.png"
               },
               name: "Portugal",
               code: "POR",
               national: true,
               fullName: null,
               shortName: null
            }
         ]
      }
   ]
}

Get player by ID

Method: getPlayerById(ID, disableCache?)

This method returns data for a particular player identified by ID string parameter. Besides the player data, the method
also returns the teams the player plays for as well as the competitions these teams (respectively the player) participates in.
If no value is passed to disableCache (undefined) it will be set to false.

sdk.football.getPlayerById("fb:p:43400").then((responseObject) => {
    // do something with responseObject
});

Example result

{
   id: "fb:p:43400",
   country: {
      id: "fb:cnt:3135",
      alias: null,
      countryCode: "PRT",
      assets: {
         flag: "https://football.fansunitedassets.com/country/3a92ec60-8e19-11eb-b60d-42010a84003b.png"
      },
      name: "Portugal"
   },
   birthDate: "1985-02-05",
   firstName: "Cristiano Ronaldo",
   lastName: "dos Santos Aveiro",
   name: "Cristiano Ronaldo",
   position: "forward",
   assets: {
      headshot: "https://football.fansunitedassets.com/player/41ff1b20-8c4e-11eb-aff3-42010a8400d1.jpeg"
   },
   competitions: [
      {
         id: "fb:c:76",
         country: {
            id: "fb:cnt:1522",
            alias: null,
            countryCode: "ENG",
            assets: {
               flag: "https://football.fansunitedassets.com/country/3a930dd8-8e19-11eb-b60d-42010a84003b.png"
            },
            name: "England"
         },
         gender: "male",
         assets: {
            logo: "https://football.fansunitedassets.com/competition/42107f75-8c4e-11eb-aff3-42010a8400d1.png"
         },
         type: "cup",
         name: "EFL Cup"
      },
      {
         id: "fb:c:3",
         country: {
            id: "fb:cnt:1522",
            alias: null,
            countryCode: "ENG",
            assets: {
               flag: "https://football.fansunitedassets.com/country/3a930dd8-8e19-11eb-b60d-42010a84003b.png"
            },
            name: "England"
         },
         gender: "male",
         assets: {
            logo: "https://football.fansunitedassets.com/competition/42108c2a-8c4e-11eb-aff3-42010a8400d1.png"
         },
         type: "league",
         name: "Premier League"
      },
      {
         id: "fb:c:75",
         country: {
            id: "fb:cnt:1522",
            alias: null,
            countryCode: "ENG",
            assets: {
               flag: "https://football.fansunitedassets.com/country/3a930dd8-8e19-11eb-b60d-42010a84003b.png"
            },
            name: "England"
         },
         gender: "male",
         assets: {
            logo: "https://football.fansunitedassets.com/competition/4210933b-8c4e-11eb-aff3-42010a8400d1.png"
         },
         type: "cup",
         name: "FA Cup"
      },
      {
         id: "fb:c:29",
         country: {
            id: "fb:cnt:1221",
            alias: null,
            countryCode: "INT",
            assets: {
               flag: "https://football.fansunitedassets.com/country/3a931055-8e19-11eb-b60d-42010a84003b.png"
            },
            name: "International"
         },
         gender: "male",
         assets: {
            logo: null
         },
         type: "cup",
         name: "Friendlies"
      },
      {
         id: "fb:c:37",
         country: {
            id: "fb:cnt:1221",
            alias: null,
            countryCode: "INT",
            assets: {
               flag: "https://football.fansunitedassets.com/country/3a931055-8e19-11eb-b60d-42010a84003b.png"
            },
            name: "International"
         },
         gender: "male",
         assets: {
            logo: "https://football.fansunitedassets.com/competition/421092ce-8c4e-11eb-aff3-42010a8400d1.png"
         },
         type: null,
         name: "European Championship"
      },
      {
         id: "fb:c:27",
         country: {
            id: "fb:cnt:1221",
            alias: null,
            countryCode: "INT",
            assets: {
               flag: "https://football.fansunitedassets.com/country/3a931055-8e19-11eb-b60d-42010a84003b.png"
            },
            name: "International"
         },
         gender: "male",
         assets: {
            logo: "https://football.fansunitedassets.com/competition/42109005-8c4e-11eb-aff3-42010a8400d1.png"
         },
         type: null,
         name: "Champions League"
      }
   ],
   teams: [
      {
         id: "fb:t:8102",
         country: {
            id: "fb:cnt:1522",
            alias: null,
            countryCode: "ENG",
            assets: {
               flag: "https://football.fansunitedassets.com/country/3a930dd8-8e19-11eb-b60d-42010a84003b.png"
            },
            name: "England"
         },
         gender: "male",
         assets: {
            logo: "https://football.fansunitedassets.com/team/41fba11d-8c4e-11eb-aff3-42010a8400d1.png"
         },
         name: "Manchester United",
         code: "MNU",
         national: false,
         fullName: null,
         shortName: null
      },
      {
         id: "fb:t:81651",
         country: {
            id: "fb:cnt:3135",
            alias: null,
            countryCode: "PRT",
            assets: {
               flag: "https://football.fansunitedassets.com/country/3a92ec60-8e19-11eb-b60d-42010a84003b.png"
            },
            name: "Portugal"
         },
         gender: "male",
         assets: {
            logo: "https://football.fansunitedassets.com/team/4217ec5f-8c4e-11eb-aff3-42010a8400d1.png"
         },
         name: "Portugal",
         code: "POR",
         national: true,
         fullName: null,
         shortName: null
      }
   ]
}

Get top players

Method: getTopPlayers(disableCache?)

This method returns the top players for a particular client. The top players are determined based on the follow counts by the users.
If there isn't enough data, the top European players are returned as default.
If no value is passed to disableCache (undefined) it will be set to false.

sdk.football.getTopPlayers().then((responseObject) => {
    // do something with responseObject
});

Example result

[
   {
      id: "fb:p:43400",
      country: {
         id: "fb:cnt:3135",
         alias: null,
         countryCode: "PRT",
         assets: {
            flag: "https://football.fansunitedassets.com/country/3a92ec60-8e19-11eb-b60d-42010a84003b.png"
         },
         name: "Portugal"
      },
      birthDate: "1985-02-05",
      firstName: "Cristiano Ronaldo",
      lastName: "dos Santos Aveiro",
      name: "Cristiano Ronaldo",
      position: "forward",
      assets: {
         headshot: "https://football.fansunitedassets.com/player/41ff1b20-8c4e-11eb-aff3-42010a8400d1.jpeg"
      }
   },
   {
      id: "fb:p:43399",
      country: {
         id: "fb:cnt:552",
         alias: null,
         countryCode: "ARG",
         assets: {
            flag: "https://football.fansunitedassets.com/country/3a92dfb7-8e19-11eb-b60d-42010a84003b.png"
         },
         name: "Argentina"
      },
      birthDate: "1987-06-24",
      firstName: "Lionel Andrés",
      lastName: "Messi Cuccittini",
      name: "Lionel Messi",
      position: "forward",
      assets: {
         headshot: "https://football.fansunitedassets.com/player/42066a25-8c4e-11eb-aff3-42010a8400d1.jpeg"
      }
   }
]

Team related methods

Get teams

Method: getTeams({}, disableCache?)

This method is used when you want to fetch a list of teams based on different criteria. You can use it to fetch football
teams from a country or by gender, you can fetch specific teams by ID or make a general search. You can scope your search
and get ordered paginated results.
If no value is passed to disableCache (undefined) it will be set to false.

Filters object:

  • name: string. The value in this field will be used for search purposes.
  • countryId: string. Limits the teams to the specified country
  • national: boolean. Determines whether the teams should be national or clubs
  • gender: string. Options are "male" or "female"
  • limit: number. Determines how many items per page there will be.
  • page: number. The number of the page.
  • scope: string[]. A list of competition IDs. Limits the result set to teams only in those competitions.
  • sortField: string. Determines the field used for the sorting.
  • sortOrder: string. Determines the sort order - asc or desc
  • teamIds: string[]. An array of team IDs. Returns all specified teams.
sdk.football.getTeams().then((responseObject) => {
    // do something with responseObject
});

Example result

{
   meta: {
      pagination: {
         currentPage: 1,
         itemsPerPage: 1,
         totalItems: 25153,
         numberOfPages: 1258
      }
   },
   data: [
      {
          id: "fb:t:8102",
          country: {
             id: "fb:cnt:1522",
             alias: null,
             countryCode: "ENG",
             assets: {
                flag: "https://football.fansunitedassets.com/country/3a930dd8-8e19-11eb-b60d-42010a84003b.png"
             },
             name: "England"
          },
          gender: "male",
          assets: {
             logo: "https://football.fansunitedassets.com/team/41fba11d-8c4e-11eb-aff3-42010a8400d1.png"
          },
          name: "Manchester United",
          code: "MNU",
          national: false,
          fullName: null,
          shortName: null
       }
   ]
}

Get team by ID

Method: getTeamById(ID, disableCache?)

This method returns data for a particular team identified by ID string parameter. Besides the team data, the method
also returns the competitions this team participates in as well as the squad of players.
If no value is passed to disableCache (undefined) it will be set to false.

sdk.football.getTeamById("fb:t:8102").then((responseObject) => {
    // do something with responseObject
});

Example result

{
   id: "fb:t:8102",
   country: {
      id: "fb:cnt:1522",
      alias: null,
      countryCode: "ENG",
      assets: {
         flag: "https://football.fansunitedassets.com/country/3a930dd8-8e19-11eb-b60d-42010a84003b.png"
      },
      name: "England"
   },
   gender: "male",
   assets: {
      logo: "https://football.fansunitedassets.com/team/41fba11d-8c4e-11eb-aff3-42010a8400d1.png"
   },
   name: "Manchester United",
   colors: {
      primary: "#DA291C",
      secondary: null,
      tertiary: null
   },
   competitions: [
      {
         id: "fb:c:3",
         country: {
            id: "fb:cnt:1522",
            alias: null,
            countryCode: "ENG",
            assets: {
               flag: "https://football.fansunitedassets.com/country/3a930dd8-8e19-11eb-b60d-42010a84003b.png"
            },
            name: "England"
         },
         gender: "male",
         assets: {
            logo: "https://football.fansunitedassets.com/competition/42108c2a-8c4e-11eb-aff3-42010a8400d1.png"
         },
         type: "league",
         name: "Premier League"
      },
      {
         id: "fb:c:27",
         country: {
            id: "fb:cnt:1221",
            alias: null,
            countryCode: "INT",
            assets: {
               flag: "https://football.fansunitedassets.com/country/3a931055-8e19-11eb-b60d-42010a84003b.png"
            },
            name: "International"
         },
         gender: "male",
         assets: {
            logo: "https://football.fansunitedassets.com/competition/42109005-8c4e-11eb-aff3-42010a8400d1.png"
         },
         type: null,
         name: "Champions League"
      }
   ],
   code: "MNU",
   national: false,
   fullName: null,
   shortName: null,
     
   squad: [
      {
         id: "fb:p:41601",
         startDate: "2011-07-01",
         endDate: null,
         loan: false,
         position: "keeper",
         country: {
            id: "fb:cnt:1799",
            alias: null,
            countryCode: "ESP",
            assets: {
               flag: "https://football.fansunitedassets.com/country/3a93054f-8e19-11eb-b60d-42010a84003b.png"
            },
            name: "Spain"
         },
         name: "David De Gea",
         assets: {
            headshot: "https://football.fansunitedassets.com/player/420772b2-8c4e-11eb-aff3-42010a8400d1.jpeg"
         },
         birthDate: "1990-11-07",
         shirtNumber: 1
      },
      {
         id: "fb:p:43400",
         startDate: "2021-08-31",
         endDate: null,
         loan: false,
         position: "forward",
         country: {
            id: "fb:cnt:3135",
            alias: null,
            countryCode: "PRT",
            assets: {
               flag: "https://football.fansunitedassets.com/country/3a92ec60-8e19-11eb-b60d-42010a84003b.png"
            },
            name: "Portugal"
         },
         name: "Cristiano Ronaldo",
         assets: {
            headshot: "https://football.fansunitedassets.com/player/41ff1b20-8c4e-11eb-aff3-42010a8400d1.jpeg"
         },
         birthDate: "1985-02-05",
         shirtNumber: null
      }
   ]
}

Get top teams

Method: getTopTeams(disableCache?)

This method returns the top teams for a particular client. The top teams are determined based on the follow counts by the users.
If there isn't enough data, the top European teams are returned as default.
If no value is passed to disableCache (undefined) it will be set to false.

sdk.football.getTopTeams().then((responseObject) => {
    // do something with responseObject
});

Example result

[
   {
      id: "fb:t:8204",
      country: {
         id: "fb:cnt:1799",
         alias: null,
         countryCode: "ESP",
         assets: {
            flag: "https://football.fansunitedassets.com/country/3a93054f-8e19-11eb-b60d-42010a84003b.png"
         },
         name: "Spain"
      },
      gender: "male",
      assets: {
         logo: "https://football.fansunitedassets.com/team/42132e72-8c4e-11eb-aff3-42010a8400d1.png"
      },
      name: "Real Madrid",
      code: "RMA",
      national: false,
      fullName: null,
      shortName: null
   },
   {
      id: "fb:t:8205",
      country: {
         id: "fb:cnt:1799",
         alias: null,
         countryCode: "ESP",
         assets: {
            flag: "https://football.fansunitedassets.com/country/3a93054f-8e19-11eb-b60d-42010a84003b.png"
         },
         name: "Spain"
      },
      gender: "male",
      assets: {
         logo: "https://football.fansunitedassets.com/team/41fc13ac-8c4e-11eb-aff3-42010a8400d1.png"
      },
      name: "Barcelona",
      code: "BAR",
      national: false,
      fullName: null,
      shortName: null
   }
]

Competition related methods

Get competitions

Method: getCompetitions({}, disableCache?)

This method is used when you want to fetch a list of competitions based on different criteria. You can use it to fetch football
competitions by country or gender, you can fetch specific competitions by ID or make a general search. You can filter by type
and get ordered results.
If no value is passed to disableCache (undefined) it will be set to false.

Filters object:

  • countryId: string. Limits the competitions to the specified country
  • name: string. The value in this field will be used for search purposes.
  • gender: string. Options are "male" or "female"
  • type: string. The type of the competition - league or cup
  • sortField: string. Determines the field used for the sorting.
  • sortOrder: string. Determines the sort order - asc or desc
  • competitionIds: string[]. An array of competition IDs. Returns all specified competitions.
sdk.football.getCompetitions().then((responseObject) => {
    // do something with responseObject
});

Example result

[
   {
      id: "fb:c:3",
      country: {
         id: "fb:cnt:1522",
         alias: null,
         countryCode: "ENG",
         assets: {
            flag: "https://football.fansunitedassets.com/country/3a930dd8-8e19-11eb-b60d-42010a84003b.png"
         },
         name: "England"
      },
      gender: "male",
      assets: {
         logo: "https://football.fansunitedassets.com/competition/42108c2a-8c4e-11eb-aff3-42010a8400d1.png"
      },
      type: "league",
      name: "Premier League"
   }
]

Get competition by ID

Method: getCompetitionById(ID, disableCache?)

This method returns data for a particular competition identified by ID string parameter. Besides the competition data, the method
also returns the teams that participate in the current season.
If no value is passed to disableCache (undefined) it will be set to false.

sdk.football.getCompetitionById("fb:c:3").then((responseObject) => {
    // do something with responseObject
});

Example result

{
   id: "fb:c:3",
   country: {
      id: "fb:cnt:1522",
      alias: null,
      countryCode: "ENG",
      assets: {
         flag: "https://football.fansunitedassets.com/country/3a930dd8-8e19-11eb-b60d-42010a84003b.png"
      },
      name: "England"
   },
   gender: "male",
   assets: {
      logo: "https://football.fansunitedassets.com/competition/42108c2a-8c4e-11eb-aff3-42010a8400d1.png"
   },
   type: "league",
   name: "Premier League",
   participants: [
      {
         id: "fb:t:897",
         country: {
            id: "fb:cnt:1522",
            alias: null,
            countryCode: "ENG",
            assets: {
               flag: "https://football.fansunitedassets.com/country/3a930dd8-8e19-11eb-b60d-42010a84003b.png"
            },
            name: "England"
         },
         gender: "male",
         assets: {
            logo: "https://football.fansunitedassets.com/team/4213271f-8c4e-11eb-aff3-42010a8400d1.png"
         },
         name: "Arsenal",
         code: "ARS",
         national: false,
         fullName: null,
         shortName: null
      }
   ]
}

Get top competitions

Method: getTopCompetitions(disableCache?)

This method returns the top competitions for a particular client. The top competitions are determined based on the follow counts by the users.
If there isn't enough data, the top competitions are returned as default.
If no value is passed to disableCache (undefined) it will be set to false.

sdk.football.getTopCompetitions().then((responseObject) => {
    // do something with responseObject
});

Example result

[
   {
      id: "fb:c:3",
      country: {
         id: "fb:cnt:1522",
         alias: null,
         countryCode: "ENG",
         assets: {
            flag: "https://football.fansunitedassets.com/country/3a930dd8-8e19-11eb-b60d-42010a84003b.png"
         },
         name: "England"
      },
      gender: "male",
      assets: {
         logo: "https://football.fansunitedassets.com/competition/42108c2a-8c4e-11eb-aff3-42010a8400d1.png"
      },
      type: "league",
      name: "Premier League"
   },
   {
      id: "fb:c:5",
      country: {
         id: "fb:cnt:1799",
         alias: null,
         countryCode: "ESP",
         assets: {
            flag: "https://football.fansunitedassets.com/country/3a93054f-8e19-11eb-b60d-42010a84003b.png"
         },
         name: "Spain"
      },
      gender: "male",
      assets: {
         logo: "https://football.fansunitedassets.com/competition/42108d09-8c4e-11eb-aff3-42010a8400d1.png"
      },
      type: "league",
      name: "LaLiga"
   }
]

Match related methods

Get matches

Method: getMatches({}, disableCache?)

Returns a number of matches based on the specified criteria. The basic match information is available here. For details
such as timelines, starting lineups, etc, you should make call getMatchById().
If no value is passed to disableCache (undefined) it will be set to false.

Filters object:

  • countryIds: string[]. An array of country IDs. The result set will be limited to those countries.
  • competitionIds: string[]. An array of competition IDs. The result set will be limited to those competitions.
  • matchIds: string[]. An array of match IDs. The result set will be limited to those matches.
  • status: string. The status of the match. Options are live, upcoming and finished
  • teamIds: string[]. An array of team IDs. The result set will be limited to matches between the teams specified.
  • fromDate: string. Format: 2020-01-06T08:55:00Z. Search for matches starting (kickoff) from this datetime.
  • toDate: string. Format: 2020-01-06T08:55:00Z. Search for matches ending (kickoff) to this datetime.
  • limit: number. Determines how many items per page there will be.
  • page: number. The number of the page.
  • sortField: string. Determines the field used for the sorting. The only possible value is date. With it, the matches will be sorted by their kickoff time.
  • sortOrder: string. Determines the sort order - asc or desc
sdk.football.getMatches({matchIds: ["fb:m:662634"]}).then((responseObject) => {
    // do something with responseObject
});

Example result

{
   meta: {
      pagination: {
         currentPage: 1,
         itemsPerPage: 20,
         totalItems: 1,
         numberOfPages: 1
      }
   },
   data: [
      {
         id: "fb:m:662634",
         kickoffAt: "2021-10-10T18:45:00Z",
         finishedAt: "2021-10-10T20:40:42Z",
         updatedAt: "2021-10-12T14:31:12Z",
         availableMarkets: ["FT_1X2", "BOTH_TEAMS_SCORE"],
         homeTeam: {
            id: "fb:t:81770",
            country: {
               id: "fb:cnt:1799",
               alias: null,
               countryCode: "ESP",
               assets: {
                  flag: "https://football.fansunitedassets.com/country/3a93054f-8e19-11eb-b60d-42010a84003b.png"
               },
               name: "Spain"
            },
            gender: "male",
            assets: {
               logo: "https://football.fansunitedassets.com/team/421acd83-8c4e-11eb-aff3-42010a8400d1.png"
            },
            name: "Spain",
            code: "SPA",
            national: true,
            fullName: null,
            shortName: null
         },
         awayTeam: {
            id: "fb:t:82434",
            country: {
               id: "fb:cnt:2258",
               alias: null,
               countryCode: "FRA",
               assets: {
                  flag: "https://football.fansunitedassets.com/country/3a92ed77-8e19-11eb-b60d-42010a84003b.png"
               },
               name: "France"
            },
            gender: "male",
            assets: {
               logo: "https://football.fansunitedassets.com/team/42044961-8c4e-11eb-aff3-42010a8400d1.png"
            },
            name: "France",
            code: "FRA",
            national: true,
            fullName: null,
            shortName: null
         },
         lineupsConfirmed: true,
         startedAt: "2021-10-10T19:49:14Z",
         minute: null,
         scores: {
            ftScore: {
               homeGoals: 1,
               awayGoals: 2
            },
            htScore: {
               homeGoals: 0,
               awayGoals: 0
            },
            aetScore: {
               homeGoals: null,
               awayGoals: null
            },
            aggScore: {
               homeGoals: null,
               awayGoals: null
            },
            penScore: {
               homeGoals: null,
               awayGoals: null
            }
         },
         context: {
            competition: {
               id: "fb:c:553",
               country: {
                  id: "fb:cnt:1221",
                  alias: null,
                  countryCode: "INT",
                  assets: {
                     flag: "https://football.fansunitedassets.com/country/3a931055-8e19-11eb-b60d-42010a84003b.png"
                  },
                  name: "International"
               },
               gender: "male",
               assets: {
                  logo: "https://football.fansunitedassets.com/competition/421093a8-8c4e-11eb-aff3-42010a8400d1.png"
               },
               type: "cup",
               name: "UEFA Nations League"
            }
         },
         status: {
            type: "finished",
            subType: "finished"
         }
      }
   ]
}

Get match by ID

Method: getMatchById(ID, disableCache?)

Returns the all the match information available for the specified ID. Includes match info, lineups, timeline and statistics.
If no value is passed to disableCache (undefined) it will be set to false.

sdk.football.getMatchById("fb:m:721159093").then((responseObject) => {
    // do something with responseObject
});

Example result

{
   id: "fb:m:721159093",
   kickoffAt: "2021-12-11T17:30:00Z",
   finishedAt: "2021-12-11T19:22:02Z",
   updatedAt: "2021-12-15T20:08:30Z",
   availableMarkets: ["FT_1X2", "BOTH_TEAMS_SCORE"],
   homeTeam: {
      id: "fb:t:8111",
      country: {
         id: "fb:cnt:1522",
         alias: null,
         countryCode: "ENG",
         assets: {
            flag: "https://football.fansunitedassets.com/country/3a930dd8-8e19-11eb-b60d-42010a84003b.png"
         },
         name: "England"
      },
      gender: "male",
      assets: {
         logo: "https://football.fansunitedassets.com/team/41f7b806-8c4e-11eb-aff3-42010a8400d1.png"
      },
      name: "Norwich City",
      code: "NOR",
      national: false,
      fullName: null,
      shortName: null
   },
   awayTeam: {
      id: "fb:t:8102",
      country: {
         id: "fb:cnt:1522",
         alias: null,
         countryCode: "ENG",
         assets: {
            flag: "https://football.fansunitedassets.com/country/3a930dd8-8e19-11eb-b60d-42010a84003b.png"
         },
         name: "England"
      },
      gender: "male",
      assets: {
         logo: "https://football.fansunitedassets.com/team/41fba11d-8c4e-11eb-aff3-42010a8400d1.png"
      },
      name: "Manchester United",
      code: "MNU",
      national: false,
      fullName: null,
      shortName: null
   },
   lineupsConfirmed: true,
   startedAt: "2021-12-11T18:31:37Z",
   minute: null,
   scores: {
      ftScore: {
         homeGoals: 0,
         awayGoals: 1
      },
      htScore: {
         homeGoals: 0,
         awayGoals: 0
      },
      aetScore: {
         homeGoals: null,
         awayGoals: null
      },
      aggScore: {
         homeGoals: null,
         awayGoals: null
      },
      penScore: {
         homeGoals: null,
         awayGoals: null
      }
   },
   stats: {
      corners: {
         homeTeam: 8,
         awayTeam: 6
      },
      cornersFirstHalf: {
         homeTeam: 4,
         awayTeam: 3,
      },
      cornersSecondHalf: {
         homeTeam: 4,
         awayTeam: 3,
      },
      cornersExtraTime: {
         homeTeam: null,
         awayTeam: null,
      },
      crosses: {
         homeTeam: 26,
         awayTeam: 12
      },
      crossesFirstHalf: {
         homeTeam: 13,
         awayTeam: 6
      },
      crossesSecondHalf: {
         homeTeam: 13
         awayTeam: 6,
      },
      crossesExtraTime: {
         homeTeam: null,
         awayTeam: null,
      },
      offside: {
         homeTeam: 0,
         awayTeam: 1
      },
      offsideFirstHalf: {
         homeTeam: 0,
         awayTeam: 0
      },
      offsideSecondHalf: {
         homeTeam:0
         awayTeam: 1,
      },
      offsideExtraTime: {
         homeTeam: null,
         awayTeam: null,
      },
      shotsOn: {
         homeTeam: 5,
         awayTeam: 5
      },
      shotsOnFirstHalf: {
         homeTeam: 2,
         awayTeam: 2
      },
      shotsOnSecondHalf: {
         homeTeam:3
         awayTeam: 3,
      },
      shotsOnExtraTime: {
         homeTeam: null,
         awayTeam: null,
      },
      throwIn: {
         homeTeam: 23,
         awayTeam: 17
      },
      throwInFirstHalf: {
         homeTeam: 11,
         awayTeam: 13
      },
      throwInSecondHalf: {
         homeTeam:12
         awayTeam: 14,
      },
      throwInExtraTime: {
         homeTeam: null,
         awayTeam: null,
      },
      redCards: {
         homeTeam: 0,
         awayTeam: 0
      },
      redCardsFirstHalf: {
         homeTeam: 0,
         awayTeam: 0
      },
      redCardsSecondHalf: {
         homeTeam:0
         awayTeam: 0,
      },
      redCardsExtraTime: {
         homeTeam: null,
         awayTeam: null,
      },
      shotsOff: {
         homeTeam: 2,
         awayTeam: 5
      },
      shotsOffFirstHalf: {
         homeTeam: 1,
         awayTeam: 2
      },
      shotsOffSecondHalf: {
         homeTeam: 1,
         awayTeam: 3
      },
      shotsOffExtraTime: {
         homeTeam: null,
         awayTeam: null,
      },
      goalKicks: {
         homeTeam: 6,
         awayTeam: 6
      },
      goalKicksFirstHalf: {
         homeTeam: 3,
         awayTeam: 3
      },
      goalKicksSecondHalf: {
         homeTeam: 3,
         awayTeam: 3
      },
      goalKicksExtraTime: {
         homeTeam: null,
         awayTeam: null,
      },
      possession: {
         homeTeam: 47,
         awayTeam: 53
      },
      possessionFirstHalf: {
         homeTeam: 47,
         awayTeam: 53
      },
      possessionSecondHalf: {
         homeTeam: 47,
         awayTeam: 53
      },
      possessionExtraTime: {
         homeTeam: null,
         awayTeam: null,
      },
      treatments: {
         homeTeam: 7,
         awayTeam: 2
      },
      treatmentsFirstHalf: {
         homeTeam: 3,
         awayTeam: 1
      },
      treatmentsSecondHalf: {
         homeTeam: 3,
         awayTeam: 1
      },
      treatmentsExtraTime: {
         homeTeam: null,
         awayTeam: null,
      },
      yellowCards: {
         homeTeam: 1,
         awayTeam: 1
      },
      yellowCardsFirstHalf: {
         homeTeam: 1,
         awayTeam: 1
      },
      yellowCardsSecondHalf: {
         homeTeam: 0,
         awayTeam: 0
      },
      yellowCardsExtraTime: {
         homeTeam: null,
         awayTeam: null,
      },
      shotsBlocked: {
         homeTeam: 3,
         awayTeam: 3
      },
      shotsBlockedFirstHalf: {
         homeTeam: 1,
         awayTeam: 1
      },
      shotsBlockedSecondHalf: {
         homeTeam: 2,
         awayTeam: 2
      },
      shotsBlockedExtraTime: {
         homeTeam: null,
         awayTeam: null,
      },
      substitutions: {
         homeTeam: 3,
         awayTeam: 3
      },
      substitutionsFirstHalf: {
         homeTeam: 0,
         awayTeam: 0
      },
      substitutionsSecondHalf: {
         homeTeam: 3,
         awayTeam: 3
      },
      substitutionsExtraTime: {
         homeTeam: null,
         awayTeam: null,
      },
      counterAttacks: {
         homeTeam: 0,
         awayTeam: 2
      },
      counterAttacksFirstHalf: {
         homeTeam: 0,
         awayTeam: 1
      },
      counterAttacksSecondHalf: {
         homeTeam: 0,
         awayTeam: 1
      },
      counterAttacksExtraTime: {
         homeTeam: null,
         awayTeam: null,
      },
      foulsCommitted: {
         homeTeam: 6,
         awayTeam: 17
      },
      foulsCommittedFirstHalf: {
         homeTeam: 3,
         awayTeam: 8
      },
      foulsCommittedSecondHalf: {
         homeTeam: 3,
         awayTeam: 9
      },
      foulsCommittedExtraTime: {
         homeTeam: null,
         awayTeam: null,
      },
   },
   context: {
      competition: {
         id: "fb:c:3",
         country: {
            id: "fb:cnt:1522",
            alias: null,
            countryCode: "ENG",
            assets: {
               flag: "https://football.fansunitedassets.com/country/3a930dd8-8e19-11eb-b60d-42010a84003b.png"
            },
            name: "England"
         },
         gender: "male",
         assets: {
            logo: "https://football.fansunitedassets.com/competition/42108c2a-8c4e-11eb-aff3-42010a8400d1.png"
         },
         type: "league",
         name: "Premier League"
      }
   },
   timeline: [
      {
         minute: "21",
         type: "substitution",
         teamId: "fb:t:8111",
         player: {
            id: "fb:p:42943",
            name: "Grant Hanley",
            position: "defender",
            assets: {
               headshot: "https://football.fansunitedassets.com/player/41f9a74f-8c4e-11eb-aff3-42010a8400d1.jpeg"
            },
            type: "substitution",
            shirtNumber: 5
         },
         relatedPlayer: {
            id: "fb:p:473708",
            name: "Jacob Lungi Soerensen",
            position: "midfielder",
            assets: null,
            type: "substitution",
            shirtNumber: 19
         },
         updatedAt: "2021-12-15T20:08:23Z"
      },
      {
         minute: "75",
         type: "penalty_goal",
         teamId: "fb:t:8102",
         player: {
            id: "fb:p:43400",
            name: "Cristiano Ronaldo",
            position: "forward",
            assets: {
               headshot: "https://football.fansunitedassets.com/player/41ff1b20-8c4e-11eb-aff3-42010a8400d1.jpeg"
            },
            type: "penalty_goal",
            shirtNumber: 7
         },
         relatedPlayer: null,
         updatedAt: "2021-12-15T20:08:23Z"
      },
      {
         minute: "77",
         type: "yellow_card",
         teamId: "fb:t:8102",
         player: {
            id: "fb:p:4163542",
            name: "Diogo Dalot",
            position: "defender",
            assets: null,
            type: "yellow_card",
            shirtNumber: 20
         },
         relatedPlayer: null,
         updatedAt: "2021-12-15T20:08:23Z"
      }
   ],
   status: {
      type: "finished",
      subType: "finished"
   },
   lineups: {
      homeTeam: {
         players: [
            {
               id: "fb:p:4212098",
               name: "Brandon Williams",
               position: "defender",
               assets: null,
               type: "unknown",
               shirtNumber: 21
            },
            {
               id: "fb:p:476863",
               name: "Mathias Normann",
               position: "midfielder",
               assets: null,
               type: "miss",
               shirtNumber: 16
            },
            {
               id: "fb:p:42082",
               name: "Sam Byram",
               position: "defender",
               assets: {
                  headshot: "https://football.fansunitedassets.com/player/4200e5bf-8c4e-11eb-aff3-42010a8400d1.jpeg"
               },
               type: "sub",
               shirtNumber: 3
            },
            {
               id: "fb:p:42380",
               name: "Tim Krul",
               position: "keeper",
               assets: {
                  headshot: "https://football.fansunitedassets.com/player/421523ce-8c4e-11eb-aff3-42010a8400d1.jpeg"
               },
               type: "start",
               shirtNumber: 1
            }
         ]
      },
      awayTeam: {
         players: [
            {
               id: "fb:p:43949",
               name: "Raphael Varane",
               position: "defender",
               assets: {
                  headshot: "https://football.fansunitedassets.com/player/4216a724-8c4e-11eb-aff3-42010a8400d1.jpeg"
               },
               type: "miss",
               shirtNumber: 19
            },
            {
               id: "fb:p:4158170",
               name: "Aaron Wan-Bissaka",
               position: "defender",
               assets: null,
               type: "unknown",
               shirtNumber: 29
            },
            {
               id: "fb:p:41601",
               name: "David De Gea",
               position: "keeper",
               assets: {
                  headshot: "https://football.fansunitedassets.com/player/420772b2-8c4e-11eb-aff3-42010a8400d1.jpeg"
               },
               type: "start",
               shirtNumber: 1
            },
            {
               id: "fb:p:41914",
               name: "Eric Bailly",
               position: "defender",
               assets: {
                  headshot: "https://football.fansunitedassets.com/player/42146537-8c4e-11eb-aff3-42010a8400d1.jpeg"
               },
               type: "sub",
               shirtNumber: 3
            }
         ]
      }
   }
}

Get next match for team

Method: getNextMatchForTeam(teamId, disableCache?)

This method is an alias of getMatchById(). However, instead of accepting a match ID, it accepts a team ID and returns
the next match the team is playing.
If no value is passed to disableCache (undefined) it will be set to false.

sdk.football.getNextMatchForTeam("fb:t:8102").then((responseObject) => {
    // do something with responseObject
});

Example result

// See getMatchById(ID)

Get previous match for team

Method: getPrevMatchForTeam(teamId, disableCache?)

This method is an alias of getMatchById(). However, instead of accepting a match ID, it accepts a team ID and returns
the previous match the team is playing.
If no value is passed to disableCache (undefined) it will be set to false.

sdk.football.getPrevMatchForTeam("fb:t:8102").then((responseObject) => {
    // do something with responseObject
});

Example result

// See getMatchById(ID)

Get next match for player

Method: getNextMatchForPlayer(playerId, disableCache?)

This method is an alias of getMatchById(). However, instead of accepting a match ID, it accepts a player ID and returns
the next match for any of the teams the player plays for.
If no value is passed to disableCache (undefined) it will be set to false.

sdk.football.getNextMatchForPlayer("fb:p:43400").then((responseObject) => {
    // do something with responseObject
});

Example result

// See getMatchById(ID)

Get previous match for player

Method: getPrevMatchForPlayer(playerId, disableCache?)

This method is an alias of getMatchById(). However, instead of accepting a match ID, it accepts a player ID and returns
the previous match for any of the teams the player plays for.
If no value is passed to disableCache (undefined) it will be set to false.

sdk.football.getPrevMatchForPlayer("fb:p:43400").then((responseObject) => {
    // do something with responseObject
});

Example result

// See getMatchById(ID)

Other methods

Get countries

Method: getCountries(disableCache?)

This method returns all the countries available in the Football API.
If no value is passed to disableCache (undefined) it will be set to false.

sdk.football.getCountries().then((responseObject) => {
    // do something with responseObject
});

Example result

[
   {
      id: "fb:cnt:23362",
      alias: null,
      countryCode: "AFG",
      assets: null,
      name: "Afghanistan"
   },
   {
      id: "fb:cnt:476",
      alias: null,
      countryCode: "ALB",
      assets: {
         flag: "https://football.fansunitedassets.com/country/3a92fe18-8e19-11eb-b60d-42010a84003b.png"
      },
      name: "Albania"
   },
   {
      id: "fb:cnt:63",
      alias: null,
      countryCode: "DZA",
      assets: {
         flag: "https://football.fansunitedassets.com/country/3a92ff61-8e19-11eb-b60d-42010a84003b.png"
      },
      name: "Algeria"
   }
]

Search

Method: search(query, entities, disableCache?)

This method searches the Football API for football entities with names that match the requested query parameter.

Available parameters:

  • query: string
  • entities: an array of enum strings. Options are "competitions", "teams", "players"
  • scope: an array of ids of all competitions supported by Fans United.
  • disableCache: boolean. Default false. Disables cache on the request
sdk.football.search({query:"Premier", entities: ["competitions", "teams", "players"]}, scope: ["fb:c:3"]).then((responseObject) => {
    // do something with responseObject
});

Example result

{
   teams: [
      {
         id: "fb:t:816579",
         country: {
            id: "fb:cnt:952",
            alias: "United States",
            countryCode: "USA",
            assets: {
               flag: "https://football.fansunitedassets.com/country/3a934b81-8e19-11eb-b60d-42010a84003b.png"
            },
            name: "USA"
         },
         gender: "male",
         assets: null,
         name: "Mass Premier Soccer",
         code: "MPS",
         national: false,
         fullName: null,
         shortName: null
      }
   ],
   players: [],
   competitions: [
      {
         id: "fb:c:3",
         country: {
            id: "fb:cnt:1522",
            alias: null,
            countryCode: "ENG",
            assets: {
               flag: "https://football.fansunitedassets.com/country/3a930dd8-8e19-11eb-b60d-42010a84003b.png"
            },
            name: "England"
         },
         gender: "male",
         assets: {
            logo: "https://football.fansunitedassets.com/competition/42108c2a-8c4e-11eb-aff3-42010a8400d1.png"
         },
         type: "league",
         name: "Premier League"
      }
   ]
}