# Soccer AI Commentary This REST API endpoint returns all available statistical data in the form of soccer commentary given a fixture\_id and a team\_id. This can be called before a match begins (to obtain pre match insights) or during a live fixture to obtain (in-play insights). Soccer data is processed via the Data Insights Lakehouse Engine using historical data and has the capability to include AI commentary additional processing to enhance the comments. ## Endpoint URL **** N.B. – Please insert the relevant fixtureId returned from the fixtures API endpoint to return the data. The authentication token provided will be required to make a connection to this websocket endpoint. ## Polling Frequency We recommend the following frequency for your REST requests to ensure that you have the most up-to-date information at all times: | Frequency | | -------------------------------- | | Every 30 seconds for media usage | ## Required Headers | Required (unless stated otherwise\*) | Value | | ------------------------------------ | ------------------------------------------------- | | Accept | application/vnd.imggaming.dde.api+json;version=1 | | Content-Type | application/json | | Authorization | Bearer eyvhaoudfgpdfgo\* | | fixtureId (Optional\*) | 8780f158-052f-4f70-80c8-5d748f1494fe (an example) | | teamId (Optional\*) | 023356e9-3287-46a5-973a-9c71b02e4de6 (an example) | | language | en by default (or another language) | | trigger (market types) | ALL (or a market type) | | include\_alt\_text (Optional\*) | (yes/no) | | enable\_ai (Optional\*) | (true/false) | **Example Header** ```bash 'GET' \ 'https://dde-api.data.imgarena.com/soccer/commentary_ui?fixtureId=8780f158-052f-4f70-80c8-5d748f1494fe&teamId=023356e9-3287-46a5-973a-9c71b02e4de6&language=en&trigger=ALL&include_alt_text=false' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' ``` ## Feed Model Comment narratives and data types fit into one of these categories as their primary 'betting driver/market type' ``` TotalGoals AvgGoals TotalShotsOnTarget AvgShotsOnTarget NumberOfBookingsYellowTotal NumberOfBookingsYellowAvg TotalPenalties AvgPenalties TotalThrowIns AvgThrowIns CleanSheet CleanSheetImpolluted CleanSheetFail BothTeamsToScore BothHalvesGoal MatchResultDraw MatchResultLoss MatchResultNoLoss MatchResultWin MatchResultNoWin OverOrUnder2UpOrMore OverOrUnder2DownOrLess FirstToScoreTeamGoal Last10MinFirstHalfGoals Last10MinFirstHalfCorners Last10MinFirstHalfThrowIns Last10MinFirstHalfShotsOnTarget Last10MinFirstHalfBooked Last15MinSecondHalfGoals Last15MinSecondHalfCorners Last15MinSecondHalfThrowIns Last15MinSecondHalfShotsOnTarge Last15MinSecondHalfBooked PlayerToScore GoalsAfterCorner DangerousAttacks TeamAvgFirstGoal TeamAvgFirstYellow TeamAvgSecondYellow TeamAvgFifthCorner TeamAvgThirdShotOnTarget ``` ## Sample Response Extracts \ **ThrowIns** * In their last 15 fixtures this season playing at home in the Netherlands Eerste Divisie, Team FC Utrecht U21 has conceded 414 throw-ins: 191 in the first period, 223 during the second **TeamAvgThirdShotOnTarget** * The average time for Team Ajax Amsterdam U21 to concede their third shot on target this Netherlands Eerste Divisie season playing away is 38 minutes * The average time for Team Adelaide Cobras Res. to concede their third shot on target this Australia South Australia - State League 1 Reserves season playing home is 49 minutes **TeamAvgFirstYellow** * The average time for Team Austin FC to book their opponent the first yellow card this season at USA MLS is 39 minutes **TeamAvgSecondYellow** * The average time for Team Ajax Amsterdam U21's opponent to receive a second yellow card this season in the Netherlands Eerste Divisie is 68 minutes **TeamAvgFirstGoal** * The average time for Team Charlotte FC to concede their first goal this season at USA MLS playing away is 53 minutes * The average time for Team AIK to score their first goal this season at Sweden Allsvenskan is 52 minutes **TeamAvgFifthCorner** * The average time for Team JK Tabasalu to concede five corners this season playing home is 72 minutes at Estonia Esiliiga * The average time for Team Colorado Rapids 2 to concede five corners this season is 46 minutes at USA MLS Next Pro **ShotsOnTarget (inc player shots on target info)** * In their last 2 fixtures this season playing at home in the Australia Victoria - NPLW, Team Bulleen Lions W has conceded 14 shots on target, where 5 happened in the first period * In their last 24 fixtures this season in the Israel Ligat ha'Al, Maccabi Haifa's player Refaelov has accumulated a total of 1 shots on target and it happened during the first half **OverOrUnder2UpOrMore** * After 7 total games this 2024 season at USA MLS Team Inter Miami CF has been 2 goals above its opponent 3 matches * After 14 away games this 2023/2024 season at Greece Super League Team PAOK Thessaloniki has been 2 goals above its opponent 10 matches **OverOrUnder2DownOrLess** * After 5 total games this 2024 season at USA MLS Team New England Revolution has been 2 goals down its opponent 3 matches **NumberOfBookingsYellowAvg (with player data)** * In their last 19 fixtures this season in the Romania Superliga, ACSM Politehnica Iasi's player De Souza Figueiredo has been booked an average of 0.16 yellow cards per match. 33% took place during the first half * In their last 10 fixtures this season in the Romania Superliga, SC Otelul Galati's player Rus has been booked an average of 0.3 yellow cards per match. 33% took place during the first half **NumberOfBookingsYellow (with player data)** * In their last 21 fixtures this season in the Montenegro Prva Liga, FK Mladost Donja Gorica's player Maras has been booked a total of 4 yellow cards: 1 in the first period, 3 during the second **MatchResultWin** * Team AEK Athens has won their previous 5 home games this 2023/2024 season at Greece Super League * Team PFC Ludogorets 1945 has won their previous 4 away games this 2023/2024 season at Bulgaria 1 Liga **MatchResultNoLoss** * Team Macarthur FC has not lost their previous 5 away matches this 2023/2024 season at Australia A-League Men * Team Skive IK has not lost their previous 8 total matches this 2023/2024 season at Denmark 2nd Division **MatchResultLoss** * Team VfB Lübeck has lost their previous 5 away matches this 2023/2024 season at Germany 3. Liga * Team FC Dallas has lost their previous 4 total matches this 2024 season at USA MLS **MatchResultDraw** * Team Skive IK has tied their last 4 home matches this 2023/2024 season at Denmark 2nd Division * Team FK Tekstilac Odzaci has tied their last 5 away matches this 2023/2024 season in the Serbia Prva Liga **Last15MinSecondHalfGoals** * In the previous 2 total games, Team Colorado Rapids 2 has scored a goal during the last 15 minutes of the second half * In the previous 3 total games of the Australia Victoria - VPL 1, Team Kingston City has conceded a goal during the last 15 minutes of the second half **Last15MinSecondHalfBooked** * In the previous 4 total games, Team Preston Lions has received a yellow card during the last 15 minutes of the second half **Last10MinFirstHalfGoals** * In the previous 2 total games, Team Chicago Fire FC has conceded a goal during the last 10 minutes of the first half * In the previous 2 total games, Team Tacoma Defiance has scored a goal during the last 10 minutes of the first half **Last10MinFirstHalfBooked** * In the previous 3 total games, Team Kingston City U23 has conceded a yellow card during the last 10 minutes of the first half **Goals** * In their last 11 fixtures this season playing away in the Romania Superliga, SC Otelul Galati's player Teles Pereira Nunes Da Silva has scored 3 goals: 2 in the first period, 1 during the second * In their last 7 fixtures this season playing home in the Israel Ligat ha'Al, Maccabi Tel Aviv's player Gilad Kanichowsky has scored 2 goals, both of them in the second half * In their last 17 fixtures this season in the Montenegro Prva Liga, OFK Petrovac's player Babic has scored a total of 8 goals: 4 in the first period, 4 during the second **FirstToScoreTeamGoal** * After 15 home games this 2023/2024 season at Greece Super League Team PAOK Thessaloniki has been the first scorer on 10 * After 21 total games this 2023/2024 season at Denmark 2nd Division Team Esbjerg fB has been the first scorer on 15 **DangerousAttacks** * In the last 2 away matches for the season 2024 at Australia South Australia - State League 1 Reserves Team Salisbury United FC Res. has missed 2 dangerous attacks **CleanSheet** * Team FC Dordrecht keeps a clean sheet during their last 5 home matches * Team Holbaek keeps a clean sheet during their last 4 away matches **BothTeamsToScore** * On the previous 1 away matches, both Adelaide Blue Eagles Res. and its opponents scored at least a goal * On the previous 2 away matches, both New England Revolution and its opponents scored at least a goal **AvgThrowIns** * On their last 3 fixtures this season at USA MLS Next Pro, Team Tacoma Defiance has conceded an average of 24.33 throw-ins per match, 45% took place during the first half **AvgShotsOnTarget** * In their last 24 fixtures this season in the Israel Ligat ha'Al, Maccabi Haifa's player Refaelov averages a total of 0.04 shots on target per match, 100% took place during the first half * In their last 27 fixtures this season in the Bulgaria 1 Liga, Team Botev Vratsa has conceded, on average, a total of 5.33 shots on target per match, 40% took place during the first half * In their last 3 fixtures this season playing at home in the Australia Victoria - VPL 1, Team Langwarrin has conceded, on average, 6.33 shots on target per match, 36% took place during the first half **AvgGoals (including player data)** * In their last 14 fixtures this season in the Serbia Prva Liga, FK Mladost GAT Novi Sad's player Abadzija averages a total of 0.14 goals per match, all took place during the first half * In their last 17 fixtures this season in the Montenegro Prva Liga, OFK Petrovac's player Babic averages a total of 0.47 goals per match * In their last 7 fixtures this season playing home in the Serbia Prva Liga, FK Indjija's player Desancic averages 0.43 goals per match ## AI-Enabled Commentary Sample Extract **Example of enable\_ai ( increases variation of comments by a factor of 10 )** **time triggered comments** "*Columbus Crew are winning 2-0. In the previous 2 total games have scored a goal during the last 15 minutes of the second half*" "*Inter Miami are drawing 0-0. The average time to concede their first goal this season is 30 minutes. The average time to concede their first goal this season playing away is 24 minutes*" "*Colorado are losing 0-1, but the match is still very much in play. They should maintain a positive attitude and continue to fight for every opportunity. The average time to receive the first yellow card this season playing at home is 57 minutes, so they must be cautious in their tackles.*" **event triggered comments** "*Nashville just attempted their second shot of the game, indicating their willingness to take risks. At home, they typically have their third shot on target by the 44th minute mark.*" "*Vancouver have conceded, on average, a total of 2.0 goals per match in their recent fixtures, highlighting a clear area for improvement. In their last fixture this season, playing at home, they have conceded 2 goals, with all being scored in the first half.*" "*Having just received their first yellow card in the game, LA Galaxy needs to maintain composure and avoid risky tackles. Their average time to receive a second yellow card this season is 45 minutes, so they should be mindful of their discipline on the field.*" ## Response Model \ **Action Id object**
Field NameTypeDescription
awayTeamScorestringcurrent away team score as a string value
clockSecondsTimeintcurrent game time elapsed in seconds
commentGamealpha numericunique record reference key of the game comment
currentClockTimedateTimeThe current clock time within the match fixture ("01:41") means 1 minute 41 seconds into the match
homeTeamScorestringcurrent home team score as a string value
isTeamHomestring"1" for home or "0" for away represented as a string
latestTextstringThe textual commentary string/paragraph containing key data points pertaining to triggers/market types/data points requested
oppositionTeamNamestringThe opposition team name (the other team who are playing the team requested in the url)
periodstringthe period in the match represented by a string where "0" is the first half and "1" is the second half
seasonGamealpha numericUnique reference for this game within the season
teamIdalpha numericThe unique team reference key
teamNamestringThe 'requested' team name asked for in the url header via teamId
timestampUTC dateTimeThe timestamp the event was first created
triggerstringTime in the day trigger point (Pre match, Post match, in play) when this endpoint is being requested
**Sample Response Extract** ```json [ { "awayTeamScore": "0", "clockSecondsTime": 0, "commentGame": "8780f158-052f-4f70-80c8-5d748f1494fe", "currentClockTime": "02:50", "homeTeamScore": "0", "isTeamHome": "1", "latestText": "This season, Maccabi Netanya has a goal average of 1.25 (1.25 home vs 1.25 away). This season, Hapoel Beer Sheva has a goal average of 0.75 (1.0 home vs 0.5 away). This season, Maccabi Netanya has a shots on target average of 4.88 (5.5 home vs 4.25 away). This season, Hapoel Beer Sheva has a shots on target average of 5.88 (3.75 home vs 8.0 away)", "oppositionTeamName": "Hapoel Beer Sheva", "period": "0", "seasonGame": "ea84a55d-0407-435b-bd80-a4fc1d3e3231", "teamId": "023356e9-3287-46a5-973a-9c71b02e4de6", "teamName": "Maccabi Netanya", "timestamp": "2023-12-11T17:05:52Z", "trigger": "SoccerPostMatch_TODAY" }, { "awayTeamScore": "0", "clockSecondsTime": 0, "commentGame": "8780f158-052f-4f70-80c8-5d748f1494fe", "currentClockTime": "48:07", "homeTeamScore": "0", "isTeamHome": "1", "latestText": "Team Maccabi Netanya is on the rank 9 of scoring goals in the last 10 minutes this season. Team Hapoel Beer Sheva is on the rank 5 of scoring goals in the last 10 minutes this season. Team Hapoel Beer Sheva average time of receiving a first yellow card this season is 36 minutes.", "oppositionTeamName": "Hapoel Beer Sheva", "period": "1", "seasonGame": "ea84a55d-0407-435b-bd80-a4fc1d3e3231", "teamId": "023356e9-3287-46a5-973a-9c71b02e4de6", "teamName": "Maccabi Netanya", "timestamp": "2023-12-11T18:19:54Z", "trigger": "SoccerInPlay_TODAY" } ] ``` **Response headers**