Guides

Football operations

Suggest Edits

Football operations are responsible for communicating with the Football API.
Each method that works with statistical data also converts your IDs to the desired ID provider for easier and quicker development.

The general design of the namespace follows this pattern:

val response = sdk.football().someMethod(...)
// do something with response object

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: List. 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: List. An array of player IDs. Returns all specified players.
  • limit: Int. Determines how many items per page there will be.
  • page: Int. The number of the page.
  • sortField: String. Determines the field used for the sorting.
  • sortOrder: String. Determines the sort order - asc or desc
val response: List<Player> = sdk.football().getPlayers(...)
val players: response.data
// Obtain pagination data
val pagination = response.meta.pagination

Get player by ID

Method: getPlayerById(playerId, 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.

val player = sdk.football().getPlayerById("fb:p:43400")

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.

val response = sdk.football().getTopPlayers()
val players: response.data

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: Int. Determines how many items per page there will be.
  • page: . The number of the page.
  • scope: List. 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: List. An array of team IDs. Returns all specified teams.
val response = sdk.football().getTeams()
val teams = response.data

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.

val response = sdk.football().getTeamById("fb:t:8102")
val team = response.data

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.

val response = sdk.football().getTopTeams()
val teams = response.data

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: List. An array of competition IDs. Returns all specified competitions.
val response = sdk.football().getCompetitions()
val competitions = response.data

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.

val response = sdk.football().getCompetitionById("fb:c:3")
val competition = response.data

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.

val response = sdk.football().getTopCompetitions()
val competitions = response.data

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: List. An array of country IDs. The result set will be limited to those countries.
  • competitionIds: List. An array of competition IDs. The result set will be limited to those competitions.
  • matchIds: List. 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: List. 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: Int. Determines how many items per page there will be.
  • page: Int. The number of the page.
  • sortField: String. Determines the field used for the sorting.
  • sortOrder: String. Determines the sort order - asc or desc
val response = sdk.football().getMatches(...)
val matches = response.data

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.

val response = sdk.football().getMatchById("fb:m:721159093")
val match = response.data

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.

val response = sdk.football().getNextMatchForTeam("fb:t:8102")
val match = response.data

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.

val response = sdk.football().getPrevMatchForTeam("fb:t:8102")
val match = response.data

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.

val response = sdk.football().getNextMatchForPlayer("fb:p:43400")
val match = response.data

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.

val response = sdk.football().getPrevMatchForPlayer("fb:p:43400")
val match = response.data

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.

val response = sdk.football().getCountries()
val countries = response.data

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
val response = sdk.football().search(...)
val searchResult: SearchResult = response.data

Updated about 1 year ago