Logo Logo
Logo
  • Home
  • Prices
  • Competitions
    • All Competitions
    • World Cup API
  • Documentation
    • Football API Documentation
    • Live Match Commentary
  • Help
    • FAQ
    • Contact
  • 🔍
  • Login
  • Register

Match commentary

Summarize with AI » Summarize with Google AI    Summarize with ChatGPT    Summarize with Claude    Summarize with Grok    Summarize with Perplexity
  • Livescores
  • Match Commentary
  • Football Fantasy
  • Fixtures API
  • Match events
  • Match statistics
  • Match lineups
  • Competition Squads
  • Competition Rosters
  • Match History
  • Head 2 Head
  • Live Standings
  • Standings
  • Group Standings
  • Top goalscorers
  • Top disciplinary
  • Countries
  • Flags
  • Competitions
  • Groups
  • Federations
  • Teams List
  • Team last matches
  • Team Event Minutes
  • Seasons
  • JSON Data
  • Response Structure
  • Common Errors
  • Languages
  • Validate Key

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

This football API endpoint delivers data exclusively for major tournaments such as the FIFA World Cup, Copa America, and UEFA Euro. Access to this data requires the purchase of a dedicated commentary package, available via the pricing page.

Clients who acquire the commentary football API package additionally receive a collection of icons that visually depict every event type. A complete catalog of these icons appears at the bottom of this page.

This football API endpoint provides coverage for 30+ languages.

The events commentary football API endpoint delivers an in-depth breakdown of 50 event types, ranging from a basic throw-in all the way to goals scored. Alongside each event, the response includes metadata such as the players involved, the teams involved, the pitch location, the event timing, and a textual description of the event available in 30+ languages.


ENDPOINT


GET:

Check this Football API endpoint in our postman collection. Download it now!


To exercise the API endpoint, supply any of the match ids below from the UEFA Nations League:
334919 Croatia - France
335217 Denmark - Croatia
335680 France - Croatia (the match featured on our commentary demonstration page)


NameTypeRequiredExampleDescription
from_secondNumber500The elapsed seconds counted from the start of the match, marking the point from which you want to retrieve all subsequent commentary events. Leave this parameter out when you need every event starting from the beginning of the match.
langStringfrThe two letter ISO code specifying the language in which you want the data returned. Pick any of the 30+ languages available. When this parameter is left out, the data falls back to English by default.
match_idNumber1335680The match id whose commentary data you want to retrieve
to_secondNumber600The elapsed seconds marking the point up to which you want to retrieve all preceding commentary events. Skip this parameter when you need every event through to the end of the match.

RESPONSE


Below is a sample response for the match event commentary. This excerpt comes from the France versus Croatia fixture played in the UEFA Nations League. The example contains 30 out of our 50+ different types of events.


