Football data library

Welcome to our football data library. Here you will find all kinds of data fields and their definitions. We will include all statuses and definitions so you can have a perfect understanding of our Football API and the meaning of your data. You can also take a look at our documentation pages.

Documentation Pages

Fixture status definitions

Every fixture has a status. There are a lot of different statuses a fixture can have and every fixture moves through different statuses. For example, a fixture will have the status NS, which means not starting before starting a game. After the referee’s first whistle, the fixture will have the status LIVE, which means that the match is playing at that moment. When the referee whistles for halftime, the match will get a new status ‘HT’. After the break, the game will be LIVE again until the referee whistles for Full Time. The status will be ‘FT’. However, there are many more possibilities. Let’s take a closer look at them in the list below.

 

Regular statuses and definitions

NS Not Started. The initial status of a game. Every game has this status until the game gets started or Postponed.

LIVE Live. The game is currently inplay.

HT Half-Time. The game is currently in the half-time break.

FT Full-Time. The game has ended after 90 minutes. When a game goes into extra time, the FT status will be presented for a few seconds and then move to the BREAK status.

ET Extra-Time. The game is currently in extra time, can only happen in knockout games.

Pen_Live Penalty Shootout. ET status didn’t get a winner, penalties are taken to determine the winner

AET Finished After Extra Time. The game has finished after 120 minutes.

Break Regular time finished. Waiting for extra time (ET) or penalties (Pen_Live) to start.

FT_PEN Full-Time after Penalties. Finished after the penalty shootout.

Special statuses and definitions

CANCL Canceled. The game has been canceled.

POSTP PostPoned. The game has been postponed.

INT Interrupted. The game has been interrupted. A reason for an interruption can be bad weather.

ABAN Abandoned. The game has been abandoned and will continue at a later time or day.

SUSP. Suspended. The game has been suspended and will continue at a later time or day.

TBA. To Be Announced. The game does not have a confirmed date and time yet. It will be announced later on.

AWARDED Awarded. Winner is being decided externally.

DELAYED Delayed. The game is delayed so it will start later.

WO Walk Over. Awarding of a victory to a contestant because there are no other contestants.

AU Awaiting Updates. Can occur when there is a connectivity issue.

DELETED. Deleted. The game is not available anymore via regular API calls because it has been replaced. This can happen in leagues that have a lot of changes in their schedules. The games can still be retrieved by adding deleted=1 to your request so you can update your system properly

