Jump to:

  1. Endpoint
  2. Response
  3. Event Coordinates
  4. Event Types

This football API endpoint will only provide data for popular competitions like the FIFA World Cup, Copa America, or the UEFA Euro and you need to purchase a specific commentary package to gain access to this kind of data.

All clients that purchase the commentary football api package also get a list of icons visually representing each event type. You can find the full list of the icons at the end of the page.

This football API endpoint supports 31 languages

The events commentary football api endpoint allows you to get detailed view of 50+ matches events from a simple throw in to goals scored. Besides the event itself, you will also receive metadata about the event like: players involved, team involved, location on the pitch, timing of the event, and a textual representation of the event in 31 languages.


ENDPOINT


GET:

To test the API endpoint you can use the following matches ids from the UEFA Nations League:
334919 Croatia - France
335217 Denmark - Croatia
335680 France - Croatia (this is the match showing on our commentary demonstration page)


NameTypeRequiredExampleDescription
from_secondNumber500The second since the start of the match since which we want to get all following commentary events. Omit this parameter if you want all events since the beginning of the match
langStringfrThe 2 letter iso code of the language in which we want the data. You can choose from 31 languages. If you omit this parameter the data will default to English.
match_idNumber1335680The id of the match which commentary data we want to get
to_secondNumber600The second until which we want to get all preceding commentary events. Omit this parameter if you want all events until the end of the match.

RESPONSE


Here is an example response of the match event commentary. It is an excerpt from the match between France and Croatia played during the UEFA Nations League.


{
    "success": true,
    "data": {
        "commentary": [
            {
                "id": 874,
                "match_id": 335680,
                "event_type": "WINNER",
                "minute": "FT",
                "second": "FT",
                "match_second": 6789,
                "comment": "",
                "pos_x": 0,
                "pos_y": 0,
                "side": "a",
                "created_at": "2022-06-29 14:52:01",
                "updated_at": "0",
                "text": "Croatia is the match winner",
                "team": {
                    "id": 211,
                    "name": "Croatia",
                    "stadium": "Stadion Maksimir",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.live-score-api.com\/teams\/e0e69718246798fdfd5e88308dfca5b6.png"
                },
                "player": [],
                "player_2": []
            },
            {
                "id": 871,
                "match_id": 335680,
                "event_type": "GOAL_KICK_TAKEN",
                "minute": "90+",
                "second": "276",
                "match_second": 6782,
                "comment": "",
                "pos_x": 5,
                "pos_y": 62,
                "side": "",
                "created_at": "2022-06-13 20:38:36",
                "updated_at": null,
                "text": "Ivica Ivusic takes the goal kick",
                "team": {
                    "id": 211,
                    "name": "Croatia",
                    "stadium": "Stadion Maksimir",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.live-score-api.com\/teams\/e0e69718246798fdfd5e88308dfca5b6.png"
                },
                "player": {
                    "id": 13448,
                    "name": "Ivica Ivusic"
                },
                "player_2": []
            },
            {
                "id": 863,
                "match_id": 335680,
                "event_type": "SUBSTITUTION",
                "minute": "90",
                "second": "40",
                "match_second": 6546,
                "comment": "",
                "pos_x": 0,
                "pos_y": 0,
                "side": "",
                "created_at": "2022-06-13 20:34:43",
                "updated_at": null,
                "text": "Substitution in the team of Croatia. Luka Sucic replaces Mateo Kovacic",
                "team": {
                    "id": 211,
                    "name": "Croatia",
                    "stadium": "Stadion Maksimir",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.live-score-api.com\/teams\/e0e69718246798fdfd5e88308dfca5b6.png"
                },
                "player": {
                    "id": 44535,
                    "name": "Luka Sucic"
                },
                "player_2": {
                    "id": 4346,
                    "name": "Mateo Kovacic"
                }
            }
        ]
    }
}


To demonstrate the content of a commentary data event we will take the substitution in the 90th minute when Luka Sucic replaced Mateo Kovacic for Croatia. This type of event contains data in all fields available.


In some cases as data is arriving or just because the type of event does not support them, certain fields might be empty and then become populated with following data updates