{
    "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.football-api.com\/teams\/211.png"
                },
                "player": null,
                "player_2": null
            },
            {
                "id": 873,
                "match_id": 335680,
                "event_type": "MATCH_ENDS",
                "minute": "FT",
                "second": "FT",
                "match_second": 6788,
                "comment": "",
                "pos_x": 0,
                "pos_y": 0,
                "side": "",
                "created_at": "2022-06-29 14:51:38",
                "updated_at": "0",
                "text": "The match ends",
                "team": null,
                "player": null,
                "player_2": null
            },
            {
                "id": 872,
                "match_id": 335680,
                "event_type": "SECOND_HALF_OVER",
                "minute": "90+",
                "second": "280",
                "match_second": 6786,
                "comment": "",
                "pos_x": 0,
                "pos_y": 0,
                "side": "",
                "created_at": "2022-06-13 20:38:40",
                "updated_at": null,
                "text": "End of the regular time",
                "team": null,
                "player": null,
                "player_2": null
            },
            {
                "id": 825,
                "match_id": 335680,
                "event_type": "OFFSIDE",
                "minute": "72",
                "second": "53",
                "match_second": 5479,
                "comment": "",
                "pos_x": 83,
                "pos_y": 6,
                "side": "",
                "created_at": "2022-06-30 12:44:57",
                "updated_at": "0",
                "text": "Mateo Kovacic is caught offside",
                "team": {
                    "id": 211,
                    "name": "Croatia",
                    "stadium": "Stadion Maksimir",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.football-api.com\/teams\/211.png"
                },
                "player": {
                    "id": 4346,
                    "name": "Mateo Kovacic",
                    "photo": "https:\/\/cdn.football-api.com\/players\/e\/0\/2\/a\/e02a35b1563d0db53486ec068ebab80f.png"
                },
                "player_2": null
            },
            {
                "id": 757,
                "match_id": 335680,
                "event_type": "SECOND_HALF_START",
                "minute": "HT",
                "second": "HT",
                "match_second": 3813,
                "comment": "",
                "pos_x": 0,
                "pos_y": 0,
                "side": "",
                "created_at": "2022-06-13 19:48:58",
                "updated_at": "0",
                "text": "The second half starts",
                "team": null,
                "player": null,
                "player_2": null
            },
            {
                "id": 755,
                "match_id": 335680,
                "event_type": "SUBSTITUTION",
                "minute": "HT",
                "second": "HT",
                "match_second": 3784,
                "comment": "",
                "pos_x": 0,
                "pos_y": 0,
                "side": "",
                "created_at": "2022-06-13 19:48:44",
                "updated_at": null,
                "text": "Substitution in the team of France. Benjamin Pavard replaces Jules Kounde",
                "team": {
                    "id": 1439,
                    "name": "France",
                    "stadium": "Stade de France",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.football-api.com\/teams\/1439.png"
                },
                "player": {
                    "id": 2377,
                    "name": "Benjamin Pavard",
                    "photo": "https:\/\/cdn.football-api.com\/players\/2\/6\/9\/d\/269d837afada308dd4aeab28ca2d57e4.png"
                },
                "player_2": {
                    "id": 16226,
                    "name": "Jules Kounde",
                    "photo": "https:\/\/cdn.football-api.com\/players\/9\/c\/7\/7\/9c773fbdb174e0964bd32bafde850f87.png"
                }
            },
            {
                "id": 754,
                "match_id": 335680,
                "event_type": "FIRST_HALF_OVER",
                "minute": "45+",
                "second": "125",
                "match_second": 2825,
                "comment": "",
                "pos_x": 0,
                "pos_y": 0,
                "side": "",
                "created_at": "2022-06-13 19:32:39",
                "updated_at": null,
                "text": "End of the first half of play",
                "team": null,
                "player": null,
                "player_2": null
            },
            {
                "id": 752,
                "match_id": 335680,
                "event_type": "ADDITIONAL_TIME",
                "minute": "45+",
                "second": "80",
                "match_second": 2780,
                "comment": "2",
                "pos_x": 0,
                "pos_y": 0,
                "side": "",
                "created_at": "2022-06-13 19:31:54",
                "updated_at": null,
                "text": "The referee indicates 2 minutes of added time",
                "team": null,
                "player": null,
                "player_2": null
            },
            {
                "id": 713,
                "match_id": 335680,
                "event_type": "SHOT_OFF_TARGET",
                "minute": "27",
                "second": "46",
                "match_second": 1666,
                "comment": "",
                "pos_x": 69,
                "pos_y": 33,
                "side": "",
                "created_at": "2022-06-13 19:13:21",
                "updated_at": null,
                "text": "Christopher Nkunku misses the goal",
                "team": {
                    "id": 1439,
                    "name": "France",
                    "stadium": "Stade de France",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.football-api.com\/teams\/1439.png"
                },
                "player": {
                    "id": 14842,
                    "name": "Christopher Nkunku",
                    "photo": "https:\/\/cdn.football-api.com\/players\/8\/a\/a\/d\/8aad11ad0535421ef52a534d5cce4bd3.png"
                },
                "player_2": null
            },
            {
                "id": 698,
                "match_id": 335680,
                "event_type": "GOAL_KICK_TAKEN",
                "minute": "21",
                "second": "35",
                "match_second": 1295,
                "comment": "",
                "pos_x": 95,
                "pos_y": 42,
                "side": "",
                "created_at": "2022-06-13 19:07:08",
                "updated_at": null,
                "text": "Ivica Ivusic takes the goal kick",
                "team": {
                    "id": 211,
                    "name": "Croatia",
                    "stadium": "Stadion Maksimir",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.football-api.com\/teams\/211.png"
                },
                "player": {
                    "id": 13448,
                    "name": "Ivica Ivusic",
                    "photo": "https:\/\/cdn.football-api.com\/players\/7\/7\/d\/a\/77da2f07ed6c94afa27b5f113bea7ebe.png"
                },
                "player_2": null
            },
            {
                "id": 697,
                "match_id": 335680,
                "event_type": "GOAL_KICK",
                "minute": "21",
                "second": "9",
                "match_second": 1269,
                "comment": "",
                "pos_x": 99,
                "pos_y": 27,
                "side": "",
                "created_at": "2022-06-13 19:06:43",
                "updated_at": null,
                "text": "The ball goes out for a goal kick",
                "team": null,
                "player": null,
                "player_2": null
            },
            {
                "id": 689,
                "match_id": 335680,
                "event_type": "MATCH_STOPPED_INJURY",
                "minute": "18",
                "second": "41",
                "match_second": 1121,
                "comment": "",
                "pos_x": 0,
                "pos_y": 0,
                "side": "",
                "created_at": "2022-06-13 19:04:14",
                "updated_at": null,
                "text": "The play is paused because of an injury",
                "team": null,
                "player": null,
                "player_2": null
            },
            {
                "id": 688,
                "match_id": 335680,
                "event_type": "TREATMENT",
                "minute": "18",
                "second": "7",
                "match_second": 1087,
                "comment": "",
                "pos_x": 46,
                "pos_y": 91,
                "side": "",
                "created_at": "2022-06-13 19:03:43",
                "updated_at": null,
                "text": "Josip Brekalo is being treated because of an injury",
                "team": {
                    "id": 211,
                    "name": "Croatia",
                    "stadium": "Stadion Maksimir",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.football-api.com\/teams\/211.png"
                },
                "player": {
                    "id": 20113,
                    "name": "Josip Brekalo",
                    "photo": "https:\/\/cdn.football-api.com\/players\/1\/0\/5\/b\/105bbb4c5c3b35ce92f245193aa94883.png"
                },
                "player_2": null
            },
            {
                "id": 687,
                "match_id": 335680,
                "event_type": "YELLOW_CARD",
                "minute": "17",
                "second": "48",
                "match_second": 1068,
                "comment": "",
                "pos_x": 0,
                "pos_y": 0,
                "side": "",
                "created_at": "2022-06-13 19:03:23",
                "updated_at": null,
                "text": "Matteo Guendouzi receives an yellow card",
                "team": {
                    "id": 1439,
                    "name": "France",
                    "stadium": "Stade de France",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.football-api.com\/teams\/1439.png"
                },
                "player": {
                    "id": 1331,
                    "name": "Matteo Guendouzi",
                    "photo": "https:\/\/cdn.football-api.com\/players\/e\/0\/7\/7\/e077e1a544eec4f0307cf5c3c721d944.png"
                },
                "player_2": null
            },
            {
                "id": 681,
                "match_id": 335680,
                "event_type": "SHOT_BLOCKED",
                "minute": "13",
                "second": "47",
                "match_second": 827,
                "comment": "",
                "pos_x": 88,
                "pos_y": 33,
                "side": "",
                "created_at": "2022-06-13 19:00:28",
                "updated_at": "0",
                "text": "The shot of Kylian Mbappe is blocked by Martin Erlic",
                "team": {
                    "id": 211,
                    "name": "Croatia",
                    "stadium": "Stadion Maksimir",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.football-api.com\/teams\/211.png"
                },
                "player": {
                    "id": 76121,
                    "name": "Martin Erlic",
                    "photo": "https:\/\/cdn.football-api.com\/players\/a\/9\/b\/1\/a9b12572d82cef73f0d41c73e93c0249.png"
                },
                "player_2": {
                    "id": 13888,
                    "name": "Kylian Mbappe",
                    "photo": "https:\/\/cdn.football-api.com\/players\/d\/b\/8\/1\/db817217c5d9b196aa39cfeb0ce889e4.png"
                }
            },
            {
                "id": 677,
                "match_id": 335680,
                "event_type": "FREE_KICK_TAKEN",
                "minute": "11",
                "second": "21",
                "match_second": 681,
                "comment": "",
                "pos_x": 65,
                "pos_y": 96,
                "side": "",
                "created_at": "2022-06-13 18:56:56",
                "updated_at": null,
                "text": "Jules Kounde takes the free kick",
                "team": {
                    "id": 1439,
                    "name": "France",
                    "stadium": "Stade de France",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.football-api.com\/teams\/1439.png"
                },
                "player": {
                    "id": 16226,
                    "name": "Jules Kounde",
                    "photo": "https:\/\/cdn.football-api.com\/players\/9\/c\/7\/7\/9c773fbdb174e0964bd32bafde850f87.png"
                },
                "player_2": null
            },
            {
                "id": 676,
                "match_id": 335680,
                "event_type": "FOUL_COMMITTED",
                "minute": "11",
                "second": "12",
                "match_second": 672,
                "comment": "",
                "pos_x": 64,
                "pos_y": 95,
                "side": "",
                "created_at": "2022-06-13 18:56:47",
                "updated_at": null,
                "text": "Foul committed",
                "team": null,
                "player": {
                    "id": 4346,
                    "name": "Mateo Kovacic",
                    "photo": "https:\/\/cdn.football-api.com\/players\/e\/0\/2\/a\/e02a35b1563d0db53486ec068ebab80f.png"
                },
                "player_2": null
            },
            {
                "id": 665,
                "match_id": 335680,
                "event_type": "GOALKEEPER_SAVE",
                "minute": "6",
                "second": "48",
                "match_second": 408,
                "comment": "",
                "pos_x": 97,
                "pos_y": 55,
                "side": "",
                "created_at": "2022-06-13 18:52:30",
                "updated_at": null,
                "text": "Ivica Ivusic makes a save",
                "team": {
                    "id": 211,
                    "name": "Croatia",
                    "stadium": "Stadion Maksimir",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.football-api.com\/teams\/211.png"
                },
                "player": {
                    "id": 13448,
                    "name": "Ivica Ivusic",
                    "photo": "https:\/\/cdn.football-api.com\/players\/7\/7\/d\/a\/77da2f07ed6c94afa27b5f113bea7ebe.png"
                },
                "player_2": null
            },
            {
                "id": 664,
                "match_id": 335680,
                "event_type": "SHOT_ON_TARGET",
                "minute": "6",
                "second": "48",
                "match_second": 400,
                "comment": "",
                "pos_x": 76,
                "pos_y": 35,
                "side": "",
                "created_at": "2022-06-13 18:52:38",
                "updated_at": "0",
                "text": "Kylian Mbappe hits the goal",
                "team": {
                    "id": 1439,
                    "name": "France",
                    "stadium": "Stade de France",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.football-api.com\/teams\/1439.png"
                },
                "player": {
                    "id": 13888,
                    "name": "Kylian Mbappe",
                    "photo": "https:\/\/cdn.football-api.com\/players\/d\/b\/8\/1\/db817217c5d9b196aa39cfeb0ce889e4.png"
                },
                "player_2": null
            },
            {
                "id": 663,
                "match_id": 335680,
                "event_type": "THROW_IN_TAKEN",
                "minute": "6",
                "second": "17",
                "match_second": 377,
                "comment": "",
                "pos_x": 81,
                "pos_y": 98,
                "side": "",
                "created_at": "2022-06-13 18:51:52",
                "updated_at": null,
                "text": "Jules Kounde takes the throw in for France",
                "team": {
                    "id": 1439,
                    "name": "France",
                    "stadium": "Stade de France",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.football-api.com\/teams\/1439.png"
                },
                "player": {
                    "id": 16226,
                    "name": "Jules Kounde",
                    "photo": "https:\/\/cdn.football-api.com\/players\/9\/c\/7\/7\/9c773fbdb174e0964bd32bafde850f87.png"
                },
                "player_2": null
            },
            {
                "id": 662,
                "match_id": 335680,
                "event_type": "THROW_IN_AWARDED",
                "minute": "6",
                "second": "13",
                "match_second": 373,
                "comment": "",
                "pos_x": 86,
                "pos_y": 98,
                "side": "h",
                "created_at": "2022-06-13 18:51:47",
                "updated_at": null,
                "text": "The ball goes out for a throw in for France",
                "team": {
                    "id": 1439,
                    "name": "France",
                    "stadium": "Stade de France",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.football-api.com\/teams\/1439.png"
                },
                "player": null,
                "player_2": null
            },
            {
                "id": 661,
                "match_id": 335680,
                "event_type": "KICK_OFF",
                "minute": "5",
                "second": "21",
                "match_second": 321,
                "comment": "",
                "pos_x": 50,
                "pos_y": 50,
                "side": "h",
                "created_at": "2022-06-13 18:50:54",
                "updated_at": null,
                "text": "France restart the game after conceding a goal",
                "team": {
                    "id": 1439,
                    "name": "France",
                    "stadium": "Stade de France",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.football-api.com\/teams\/1439.png"
                },
                "player": null,
                "player_2": null
            },
            {
                "id": 660,
                "match_id": 335680,
                "event_type": "GOAL_PENALTY",
                "minute": "4",
                "second": "35",
                "match_second": 275,
                "comment": "",
                "pos_x": 11,
                "pos_y": 50,
                "side": "",
                "created_at": "2022-06-13 18:50:11",
                "updated_at": null,
                "text": "Luka Modric scores from a penalty",
                "team": {
                    "id": 211,
                    "name": "Croatia",
                    "stadium": "Stadion Maksimir",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.football-api.com\/teams\/211.png"
                },
                "player": {
                    "id": 14958,
                    "name": "Luka Modric",
                    "photo": "https:\/\/cdn.football-api.com\/players\/a\/8\/b\/f\/a8bfe36fa885d46814378912f268a8a1.png"
                },
                "player_2": null
            },
            {
                "id": 659,
                "match_id": 335680,
                "event_type": "VAR_REVIEW_OVER",
                "minute": "3",
                "second": "54",
                "match_second": 234,
                "comment": "Penalty",
                "pos_x": 0,
                "pos_y": 0,
                "side": "",
                "created_at": "2022-06-13 18:49:32",
                "updated_at": null,
                "text": "VAR review is complete. Decision: Penalty",
                "team": null,
                "player": null,
                "player_2": null
            },
            {
                "id": 658,
                "match_id": 335680,
                "event_type": "VAR_PENALTY_REVIEW",
                "minute": "3",
                "second": "26",
                "match_second": 206,
                "comment": "",
                "pos_x": 0,
                "pos_y": 0,
                "side": "",
                "created_at": "2022-06-13 18:49:00",
                "updated_at": null,
                "text": "VAR is reviewing a penalty situation",
                "team": null,
                "player": null,
                "player_2": null
            },
            {
                "id": 657,
                "match_id": 335680,
                "event_type": "PENALTY_AWARDED",
                "minute": "3",
                "second": "9",
                "match_second": 189,
                "comment": "",
                "pos_x": 11,
                "pos_y": 50,
                "side": "a",
                "created_at": "2022-06-13 18:48:44",
                "updated_at": null,
                "text": "Penalty kick awarded in favour of Croatia",
                "team": {
                    "id": 211,
                    "name": "Croatia",
                    "stadium": "Stadion Maksimir",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.football-api.com\/teams\/211.png"
                },
                "player": null,
                "player_2": null
            },
            {
                "id": 656,
                "match_id": 335680,
                "event_type": "CORNER_KICK_TAKEN",
                "minute": "2",
                "second": "51",
                "match_second": 171,
                "comment": "",
                "pos_x": 1,
                "pos_y": 1,
                "side": "",
                "created_at": "2022-06-13 18:48:25",
                "updated_at": null,
                "text": "Josip Brekalo takes the corner for Croatia",
                "team": {
                    "id": 211,
                    "name": "Croatia",
                    "stadium": "Stadion Maksimir",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.football-api.com\/teams\/211.png"
                },
                "player": {
                    "id": 20113,
                    "name": "Josip Brekalo",
                    "photo": "https:\/\/cdn.football-api.com\/players\/1\/0\/5\/b\/105bbb4c5c3b35ce92f245193aa94883.png"
                },
                "player_2": null
            },
            {
                "id": 655,
                "match_id": 335680,
                "event_type": "CORNER_KICK_AWARDED",
                "minute": "2",
                "second": "26",
                "match_second": 146,
                "comment": "",
                "pos_x": 1,
                "pos_y": 21,
                "side": "a",
                "created_at": "2022-06-13 18:48:00",
                "updated_at": null,
                "text": "Croatia wins a corner",
                "team": {
                    "id": 211,
                    "name": "Croatia",
                    "stadium": "Stadion Maksimir",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.football-api.com\/teams\/211.png"
                },
                "player": null,
                "player_2": null
            },
            {
                "id": 653,
                "match_id": 335680,
                "event_type": "CONTAINS_BALL",
                "minute": "0",
                "second": "50",
                "match_second": 50,
                "comment": "",
                "pos_x": 0,
                "pos_y": 0,
                "side": "h",
                "created_at": "2022-06-13 18:46:24",
                "updated_at": null,
                "text": "France contains the ball for a long period of time",
                "team": {
                    "id": 1439,
                    "name": "France",
                    "stadium": "Stade de France",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.football-api.com\/teams\/1439.png"
                },
                "player": null,
                "player_2": null
            },
            {
                "id": 652,
                "match_id": 335680,
                "event_type": "MATCH_START",
                "minute": "0",
                "second": "0",
                "match_second": 0,
                "comment": "",
                "pos_x": 0,
                "pos_y": 0,
                "side": "a",
                "created_at": "2022-06-13 18:45:32",
                "updated_at": null,
                "text": "The match starts",
                "team": {
                    "id": 211,
                    "name": "Croatia",
                    "stadium": "Stadion Maksimir",
                    "country_id": 115,
                    "logo": "https:\/\/cdn.football-api.com\/teams\/211.png"
                },
                "player": null,
                "player_2": null
            }
        ],
        "match": {
            "home": "France",
            "away": "Croatia",
            "score": "0 - 1",
            "ht_score": "0 - 1",
            "time": "FT"
        }
    }
}