"events": {
           "data": [
               {
                   "id": 18165999001,
                   "team_id": "3468",
                   "type": "yellowcard",
                   "var_result": null,
                   "fixture_id": 18165999,
                   "player_id": 30289,
                   "player_name": "T. Kroos",
                   "related_player_id": null,
                   "related_player_name": null,
                   "minute": 22,
                   "extra_minute": null,
                   "reason": "Roughing",
                   "injuried": null,
                   "result": null,
                   "on_pitch": true
               },
               {
                   "id": 18165999002,
                   "team_id": "83",
                   "type": "yellowcard",
                   "var_result": null,
                   "fixture_id": 18165999,
                   "player_id": 26536,
                   "player_name": "F. de Jong",
                   "related_player_id": null,
                   "related_player_name": null,
                   "minute": 26,
                   "extra_minute": null,
                   "reason": "Roughing",
                   "injuried": null,
                   "result": null,
                   "on_pitch": true
               },
               {
                   "id": 18165999003,
                   "team_id": "83",
                   "type": "goal",
                   "var_result": null,
                   "fixture_id": 18165999,
                   "player_id": 31739,
                   "player_name": "P. Aubameyang",
                   "related_player_id": 32403,
                   "related_player_name": "O. Dembele",
                   "minute": 29,
                   "extra_minute": null,
                   "reason": null,
                   "injuried": null,
                   "result": "0-1",
                   "on_pitch": true
               },
               {
                   "id": 18165999004,
                   "team_id": "83",
                   "type": "yellowcard",
                   "var_result": null,
                   "fixture_id": 18165999,
                   "player_id": 185480,
                   "player_name": "S. Busquets",
                   "related_player_id": null,
                   "related_player_name": null,
                   "minute": 31,
                   "extra_minute": null,
                   "reason": "Holding",
                   "injuried": null,
                   "result": null,
                   "on_pitch": true
               },
               {
                   "id": 18165999005,
                   "team_id": "83",
                   "type": "goal",
                   "var_result": null,
                   "fixture_id": 18165999,
                   "player_id": 469717,
                   "player_name": "R. Araujo",
                   "related_player_id": 32403,
                   "related_player_name": "O. Dembele",
                   "minute": 38,
                   "extra_minute": null,
                   "reason": null,
                   "injuried": null,
                   "result": "0-2",
                   "on_pitch": true
               },


 

Event type definition

The most important in football are the events during a game. There are various event types, like a goal, card substitution, etc. In the table below you will find the types

  • Goal: A goal has been scored
  • Penalty: Penalty has been scored
  • Missed_penalty: Penalty has been missed
  • Own-goal: An own goal has been scored.
  • VAR: Information about VAR events like canceled goals etc
  • Yellowcard: Yellow card is given for a player
  • Yellowred: Second yellow card for player resulting in a red
  • Redcard: Direct red card
  • Substitution: A player got substituted and new player got in
  • Pen_shootout_goal: Penalty in penalty shootout has been scored
  • Pen_shootout_miss: Penalty in penalty shootout has been scored

 

 

VAR-events type definition

The first time the Video Assistant Referee is introduced in football on a worldwide event was at the 2016 FIFA Club World Cup. On 16 March 2018, the FIFA Council approved the use of the VAR for the 2018 FIFA World Cup in Russia.

Due to the introduction of the VAR on a worldwide scale, we do have VAR-event types. The types are: ‘Goal Disallowed’ and ‘Goal under review’.

​If there is a VAR-check, the event type is set to the ‘Goal under review‘. When the check is over, the event will be set to ‘Goal Disallowed‘ or the event type is set to ‘goal‘. ​This means that we don’t show which goals were under review after the goal was allowed.

League types

Sportmonks differentiates a couple of different league types. A list of possible types can be found below.

Domestic A league from one country. I.e The English Premier League, Serie A, La Liga etc.

Domestic_cup A cup from one country. I.e The F.A Cup, DFB Pokal, Coppa Italia etc.

International A league for international teams. I.e World Cup, European Championship, Copa America

Cup_international An international cup. I.e UEFA Champions League, Copa Libertadores, UEFA Europa League

Common standing rules

Promotion

Relegation

Relegation Play-off

Relegation Round

Possible Relegation

Next Round

Final Series

Promotion Play-off

Promotion Group

Final

Semi-finals

UEFA Champions League

UEFA Champions League Qualifiers

UEFA Europa League

UEFA Europa League Qualifiers

Championship Round

Championship Play-off

1st Phase

2nd Phase

CONMEBOL Libertadores

CONMEBOL Libertadores Qualifiers

CONMEBOL Sudamericana

CONMEBOL Sudamericana Qualifiers

Formations

Fixtures contain information about the participants line-ups. We have listed the most common formations.

4-2-3-1

4-3-3

4-4-2

4-1-4-1

3-5-2

3-4-3

4-3-1-2

4-4-1-1

3-4-2-1

3-4-1-2

5-3-2

5-4-1

4-5-1

3-1-4

4-2-2-2

4-3-2-1

3-5-1-1

4-1-3-2

4-1-2-3

3-3-1-3

3-3-3-1

5-2-3

4-2-4

3-2-4-1

4-2-1-3

2-3-4-1

5-2-2

Lineup example

The 4-3-3 is a common formation with four defenders, three midfielders and three attackers.

There are multiple ways of configuring this formation. For example, the midfield can play on a line like in the picture. However, a common variant is playing with one player in front of the other two midfielders or a little behind the others.  The deeper midfielder is the most common formation used in football.

 

 

Pitch types

The status of the pitch can also greatly influence the result of a game or the performance of the teams. A list of possible conditions is given below.

Good

Wet

Wet and Fast

Artificial Turf

Regular

Excellent

Snowy

Slow due to water

Uneven and|cutting up

Hard and Frozen