Get Match Commentary

Retrieve live play-by-play commentary and match analysis for a specific game.

GET /games/commentary

Game Commentary

cURL

curl --request GET \
  --url https://v1.football.sportsapipro.com/games/commentary \
  --header 'x-api-key: <api-key>'

Overview

The Match Commentary endpoint provides real-time play-by-play commentary for games, including match analysis, key events, and post-match summaries. Commentary is available during live matches and for completed games.

Parameters

gameId · integer · required

The unique game/match identifier.

fixtureId · string · required

The fixture identifier for play-by-play data (also known as matchupId). Can be obtained from game details response under playByPlay.fixtureId.

filter · string · default: "all"

Commentary filter:

• all - Returns all commentary messages
• top - Returns key/highlighted moments only (preview)

isLive · boolean · default: "false"

Set to true for live matches to get real-time commentary updates.

isFinished · boolean · default: "true"

Set to true for finished matches, false for ongoing matches.

All LastModified timestamps use ISO 8601 format with UTC timezone (e.g., 2025-12-17T21:22:59Z). Commentary timestamps are always returned in UTC regardless of client timezone.

Request

cURL

curl -X GET "https://v1.football.sportsapipro.com/games/commentary?gameId=4452706&fixtureId=2yuulrtp37mbqe9rok936lslw&filter=all" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "Messages": [
    {
      "Id": 75,
      "InnerId": "10l77cskp8etg1l1omc43oha2w",
      "Comment": "Barrott blows his whistle for one final time then and it's Man City who coast into the EFL Cup semi-finals thanks to a 2-0 win over Brentford in this last-eight contest at the Etihad Stadium...",
      "Type": 4,
      "TypeName": "comment",
      "Period": "14",
      "LastModified": "2025-12-17T21:22:59Z"
    },
    {
      "Id": 74,
      "InnerId": "uyjgus6b2eyw1diutdxoo5a51",
      "Comment": "FULL-TIME: MANCHESTER CITY 2-0 BRENTFORD",
      "Timeline": "90",
      "Type": 4,
      "TypeName": "comment",
      "Period": "2",
      "LastModified": "2025-12-17T21:22:23Z",
      "TimeLineSecondaryText": "+3'",
      "TimeLineSecondaryColor": "#FF5200"
    },
    {
      "Id": 73,
      "InnerId": "nxdsl7nmkbza1w84jikyhoz0j",
      "Comment": "Cherki has been awarded the Man of the Match award and, purely for his outstanding goal (an early Christmas cracker if you will), he probably deserves it.",
      "Timeline": "90",
      "Type": 4,
      "TypeName": "comment",
      "Period": "2",
      "LastModified": "2025-12-17T21:21:07Z",
      "TimeLineSecondaryText": "+2'",
      "TimeLineSecondaryColor": "#FF5200"
    }
  ],
  "UpdateURL": "",
  "TTL": 60
}

Response Fields

Root Level

Field	Type	Description
Messages	array	Array of commentary messages
UpdateURL	string	Reserved field (stripped from response for security)
TTL	integer	Cache TTL in seconds (typically 60)

Message Object

Field	Type	Description
Id	integer	Unique message ID (sequential)
InnerId	string	Internal unique identifier
Comment	string	The commentary text
Timeline	string	Match minute when the event occurred
Type	integer	Message type ID
TypeName	string	Message type name
Period	string	Match period identifier
LastModified	string	ISO 8601 timestamp of last modification
TimeLineSecondaryText	string	Additional time info (e.g., “+3’” for stoppage time)
TimeLineSecondaryColor	string	Color for stoppage time display

Message Types

Type	TypeName	Description
1	goal	Goal scored
2	yellow_card	Yellow card shown
3	red_card	Red card shown
4	comment	General commentary
5	substitution	Player substitution
6	period_start	Period started
7	period_end	Period ended
8	penalty	Penalty event
9	var	VAR decision

Period Values

Period	Description
”1”	First half
”2”	Second half
”3”	First half extra time
”4”	Second half extra time
”5”	Penalty shootout
”14”	Post-match summary

Obtaining the fixtureId

The fixtureId is available in the game details response under the playByPlay object:

// First, get game details
const gameDetails = await fetch(
  'https://v1.football.sportsapipro.com/games/details?gameId=4452706',
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
);
const data = await gameDetails.json();

// Extract fixtureId from playByPlay
const fixtureId = data.game.playByPlay?.fixtureId;
// Example: "2yuulrtp37mbqe9rok936lslw"

// Then fetch commentary
const commentary = await fetch(
  `https://v1.football.sportsapipro.com/games/commentary?gameId=4452706&fixtureId=${fixtureId}`,
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
);

Real-time Updates

For live matches, use the UpdateURL to fetch only new messages after a certain ID:

// Initial fetch
const initial = await fetchCommentary(gameId, matchupId);
let lastId = initial.Messages[0]?.Id;

// Poll for updates
setInterval(async () => {
  const updates = await fetch(initial.UpdateURL + `&afterItem=${lastId}`);
  const newData = await updates.json();
  
  if (newData.Messages.length > 0) {
    lastId = newData.Messages[0].Id;
    // Process new messages
  }
}, initial.TTL * 1000);

Use Cases

• Display live match commentary feed
• Show post-match analysis and summaries
• Build match timeline with key events
• Create highlight reels based on commentary
• Track VAR decisions and penalties

Authorizations

x-api-key · string · header · required

Your SportsAPI Pro API key

Query Parameters

gameId · integer · required

Game identifier

Example:

4452706

fixtureId · string · required

Fixture ID from game details playByPlay.fixtureId

Example:

"2yuulrtp37mbqe9rok936lslw"

filter · enum<string> · default: all

Filter type: 'all' for all commentary, 'top' for highlights only

Available options: all, top

isLive · boolean · default: false

Set to true for live matches

isFinished · boolean · default: true

Set to true for finished matches

Response

200

Game commentary retrieved successfully