NameTypeExampleDescription
commentStringThis field carries extra clarification for the event whenever such detail is supplied, for instance in the case of VAR decisions.
created_atDatetime2022-06-13 20:34:43The UTC date and time at which the event was written into our database.
event_typeStringSUBSTITUTIONThe event type that occurred. More than 50 event types are documented in a section further down this page.
idNumber863The commentary event id.
match_idNumber335680The match id identifying the match that contains the event.
match_secondNumber6546The total count of seconds elapsed since the match kicked off, factoring in the half time break, the extra time break, and the pause while awaiting penalties.
minuteString90A textual representation of the match minute in which the event took place. It may appear as digits such as 87, as added time notation like 90+, or even as HT when something occurs during the break, for example a SUBSTITUTION.
playerObject{}An object that carries information about a player, following the structure of our standard player object.
player_2Object{}An object that carries information about a player, following the structure of our standard player object.
pos_xNumber0The percentage of the pitch length measured from the top left corner up to the point where the event occurred. Certain events, such as a SUBSTITUTION, do not carry coordinates.
pos_yNumber0The percentage of the pitch width measured from the top throw in line down to the point where the event occurred. Certain events, such as a SUBSTITUTION, do not carry coordinates.
secondNumber40Typically a value between 0 and 59. It may exceed 59 once the match enters ADDITIONAL_TIME. In that case, the combined minute and second reading appears as 90+ 250.
sideCharaEither h or a. Much like the matches events data, this field signals whether the home team or the away team is involved in the event. Certain events, such as ADDITIONAL_TIME, have no side assigned.
teamObject{}An object that carries information about the team the player is competing for, following 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, rendered in whichever of the 30+ languages you selected.
updated_atDatetime2022-06-13 20:34:43When a commentary event receives consecutive updates, this field holds the UTC date and time at which the latest update was applied.

