Match Commentary

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

On this reference page, we explain how you can obtain the matches events commentary.

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

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)

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.

EVENT COORDINATES

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		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		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		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		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		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		When the match ends in a draw.
Extra time break	EXTRA_TIME_HALF_TIME		The break between the two 15 minutes extra time from 90 to 120 minutes.
Extra time over	EXTRA_TIME_OVER		End of the extra time 120th minute.
Second extra time period start	EXTRA_TIME_SECOND_HALF_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		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		The end of the first half after 45 minutes.
Foul (Rule violation)	FOUL_COMMITTED		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		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		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		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		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		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		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		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		When the matches ends 90th or 120th minute if there is extra time.
Match start	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		When the match is stopped because of an injury.
Penalty missed	MISSED_PENALTY		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		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		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		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 over	PENALTY_SHOOTOUT_END		Marks the end of the penalty shootout and the end of the match.
Penalty shootout goal	PENALTY_SHOOTOUT_GOAL		When a player scores a goal during the penalty shootout.
Penalty shootout miss	PENALTY_SHOOTOUT_MISS		When a player misses the goal during the penalty shootout.
Penalty shootout saved	PENALTY_SHOOTOUT_SAVED		When the goalkeepers save a shot during the penalty shootout.
Penalty shootout start	PENALTY_SHOOTOUT_START		Marks the beginning of the penalty shootout.
Penalty shootout taker	PENALTY_SHOOTOUT_TAKER		The player to take the next penalty.
Player warned	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		When the ball hits either side posts of the goal.
Team qualifies	QUALIFIES_NEXT_ROUND		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		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		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		Marks the end of the second half of play 45th to 90th minute.
Second half start	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		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		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		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		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		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		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		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		When the video assistant referee is reviewing a goal situation.
VAR Penalty review	VAR_PENALTY_REVIEW		When the video assistant referee is reviewing a penalty situation.
VAR Red card review	VAR_RED_CARD_REVIEW		When the video assistant referee is reviewing a red card situation.
VAR Review over	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		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		A break in the play for the players to cooldown and drink water.
Match winner	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		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		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		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.