NameTypeExampleDescription
commentStringThis field is used when additional clarification for the event is provided. For example, when there are VAR decisions.
created_atDatetime2022-06-13 20:34:43The UTC date time when the event was created in our database
event_typeStringSUBSTITUTIONThe type of the event that happened there are 50+ event types listed in a section further down this page.
idNumber863The id of the commentary event
match_idNumber335680The id of the match that holds the event
match_secondNumber6546This is the absolute number of seconds that have passed since the beginning of the match (including the half time break, extra time break, break when awaiting penalties)
minuteString90A textual representation of the match minute when the event occurred. It could digits like 87, 90+ during added time or even HT if something happens during the break like a SUBSTITUTION
playerObject{}An object holding the information about a player. It has the structure of our standard player object.
player_2Object{}An object holding the information about a player. It has the structure of our standard player object.
pos_xNumber0The % of the field length from the top left corner until where the event occurred. Some events do not have coordinates like SUBSTITUTION
pos_yNumber0The % of the field height from the top throw in line until where the event occurred. Some events do not have coordinates like SUBSTITUTION
secondNumber40Usually between 0 and 59. It can be greater than 59 when we are in the ADDITIONAL_TIME Then the combination of the minute and second would look like this 90+ 250
sideCharah or a Similarly to the matches events data, this field indicates whether the home team or away team is the one involved in the event. Some events like ADDITIONAL_TIME do not have a side
teamObject{}An object holding the information about the team for which the player is competing. It has the structure of our standard team object.
textStringSubstitution in the team of Croatia. Luka Sucic replaces Mateo KovacicA human friendly readable representation of the event. It is in one of the 31 languages that you have chosen.
updated_atDatetime2022-06-13 20:34:43If there are consecutive updates on the commentary event, this field will contain the UTC date and time when the update was made.

EVENT COORDINATES


football API commentary event position
Since football pitches differentiate in dimensions, we at live score api adopted the percentage approach when it comes to events coordinates. The beginning of the coordinate system is the top left corner of the football pitch at coordinates (0, 0). Then the horizontal (x axis) and vertical (y axis) span from 0 to 100. This concludes at the bottom right corner of the football pitch at coordinates (100,100).

Therefore, on the image you can see that the centre spot is at coordinates (50,50). This will allow you to visually represent the event on any size and orientation of a field image.

We have also illustrated an event location at (33, 19) at the top left quadrant of the football pitch to illustrate the way the coordinates progress from (0, 0) to (33, 19) to (50, 50) and finally to (98, 98).


EVENT TYPES


