Football API Documentation

Get the list of available timezone to be used in the fixtures endpoint.

This endpoint does not require any parameters.

Update Frequency : This endpoint contains all the existing timezone, it is not updated.

Recommended Calls : 1 call when you need.

Get the list of available countries for the leagues endpoint.

The name and code fields can be used in other endpoints as filters.

To get the flag of a country you have to call the following url: https://media.sportsdataapi.com/flags/{country_code}.svg

Examples available in Request samples "Use Cases".

All the parameters of this endpoint can be used together.

Update Frequency : This endpoint is updated each time a new league from a country not covered by the API is added.

Recommended Calls : 1 call per day.

Get the list of available leagues and cups.

The league id are unique in the API and leagues keep it across all seasons

To get the logo of a competition you have to call the following url: https://media.sportsdataapi.com/football/leagues/{league_id}.png

This endpoint also returns the coverage of each competition, which makes it possible to know what is available for that league or cup.

The values returned by the coverage indicate the data available at the moment you call the API, so for a competition that has not yet started, it is normal to have all the features set to False. This will be updated once the competition has started.

You can find all the leagues ids on our [Dashboard](https://dashboard.sportsdataapi.com/soccer/ids).

Example : `` "coverage": { "fixtures": { "events": true, "lineups": true, "statistics_fixtures": false, "statistics_players": false }, "standings": true, "players": true, "top_scorers": true, "top_assists": true, "top_cards": true, "injuries": true, "predictions": true, "odds": false }

` In this example we can deduce that the competition does not have the following features: statistics_fixtures, statistics_players, odds because it is set to False.

The coverage of a competition can vary from season to season and values set to True do not guarantee 100% data availability.

Some competitions, such as the friendlies, are exceptions to the coverage indicated in the leagues endpoint, and the data available may differ depending on the match, including livescore, events, lineups, statistics and players.

Competitions are automatically renewed by the API when a new season is available. There may be a delay between the announcement of the official calendar and the availability of data in the API.

For Cup` competitions, fixtures are automatically added when the two participating teams are known. For example if the current phase is the 8th final, the quarter final will be added once the teams playing this phase are known.

Examples available in Request samples "Use Cases".

Most of the parameters of this endpoint can be used together.

Update Frequency : This endpoint is updated several times a day.

Recommended Calls : 1 call per hour.

Get the list of available seasons.

All seasons are only 4-digit keys, so for a league whose season is 2018-2019 like the English Premier League (EPL), the 2018-2019 season in the API will be 2018.

All seasons can be used in other endpoints as filters.

This endpoint does not require any parameters.

Update Frequency : This endpoint is updated each time a new league is added.

Recommended Calls : 1 call per day.

Get the list of available teams.

The team id are unique in the API and teams keep it among all the leagues/cups in which they participate.

To get the logo of a team you have to call the following url: https://media.sportsdataapi.com/football/teams/{team_id}.png

You can find all the teams ids on our [Dashboard](https://dashboard.sportsdataapi.com/soccer/ids/teams).

Examples available in Request samples "Use Cases".

All the parameters of this endpoint can be used together.

This endpoint requires at least one parameter.

Update Frequency : This endpoint is updated several times a week.

Recommended Calls : 1 call per day.

Tutorials : - [HOW TO GET ALL TEAMS AND PLAYERS FROM A LEAGUE ID](https://www.sportsdataapi.com/tutorials/4/how-to-get-all-teams-and-players-from-a-league-id)

Returns the statistics of a team in relation to a given competition and season.

It is possible to add the date parameter to calculate statistics from the beginning of the season to the given date. By default the API returns the statistics of all games played by the team for the competition and the season.

Update Frequency : This endpoint is updated twice a day.

Recommended Calls : 1 call per day for the teams who have at least one fixture during the day otherwise 1 call per week.

Here is an example of what can be achieved


Get the list of seasons available for a team.

Examples available in Request samples "Use Cases".

This endpoint requires at least one parameter.

Update Frequency : This endpoint is updated several times a week.

Recommended Calls : 1 call per day.

Get the list of countries available for the teams endpoint.

Update Frequency : This endpoint is updated several times a week.

Recommended Calls : 1 call per day.

Get the list of available venues.

The venue id are unique in the API.

To get the image of a venue you have to call the following url: https://media.sportsdataapi.com/football/venues/{venue_id}.png

Examples available in Request samples "Use Cases".

All the parameters of this endpoint can be used together.

This endpoint requires at least one parameter.

Update Frequency : This endpoint is updated several times a week.

Recommended Calls : 1 call per day.

Get the standings for a league or a team.

Return a table of one or more rankings according to the league / cup.

Some competitions have several rankings in a year, group phase, opening ranking, closing ranking etc…

Examples available in Request samples "Use Cases".

Most of the parameters of this endpoint can be used together.

Update Frequency : This endpoint is updated every hour.

Recommended Calls : 1 call per hour for the leagues or teams who have at least one fixture in progress otherwise 1 call per day.

Tutorials : - [HOW TO GET STANDINGS FOR ALL CURRENT SEASONS](https://www.sportsdataapi.com/tutorials/6/how-to-get-standings-for-all-current-seasons)

Get the rounds for a league or a cup.

The round can be used in endpoint fixtures as filters

Examples available in Request samples "Use Cases".

Update Frequency : This endpoint is updated every day.

Recommended Calls : 1 call per day.

For all requests to fixtures you can add the query parameter timezone to your request in order to retrieve the list of matches in the time zone of your choice like *“Europe/London“*

To know the list of available time zones you have to use the endpoint timezone.

Available fixtures status

| SHORT | LONG | TYPE | DESCRIPTION | | -------| --------------------------------| -----------|-------------------------------------------------------------------------------------------------------------------------------------------------------| | TBD | Time To Be Defined | Scheduled | Scheduled but date and time are not known | | NS | Not Started | Scheduled | | | 1H | First Half, Kick Off | In Play | First half in play | | HT | Halftime | In Play | Finished in the regular time | | 2H | Second Half, 2nd Half Started | In Play | Second half in play | | ET | Extra Time | In Play | Extra time in play | | BT | Break Time | In Play | Break during extra time | | P | Penalty In Progress | In Play | Penaly played after extra time | | SUSP | Match Suspended | In Play | Suspended by referee's decision, may be rescheduled another day | | INT | Match Interrupted | In Play | Interrupted by referee's decision, should resume in a few minutes | | FT | Match Finished | Finished | Finished in the regular time | | AET | Match Finished | Finished | Finished after extra time without going to the penalty shootout | | PEN | Match Finished | Finished | Finished after the penalty shootout | | PST | Match Postponed | Postponed | Postponed to another day, once the new date and time is known the status will change to Not Started | | CANC | Match Cancelled | Cancelled | Cancelled, match will not be played | | ABD | Match Abandoned | Abandoned | Abandoned for various reasons (Bad Weather, Safety, Floodlights, Playing Staff Or Referees), Can be rescheduled or not, it depends on the competition | | AWD | Technical Loss | Not Played | | | WO | WalkOver | Not Played | Victory by forfeit or absence of competitor | | LIVE | In Progress | In Play | Used in very rare cases. It indicates a fixture in progress but the data indicating the half-time or elapsed time are not available |

Fixtures with the status TBD may indicate an incorrect fixture date or time because the fixture date or time is not yet known or final. Fixtures with this status are checked and updated daily. The same applies to fixtures with the status PST, CANC.

The fixtures ids are unique and specific to each fixture. In no case an ID will change.

Not all competitions have livescore available and only have final result. In this case, the status remains in NS and will be updated in the minutes/hours following the match (this can take up to 48 hours, depending on the competition).

Although the data is updated every 15 seconds, depending on the competition there may be a delay between reality and the availability of data in the API.

Update Frequency : This endpoint is updated every 15 seconds.

Recommended Calls : 1 call per minute for the leagues, teams, fixtures who have at least one fixture in progress otherwise 1 call per day.

Here are several examples of what can be achieved


Get heads to heads between two teams.

Update Frequency : This endpoint is updated every 15 seconds.

Recommended Calls : 1 call per minute for the leagues, teams, fixtures who have at least one fixture in progress otherwise 1 call per day.

Here is an example of what can be achieved


Get the statistics for one fixture.

Available statistics

* Shots on Goal * Shots off Goal * Shots insidebox * Shots outsidebox * Total Shots * Blocked Shots * Fouls * Corner Kicks * Offsides * Ball Possession * Yellow Cards * Red Cards * Goalkeeper Saves * Total passes * Passes accurate * Passes %

Update Frequency : This endpoint is updated every minute.

Recommended Calls : 1 call every minute for the teams or fixtures who have at least one fixture in progress otherwise 1 call per day.

Here is an example of what can be achieved


Get the events from a fixture.

Available events

| TYPE | | | | | | ----------- | ------------- | --------- |-------- |-------- | | Goal | Normal Goal | Own Goal | Penalty | Missed Penalty | | Card | Yellow Card | Red card | | | | Subst | Substitution [1, 2, 3...] | | | | | Var | Goal cancelled | Penalty confirmed | | |

* *VAR events are available from the 2020-2021 season.*

Update Frequency : This endpoint is updated every 15 seconds.

Recommended Calls : 1 call per minute for the fixtures in progress otherwise 1 call per day.

You can also retrieve all the events of the fixtures in progress with to the endpoint fixtures?live=all

Here is an example of what can be achieved


Get the lineups for a fixture.

Lineups are available between 20 and 40 minutes before the fixture when the competition covers this feature. You can check this with the endpoint leagues and the coverage field.

It's possible that for some competitions the lineups are not available before the fixture, in this case, they are updated and available after the match with a variable delay depending on the competition.

Available datas

* Formation * Coach * Start XI * Substitutes

**Players' positions on the grid *

X = row and Y = column (X:Y)

Line 1 X being the one of the goal and then for each line this number is incremented. The column Y** will go from left to right, and incremented for each player of the line.

* As a new feature, some irregularities may occur, do not hesitate to report them on our public Roadmap

Update Frequency : This endpoint is updated every 15 minutes.

Recommended Calls : 1 call every 15 minutes for the fixtures in progress otherwise 1 call per day.

Here are several examples of what can be done



Get the players statistics from one fixture.

Update Frequency : This endpoint is updated every minute.

Recommended Calls : 1 call every minute for the fixtures in progress otherwise 1 call per day.

Get the list of players not participating in the fixtures for various reasons such as suspended, injured for example.

Being a new endpoint, the data is only available from April 2021.

There are two types:

* Missing Fixture : The player will not play the fixture. * Questionable : The information is not yet 100% sure, the player may eventually play the fixture.

Examples available in Request samples "Use Cases".

All the parameters of this endpoint can be used together.

This endpoint requires at least one parameter.

Update Frequency : This endpoint is updated every 4 hours.

Recommended Calls : 1 call per day.

Get predictions about a fixture.

The predictions are made using several algorithms including the poisson distribution, comparison of team statistics, last matches, players etc…

Bookmakers odds are not used to make these predictions

Also provides some comparative statistics between teams

Available Predictions * Match winner : Id of the team that can potentially win the fixture * Win or Draw : If True indicates that the designated team can win or draw * Under / Over : -1.5 / -2.5 / -3.5 / -4.5 / +1.5 / +2.5 / +3.5 / +4.5 * * Goals Home : -1.5 / -2.5 / -3.5 / -4.5 * * Goals Away -1.5 / -2.5 / -3.5 / -4.5 * * Advice *(Ex : Deportivo Santani or draws and -3.5 goals)*

* -1.5 means that there will be a maximum of 1.5 goals in the fixture, i.e : 1 goal

Update Frequency : This endpoint is updated every hour.

Recommended Calls : 1 call per hour for the fixtures in progress otherwise 1 call per day.

Here is an example of what can be achieved


Get all the information about the coachs and their careers.

To get the photo of a coach you have to call the following url: https://media.sportsdataapi.com/football/coachs/{coach_id}.png

Update Frequency : This endpoint is updated every day.

Recommended Calls : 1 call per day.

Get all available seasons for players statistics.

Update Frequency : This endpoint is updated every day.

Recommended Calls : 1 call per day.

Returns the list of all available players.

It is possible to call this endpoint without parameters, but you will need to use the pagination to get all available players.

To get the photo of a player you have to call the following url: https://media.sportsdataapi.com/football/players/{player_id}.png

This endpoint uses a pagination system, you can navigate between the different pages with to the page parameter.

Pagination : 250 results per page.

Update Frequency : This endpoint is updated several times a week.

Recommended Calls : 1 call per week.

Get players statistics.

This endpoint returns the players for whom the profile and statistics data are available. Note that it is possible that a player has statistics for 2 teams in the same season in case of transfers.

The statistics are calculated according to the team id, league id and season.

You can find the available seasons by using the endpoint players/seasons.

To get the squads of the teams it is better to use the endpoint players/squads.

The players id are unique in the API and players keep it among all the teams they have been in.

In this endpoint you have the rating field, which is the rating of the player according to a match or a season. This data is calculated according to the performance of the player in relation to the other players of the game or the season who occupy the same position *(Attacker, defender, goal...)*. There are different algorithms that take into account the position of the player and assign points according to his performance.

To get the photo of a player you have to call the following url: https://media.sportsdataapi.com/football/players/{player_id}.png

This endpoint uses a pagination system, you can navigate between the different pages with to the page parameter.

Pagination : 20 results per page.

Update Frequency : This endpoint is updated several times a week.

Recommended Calls : 1 call per day.

Tutorials : - [HOW TO GET ALL TEAMS AND PLAYERS FROM A LEAGUE ID](https://www.sportsdataapi.com/tutorials/4/how-to-get-all-teams-and-players-from-a-league-id)

Return the current squad of a team when the team parameter is used. When the player parameter is used the endpoint returns the set of teams associated with the player.

The response format is the same regardless of the parameter sent.

This endpoint requires at least one parameter.

Update Frequency : This endpoint is updated several times a week.

Recommended Calls : 1 call per week.

Returns the list of teams and seasons in which the player played during his career.

This endpoint requires at least one parameter.

Update Frequency : This endpoint is updated several times a week.

Recommended Calls : 1 call per week.

Get the 20 best players for a league or cup.

How it is calculated:

* 1 : The player that has scored the higher number of goals * 2 : The player that has scored the fewer number of penalties * 3 : The player that has delivered the higher number of goal assists * 4 : The player that scored their goals in the higher number of matches * 5 : The player that played the fewer minutes * 6 : The player that plays for the team placed higher on the table * 7 : The player that received the fewer number of red cards * 8 : The player that received the fewer number of yellow cards

Update Frequency : This endpoint is updated several times a week.

Recommended Calls : 1 call per day.

Get the 20 best players assists for a league or cup.

How it is calculated:

* 1 : The player that has delivered the higher number of goal assists * 2 : The player that has scored the higher number of goals * 3 : The player that has scored the fewer number of penalties * 4 : The player that assists in the higher number of matches * 5 : The player that played the fewer minutes * 6 : The player that received the fewer number of red cards * 7 : The player that received the fewer number of yellow cards

Update Frequency : This endpoint is updated several times a week.

Recommended Calls : 1 call per day.

Get the 20 players with the most yellow cards for a league or cup.

How it is calculated:

* 1 : The player that received the higher number of yellow cards * 2 : The player that received the higher number of red cards * 3 : The player that assists in the higher number of matches * 4 : The player that played the fewer minutes

Update Frequency : This endpoint is updated several times a week.

Recommended Calls : 1 call per day.

Get the 20 players with the most red cards for a league or cup.

How it is calculated:

* 1 : The player that received the higher number of red cards * 2 : The player that received the higher number of yellow cards * 3 : The player that assists in the higher number of matches * 4 : The player that played the fewer minutes

Update Frequency : This endpoint is updated several times a week.

Recommended Calls : 1 call per day.

Get all available transfers for players and teams

Update Frequency : This endpoint is updated several times a week.

Recommended Calls : 1 call per day.

Get all available trophies for a player or a coach.

Update Frequency : This endpoint is updated several times a week.

Recommended Calls : 1 call per day.

Get all available sidelined for a player or a coach.

Update Frequency : This endpoint is updated several times a week.

Recommended Calls : 1 call per day.

This endpoint returns in-play odds for fixtures in progress.

Fixtures are added between 15 and 5 minutes before the start of the fixture. Once the fixture is over they are removed from the endpoint between 5 and 20 minutes. No history is stored. So fixtures that are about to start, fixtures in progress and fixtures that have just ended are available in this endpoint.

Update Frequency : This endpoint is updated every 5 seconds.*

* This value can change in the range of 5 to 60 seconds

INFORMATIONS ABOUT STATUS `` "status": { "stopped": false, // True if the fixture is stopped by the referee for X reason "blocked": false, // True if bets on this fixture are temporarily blocked "finished": false // True if the fixture has not started or if it is finished }, `

INFORMATIONS ABOUT VALUES

When several identical values exist for the same bet the main field is set to True for the bet being considered, the others will have the value False.

The main field will be set to True only if several identical values exist for the same bet.

When a value is unique for a bet the main value will always be False or null.

Example below : ` "id": 36, "name": "Over/Under Line", "values": [ { "value": "Over", "odd": "1.975", "handicap": "2", "main": true, // Bet to consider "suspended": false // True if this bet is temporarily suspended }, { "value": "Over", "odd": "3.45", "handicap": "2", "main": false, // Bet to no consider "suspended": false }, ] ``

Get all available bets for in-play odds.

All bets id can be used in endpoint odds/live as filters, but are not compatible with endpoint odds for pre-match odds.

Update Frequency : This endpoint is updated every 60 seconds.

Get odds from fixtures, leagues or date.

This endpoint uses a pagination system, you can navigate between the different pages with to the page parameter.

Pagination : 10 results per page.

We provide pre-match odds between 1 and 14 days before the fixture.

We keep a 7-days history *(The availability of odds may vary according to the leagues, seasons, fixtures and bookmakers)*

Update Frequency : This endpoint is updated every 3 hours.

Recommended Calls : 1 call every 3 hours.

Get the list of available fixtures id for the endpoint odds.

All fixtures, leagues id and date can be used in endpoint odds as filters.

This endpoint uses a pagination system, you can navigate between the different pages with to the page parameter.

Pagination : 100 results per page.

Update Frequency : This endpoint is updated every day.

Recommended Calls : 1 call per day.

Get all available bookmakers.

All bookmakers id can be used in endpoint odds as filters.

Update Frequency : This endpoint is updated several times a week.

Recommended Calls : 1 call per day.

Get all available bets for pre-match odds.

All bets id can be used in endpoint odds as filters, but are not compatible with endpoint odds/live for in-play odds.

Update Frequency : This endpoint is updated several times a week.

Recommended Calls : 1 call per day.