To illustrate what a commentary data event contains, consider the substitution in the 90th minute where Benjamin Pavard came on for Jules Kounde for France. This particular event carries data across every available field. In certain situations, either because data is still streaming in or because the event type does not support them, some fields may be empty and later get filled once subsequent data updates arrive.


EVENT COORDINATES


football API commentary event position
Because football pitches vary in their dimensions, we at football api rely on a percentage based approach for event coordinates. The origin of this coordinate system sits at the top left corner of the football pitch, at coordinates (0, 0). From there, both the horizontal x axis and the vertical y axis run from 0 to 100, terminating at the bottom right corner of the football pitch at coordinates (100,100).

Consequently, the centre spot shown in the image sits at coordinates (50,50). This lets you visually plot the event onto a field image of any size and orientation.

We have likewise marked an event location at (33, 19) within the top left quadrant of the football pitch, showing how the coordinates advance from (0, 0) to (33, 19) to (50, 50) and finally to (98, 98).


EVENT TYPES


The team.id and team.name fields identify which team is related to the event.
The player.id and player.name indicate the player that is involved in the event.
In some cases, there is second player involved like a SUBSTITUTION or GOAL_SCORED. Then The player2.id and player2.name give information for the player.

TypeIconDescription
ADDITIONAL_TIME football api commentary match Added time Extra time appended at the end of the half. The comment field states how many minutes were added.
CONTAINS_BALL football api commentary match Containing the ball A team retaining possession of the ball over an extended spell.
CORNER_KICK_AWARDED football api commentary match Corner kick awarded A team earns a corner kick in the opponent's half.
CORNER_KICK_TAKEN football api commentary match Corner kick taken A player steps up to take the corner kick.
CROSSBAR_HIT football api commentary match Crossbar hit The ball strikes the crossbar.
DRAW football api commentary match Draw match The match ends with the two sides level.
EXTRA_TIME_HALF_TIME football api commentary match Extra time break The interval separating the two 15 minute periods of extra time, played between the 90th and 120th minute.
EXTRA_TIME_OVER football api commentary match Extra time over The close of extra time, at the 120th minute.
EXTRA_TIME_SECOND_HALF_START football api commentary match Second extra time period start The start of the second period of extra time, covering the 105th to 120th minute.
EXTRA_TIME_START football api commentary match Extra time starts The start of extra time, covering the 90th to 105th minute.
FIRST_HALF_OVER football api commentary match Half time break starts The close of the first half after 45 minutes.
FOUL_COMMITTED football api commentary match Foul (Rule violation) A player commits a foul or otherwise breaks the rules.
FREE_KICK_TAKEN football api commentary match Free kick taken A player steps up to take the free kick.
GOAL football api commentary match Goal scored A goal is scored.
GOALKEEPER_SAVE football api commentary match Goalkeeper save The goalkeeper pulls off a save.
GOAL_KICK football api commentary match Goal kick The ball goes out of play for a goal kick.
GOAL_KICK_TAKEN football api commentary match Goal kick taken A player steps up to take the goal kick.
GOAL_PENALTY football api commentary match Goal from a penalty A goal is converted from the penalty spot during play, between the 1st and 120th minute.
KICK_OFF football api commentary match Kick Off The kick off restarting play after a goal is scored.
MATCH_ENDS football api commentary match Match ended The moment the match ends, at the 90th minute, or the 120th minute when extra time is played.
MATCH_START football api commentary match Match start The kick off that marks the start of the match.
MATCH_STOPPED_INJURY football api commentary match Match stopped (injury) Play is halted because of an injury.
MISSED_PENALTY football api commentary match Penalty missed A player fails to convert from the penalty spot during regular time, between the 90th and 120th minute.
OFFSIDE football api commentary match Offside A player is caught offside behind the line of defence.
OWN_GOAL football api commentary match Own goal A player puts the ball into their own net.
PENALTY_AWARDED football api commentary match Penalty awarded The referee points to the penalty spot during regular time, between the 90th and 120th minute.
PENALTY_SHOOTOUT_END football api commentary match Penalty shootout over The moment that marks the end of the penalty shootout and the conclusion of the match.
PENALTY_SHOOTOUT_GOAL football api commentary match Penalty shootout goal A player converts a goal during the penalty shootout.
PENALTY_SHOOTOUT_MISS football api commentary match Penalty shootout miss A player fails to score during the penalty shootout.
PENALTY_SHOOTOUT_SAVED football api commentary match Penalty shootout saved The goalkeeper denies a shot during the penalty shootout.
PENALTY_SHOOTOUT_START football api commentary match Penalty shootout start The moment that signals the start of the penalty shootout.
PENALTY_SHOOTOUT_TAKER football api commentary match Penalty shootout taker The player lined up to take the next penalty.
PLAYER_WARNED football api commentary match Player warned The referee pulls a player aside for a word.
POST_HIT football api commentary match Post hit The ball strikes either of the goalposts.
QUALIFIES_NEXT_ROUND football api commentary match Team qualifies A team books its place in the next round.
RED_CARD football api commentary match Red card A player is shown a red card.
RED_CARD_CANCELED football api commentary match Red card cancelled The referee overturns a player's red card after reviewing the incident.
SECOND_HALF_OVER football api commentary match Second half over The moment that marks the end of the second half, covering the 45th to 90th minute.
SECOND_HALF_START football api commentary match Second half start The moment that marks the start of the second half, covering the 45th to 90th minute.
SHOT_BLOCKED football api commentary match Shot blocked A player blocks a shot on goal.
SHOT_OFF_TARGET football api commentary match Shot off target A player takes a shot that misses the target, sailing wide or over the goal.
SHOT_ON_TARGET football api commentary match Shot on target A player's shot finishes on target.
SUBSTITUTION football api commentary match Substitution The manager makes a substitution, swapping one player for another.
THROW_IN_AWARDED football api commentary match Throw in The ball goes out of play for a throw in.
THROW_IN_TAKEN football api commentary match Throw in taken A player steps up to take the throw in.
TREATMENT football api commentary match Treatment A player receives treatment from the medical staff.
VAR_GOAL_REVIEW football api commentary match VAR Goal review The video assistant referee reviews a goal situation.
VAR_PENALTY_REVIEW football api commentary match VAR Penalty review The video assistant referee reviews a penalty situation.
VAR_RED_CARD_REVIEW football api commentary match VAR Red card review The video assistant referee reviews a red card situation.
VAR_REVIEW_OVER football api commentary match VAR Review over The video assistant referee completes a review.
WASTING_TIME football api commentary match Wasting time A team or player deliberately stalls, running down the clock.
WATER_BREAK football api commentary match Water break A pause in play letting the players cool down and take on water.
WINNER football api commentary match Match winner Provides details on which side won the match.
YELLOW_CARD football api commentary match Yellow card A player is shown a yellow card.
YELLOW_CARD_CANCELED football api commentary match Yellow card cancelled The referee overturns a player's yellow card after reviewing the incident.
YELLOW_RED_CARD football api commentary match Second yellow card A player picks up a second yellow card and is sent off.



Didn't find what you need?

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

Copied!
The text snippet has been copied to your clipboard. You can go and paste it wherever you need it!

Navigation

  • Home
  • Documentation
  • Prices
  • Competitions
  • Register
  • Contact
  • Terms
  • Blog

Major Competitions

  • All Competitions
  • World Cup API

Documentation!

  • API Documentation
  • Match Commentary

Social


  • Facebook
  • Twitter
  • YouTube
  • LinkedIn


Sitemaps


Sitemap in English Sitemap en Español
Logo

With 12 years of experience, football API develops and supports high-quality API data endpoints. We provide live scores, fixtures, history, match events, match statistics, standings, lineups, squads, odds, player statistics, live match commentary, live standings, goalscores, disciplinary, logos, flags, photos, and more.

© 2014 - 2026 All Rights Reserved football-api.com