Name Type Icon Description
Added time ADDITIONAL_TIME football api commentary match Added time The additional time to be added at the end of the half.
The comment field will indicate the number of minutes added.
Containing the ball CONTAINS_BALL football api commentary match Containing the ball When a team holds on to the ball for a longer period of time.
The team and team.name indicate the team is controlling the ball.
Corner kick awarded CORNER_KICK_AWARDED football api commentary match Corner kick awarded When a team wins a corner kick at the opposite end of the field.
The team_id and team.name indicate the team that is going to take the corner kick.
Corner kick taken CORNER_KICK_TAKEN football api commentary match Corner kick taken When a player takes the corner kick.
The player_id and player.name indicate the player that took the corner.
The team_id and team.name indicate for which team the player plays.
Crossbar hit CROSSBAR_HIT football api commentary match Crossbar hit When the ball hits the crossbar.
The player_id and player.name indicate the player that kicked/headed the ball into the crossbar of the goal.
The team_id and team.name indicate for which team the player plays.
Draw match DRAW football api commentary match Draw match When the match ends in a draw.
Extra time break EXTRA_TIME_HALF_TIME football api commentary match Extra time break The break between the two 15 minutes extra time from 90 to 120 minutes.
Extra time over EXTRA_TIME_OVER football api commentary match Extra time over End of the extra time 120th minute.
Second extra time period start EXTRA_TIME_SECOND_HALF_START football api commentary match Second extra time period start The beginning of the second half of 15 minutes from 105 to 120 minute.
The team_id and team.name will provide information on which team starts with the ball.
Extra time starts EXTRA_TIME_START football api commentary match Extra time starts The beginning of the extra time 90 to 105th minutes.
The team_id and team.name will provide information on which team starts with the ball.
Half time break starts FIRST_HALF_OVER football api commentary match Half time break starts The end of the first half after 45 minutes.
Foul (Rule violation) FOUL_COMMITTED football api commentary match Foul (Rule violation) When a player commits a foul or breaks the rules in any other way.
The player_id and player.name indicate the player that did the infringement.
The team_id and team.name indicate for which team the player plays.
Free kick taken FREE_KICK_TAKEN football api commentary match Free kick taken When a player takes the free kick.
The player_id and player.name indicate the player that took the free kick.
The team_id and team.name indicate for which team the player plays.
Goal scored GOAL football api commentary match Goal scored When a goal is scored.
The player_id and player.name indicate the player that scored the goal.
The team_id and team.name indicate for which team the player plays.
The player2_id and player_2.name indicate the player that made the assist.
Goalkeeper save GOALKEEPER_SAVE football api commentary match Goalkeeper save When the goalkeeper makes a save.
The player_id and player.name indicate the goalkeeper that made the save.
The team_id and team.name indicate for which team the player plays.
Goal kick GOAL_KICK football api commentary match Goal kick When the ball goes out for a goal kick.
The team_id and team.name indicate the team that is going to take the goal kick.
Goal kick taken GOAL_KICK_TAKEN football api commentary match Goal kick taken When a player takes the goal kick.
The player_id and player.name indicate the player that took the goal kick.
The team_id and team.name indicate for which team the player plays.
Goal from a penalty GOAL_PENALTY football api commentary match Goal from a penalty When a goal is scored from a penalty during play time 1st to 120th minute.
The player_id and player.name indicate the player that converted the penalty.
The team_id and team.name indicate for which team the player plays.
Kick Off KICK_OFF football api commentary match Kick Off The kick off after a goal is scored.
The team_id and team.name will provide information on which team takes the kick off.
Match ended MATCH_ENDS football api commentary match Match ended When the matches ends 90th or 120th minute if there is extra time.
Match start MATCH_START football api commentary match Match start Marks the start of the match.
The team_id and team.name fields will contain the team that starts the match controlling the ball.
Match stopped (injury) MATCH_STOPPED_INJURY football api commentary match Match stopped (injury) When the match is stopped because of an injury.
Penalty missed MISSED_PENALTY football api commentary match Penalty missed When a player misses from the penalty spot in regular time 90th to 120th minute.
The team_id and team.name fields will contain the team that took the penalty.
The player_id and player.name fields will contain the player that missed the penalty.
Offside OFFSIDE football api commentary match Offside A player caught behind the line of defence.
The player_id and player.name indicate the player caught in an offside position.
The team_id and team.name indicate for which team the player plays.
Own goal OWN_GOAL football api commentary match Own goal When a player scores an own goal.
The player_id and player.name indicate the player that scored the own goal.
The team_id and team.name indicate for which team the player plays.
Penalty awarded PENALTY_AWARDED football api commentary match Penalty awarded When the referee points to the white spot in regular time 90th to 120th minute.
The team_id and team.name fields will contain the team that gets to take the penalty.
Penalty shootout overPENALTY_SHOOTOUT_ENDfootball api commentary match Penalty shootout overMarks the end of the penalty shootout and the end of the match.
Penalty shootout goalPENALTY_SHOOTOUT_GOALfootball api commentary match Penalty shootout goalWhen a player scores a goal during the penalty shootout.
Penalty shootout missPENALTY_SHOOTOUT_MISSfootball api commentary match Penalty shootout missWhen a player misses the goal during the penalty shootout.
Penalty shootout savedPENALTY_SHOOTOUT_SAVEDfootball api commentary match Penalty shootout savedWhen the goalkeepers save a shot during the penalty shootout.
Penalty shootout startPENALTY_SHOOTOUT_STARTfootball api commentary match Penalty shootout startMarks the beginning of the penalty shootout.
Penalty shootout takerPENALTY_SHOOTOUT_TAKERfootball api commentary match Penalty shootout takerThe player to take the next penalty.
Player warned PLAYER_WARNED football api commentary match Player warned When the referee has a discussion with a player.
The player_id and player.name indicate the player that was warned by the referee.
The team_id and team.name indicate for which team the player plays.
Post hit POST_HIT football api commentary match Post hit When the ball hits either side posts of the goal.
Team qualifies QUALIFIES_NEXT_ROUND football api commentary match Team qualifies When a team qualifies for the next round.
The team_id and team.name fields will contain the team that continues to the next round.
Red card RED_CARD football api commentary match Red card When a player receives a red card.
The player_id and player.name indicate the player that was sent off.
The team_id and team.name indicate for which team the player plays.
Red card cancelled RED_CARD_CANCELED football api commentary match Red card cancelled When the referee cancels the red card of a player after reviewing of a situation.
The player_id and player.name indicate the player that was brought back into the game.
The team_id and team.name indicate for which team the player plays.
Second half over SECOND_HALF_OVER football api commentary match Second half over Marks the end of the second half of play 45th to 90th minute.
Second half start SECOND_HALF_START football api commentary match Second half start Marks the beginning of the second half of play 45th to 90th minute.
The team_id and team.name fields will contain the team that starts the second half controlling the ball.
Shot blocked SHOT_BLOCKED football api commentary match Shot blocked When a shot at the goal is blocked by a player.
The player_id and player.name indicate the player that blocked the shot.
The team_id and team.name indicate for which team the blocker plays.
The player2_id and player_2.name indicate the player that took the shot.
Shot off target SHOT_OFF_TARGET football api commentary match Shot off target When a player makes a shot but the ball goes wide or high of the goal.
The player_id and player.name indicate the player that took the shot.
The team_id and team.name indicate for which team the player plays.
Shot on target SHOT_ON_TARGET football api commentary match Shot on target When a shot of a player ends on goal.
The player_id and player.name indicate the player that took the shot.
The team_id and team.name indicate for which team the player plays.
Substitution SUBSTITUTION football api commentary match Substitution When a manager makes a substitution of players.
The player_id and player.name indicate the player that comes into play.
The team_id and team.name indicate for which team that makes the change.
The player2_id and player_2.name indicate the player that is being replaced.
Throw in THROW_IN_AWARDED football api commentary match Throw in When the ball goes our for a throw in.
The team_id and team.name indicate the team that is going to take the throw in.
Throw in taken THROW_IN_TAKEN football api commentary match Throw in taken When a player does a throw in.
The player_id and player.name indicate the player that throws the ball back into play.
The team_id and team.name indicate for which team the player plays.
Treatment TREATMENT football api commentary match Treatment When a player is being treater by the medical staff.
The player_id and player.name indicate the player that is being treated by the medical staff.
The team_id and team.name indicate for which team the player plays.
VAR Goal review VAR_GOAL_REVIEW football api commentary match VAR Goal review When the video assistant referee is reviewing a goal situation.
VAR Penalty review VAR_PENALTY_REVIEW football api commentary match VAR Penalty review When the video assistant referee is reviewing a penalty situation.
VAR Red card review VAR_RED_CARD_REVIEW football api commentary match VAR Red card review When the video assistant referee is reviewing a red card situation.
VAR Review over VAR_REVIEW_OVER football api commentary match VAR Review over When the video assistant referee review is completed.
The comment field will contain the decision of the VAR.
Wasting time WASTING_TIME football api commentary match Wasting time When a team or player is performing actions causing time waste.
The team and team.name indicate the team is wasting time.
Water break WATER_BREAK football api commentary match Water break A break in the play for the players to cooldown and drink water.
Match winner WINNER football api commentary match Match winner Gives information about the winner of the match.
The team_id and team.name fields will contain the winning team.
Yellow card YELLOW_CARD football api commentary match Yellow card When a player receives an yellow card.
The player_id and player.name indicate the player that was booked by the referee.
The team_id and team.name indicate for which team the player plays.
Yellow card cancelled YELLOW_CARD_CANCELED football api commentary match Yellow card cancelled When the referee cancels the yellow card of a player after reviewing of a situation.
The player_id and player.name indicate the player whose booking was undone.
The team_id and team.name indicate for which team the player plays.
Second yellow card YELLOW_RED_CARD football api commentary match Second yellow card When a player receives a second yellow card and is sent off.
The player_id and player.name indicate the player was red carded.
The team_id and team.name indicate for which team the player plays.


Didn't find what you need?

Do no hesitate to contact us. We will get back to you as soon as possible.


Jump to: