Get Match Commentary

GET

games

commentary

Game Commentary

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

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sportsapipro.com/v1/football/games/commentary', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sportsapipro.com/v1/football/games/commentary",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sportsapipro.com/v1/football/games/commentary"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sportsapipro.com/v1/football/games/commentary")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

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

integer

required

The unique game/match identifier.

string

required

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

string

default:"all"

Commentary filter:

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

boolean

default:"false"

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

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 -X GET "https://api.sportsapipro.com/v1/football/games/commentary?gameId=4452706&fixtureId=2yuulrtp37mbqe9rok936lslw&filter=all" \
  -H "x-api-key: YOUR_API_KEY"

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

const response = await fetch(
  'https://api.sportsapipro.com/v1/football/games/commentary?gameId=4452706&fixtureId=2yuulrtp37mbqe9rok936lslw&filter=all',
  {
    headers: {
      'x-api-key': 'YOUR_API_KEY'
    }
  }
);
const data = await response.json();

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://api.sportsapipro.com/v1/football/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://api.sportsapipro.com/v1/football/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

Last modified on June 29, 2026

Game Commentary

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

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sportsapipro.com/v1/football/games/commentary', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sportsapipro.com/v1/football/games/commentary",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sportsapipro.com/v1/football/games/commentary"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sportsapipro.com/v1/football/games/commentary")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

API Reference

Guides

Popular Sports

Team Sports

Racquet & Precision Sports

Specialty Sports

V3 API

V4 Odds API

V6 AiScore API

V1 Legacy

Football V1

Basketball V1

Tennis V1

Hockey V1

Overview

Parameters

Request

Response

Response Fields

Root Level

Message Object

Message Types

Period Values

Obtaining the fixtureId

Real-time Updates

Use Cases

Authorizations

Query Parameters

Response

​Overview

​Parameters

​Request

​Response

​Response Fields

​Root Level

​Message Object

​Message Types

​Period Values

​Obtaining the fixtureId

​Real-time Updates

​Use Cases

Authorizations

Query Parameters

Response

Overview

Parameters

Request

Response

Response Fields

Root Level

Message Object

Message Types

Period Values

Obtaining the fixtureId

Real-time Updates

Use Cases