Team Highlights

Get games with video highlights for a specific team/competitor

GET /games/highlights

Game Highlights

cURL

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

Team Highlights

Retrieve games that have video highlights available for a specific team or competitor.

Endpoint

GET /games/highlights

Description

Returns a list of games with video highlights (typically YouTube videos) for a specific competitor. This endpoint filters to only return games where highlight videos are available.

Parameters

Parameter	Type	Required	Description
competitors	number	Yes	The competitor (team) ID to get highlights for

Auto-Resolved Parameters

These parameters are automatically determined by the API based on the user’s context:

Parameter	Description
appTypeId	Client application type identifier
langId	Language identifier for localized content
timezoneName	User’s timezone for time formatting (can be overridden with IANA timezone, e.g., America/New_York)
userCountryId	User’s country for regional content

All startTime fields use ISO 8601 format with a dynamic timezone offset based on the resolved or specified timezone.

Request Example

cURL

curl -X GET "https://v1.football.sportsapipro.com/games/highlights?competitors=110" \
  -H "x-api-key: YOUR_API_KEY"

Response Structure

{
  "lastUpdateId": 0,
  "ttl": 0,
  "sports": [...],
  "countries": [...],
  "competitions": [...],
  "competitors": [...],
  "games": [...]
}

Response Fields

Root Object

Field	Type	Description
lastUpdateId	number	Internal versioning ID for caching
ttl	number	Time To Live in seconds
sports	array	Sport definitions
countries	array	Country data
competitions	array	Competition details
competitors	array	Team/competitor details
games	array	Games with available highlights

Game Object (with Video)

{
  "id": 4609055,
  "sportId": 1,
  "competitionId": 9,
  "seasonNum": 66,
  "stageNum": 6,
  "groupNum": 3,
  "roundName": "Round",
  "stageName": "Quarter Finals",
  "competitionDisplayName": "EFL Cup - Quarter Finals",
  "startTime": "2025-12-17T19:30:00+00:00",
  "statusGroup": 4,
  "statusText": "Ended",
  "homeCompetitor": {...},
  "awayCompetitor": {...},
  "venue": {
    "id": 3911,
    "name": "Etihad Stadium",
    "shortName": "etihad-stadium"
  },
  "hasVideo": true,
  "video": {
    "id": "BHn1zGTwRqM",
    "type": 1,
    "url": "https://www.youtube.com/watch?v=BHn1zGTwRqM",
    "source": 1,
    "isEmbedded": true,
    "embedElement": "<iframe width=#w height=#h src=https://www.youtube.com/embed/#id frameborder=0></iframe>"
  }
}

Video Object

Field	Type	Description
id	string	Video identifier (e.g., YouTube video ID)
type	number	Video type (1 = highlight reel)
url	string	Direct URL to the video
source	number	Video source (1 = YouTube)
isEmbedded	boolean	Whether video can be embedded
embedElement	string	HTML template for embedding (replace #w, #h, #id)

Video Sources

Value	Source
1	YouTube

Video Types

Value	Type
1	Match Highlights

Competitor Object

{
  "id": 110,
  "countryId": 1,
  "sportId": 1,
  "name": "Manchester City",
  "shortName": "Man City",
  "longName": "Manchester City FC",
  "symbolicName": "MCI",
  "score": 2.0,
  "isQualified": true,
  "toQualify": true,
  "isWinner": true,
  "nameForURL": "manchester-city",
  "type": 1,
  "popularityRank": 57273,
  "imageVersion": 1,
  "color": "#ABD1F5",
  "awayColor": "#000000",
  "mainCompetitionId": 7,
  "hasSquad": true,
  "hasTransfers": false,
  "competitorNum": 1,
  "hideOnSearch": false,
  "hideOnCatalog": false
}

Field	Type	Description
id	number	Competitor unique identifier
countryId	number	Country of the competitor
sportId	number	Sport type identifier
name	string	Display name
shortName	string	Short/abbreviated name
longName	string	Full official name
symbolicName	string	3-letter code (e.g., “MCI”)
score	number	Score in the match
isQualified	boolean	Whether team has qualified
toQualify	boolean	Whether team is set to qualify
isWinner	boolean	Whether team won the match
nameForURL	string	URL-safe name
type	number	Competitor type (1 = club)
popularityRank	number	Popularity score
imageVersion	number	Version for team logo
color	string	Primary team color (hex)
awayColor	string	Away kit color (hex)
mainCompetitionId	number	Primary competition ID
hasSquad	boolean	Whether squad data is available
hasTransfers	boolean	Whether transfer data is available
competitorNum	number	Position in match (1=home, 2=away)

Use Cases

Display Team Highlight Videos

const teamId = 110; // Manchester City
const highlights = await sportsApi.get('/games/highlights', {
  competitors: teamId
});

highlights.games.forEach(game => {
  if (game.hasVideo && game.video) {
    const { homeCompetitor, awayCompetitor, video } = game;
    
    console.log(`${homeCompetitor.shortName} vs ${awayCompetitor.shortName}`);
    console.log(`Watch: ${video.url}`);
  }
});

Embed Video Player

const highlights = await sportsApi.get('/games/highlights', {
  competitors: 110
});

const game = highlights.games[0];
if (game?.video?.isEmbedded) {
  // Replace placeholders in embed template
  const embedHtml = game.video.embedElement
    .replace('#w', '560')
    .replace('#h', '315')
    .replace('#id', game.video.id);
  
  // embedHtml: <iframe width=560 height=315 src=https://www.youtube.com/embed/BHn1zGTwRqM frameborder=0></iframe>
}

Build Highlights Gallery

const highlights = await sportsApi.get('/games/highlights', {
  competitors: 110
});

const gallery = highlights.games.map(game => ({
  matchTitle: `${game.homeCompetitor.shortName} ${game.homeCompetitor.score} - ${game.awayCompetitor.score} ${game.awayCompetitor.shortName}`,
  competition: game.competitionDisplayName,
  date: new Date(game.startTime).toLocaleDateString(),
  thumbnailUrl: `https://img.youtube.com/vi/${game.video.id}/hqdefault.jpg`,
  videoUrl: game.video.url,
  venue: game.venue?.name
}));

YouTube Thumbnail URLs

For YouTube videos, you can construct thumbnail URLs using the video ID:

Quality	URL Pattern
Default	https://img.youtube.com/vi/{videoId}/default.jpg
Medium	https://img.youtube.com/vi/{videoId}/mqdefault.jpg
High	https://img.youtube.com/vi/{videoId}/hqdefault.jpg
Max	https://img.youtube.com/vi/{videoId}/maxresdefault.jpg

Notes

• Only games with available video highlights are returned
• Videos are typically from YouTube and can be embedded
• The embedElement template uses placeholders: #w (width), #h (height), #id (video ID)
• Highlight videos are usually available shortly after matches end
• The hasVideo flag confirms video availability for each game

Authorizations

x-api-key · string · header · required

Your SportsAPI Pro API key

Query Parameters

gameId · integer

Game identifier (optional - returns all highlights if not specified)

Example:

4609057

Response

200

Game highlights retrieved successfully