Skip to main content
GET
/
games
/
highlights
Game Highlights
curl --request GET \
  --url https://v1.football.sportsapipro.com/games/highlights \
  --header 'x-api-key: <api-key>'

​
Overview

The Game Highlights endpoint returns notable recent games for specified competitors, including match results, venue information, and video highlight links (typically YouTube embeds).

​
Query Parameters

​
competitors
string
required
Comma-separated list of competitor IDs to get highlights for
​
numberOfGames
integer
default:"5"
Number of highlighted games to return
​
appTypeId
integer
Application type identifier (auto-resolved)
​
langId
integer
Language identifier (auto-resolved)
​
timezoneName
string
Timezone for date/time values (auto-resolved, or specify e.g., America/New_York).
All startTime fields use ISO 8601 format with a dynamic timezone offset based on the resolved or specified timezone.
​
userCountryId
integer
User’s country for localization (auto-resolved)

​
Response Structure

​
lastUpdateId
integer
Internal versioning ID for caching and incremental updates
​
ttl
integer
Time to live in seconds for cache validity
​
sports
array
Array of sport definitions
​
countries
array
Array of country definitions
​
competitions
array
Array of competition definitions
​
competitors
array
Array of competitor/team definitions
​
games
array
Array of highlighted games

​
Status Groups

ValueDescription
1Not Started
2Scheduled
3Live/In Progress
4Ended
5Postponed

​
Video Sources

ValueDescription
1YouTube

​
Example Request

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

​
Example Response

{
  "lastUpdateId": 0,
  "ttl": 0,
  "sports": [
    {
      "id": 1,
      "name": "Football",
      "nameForURL": "football",
      "drawSupport": true,
      "imageVersion": 1
    }
  ],
  "countries": [
    {
      "id": 1,
      "name": "England",
      "nameForURL": "england",
      "sportTypes": [1, 9, 11],
      "imageVersion": 1,
      "isInternational": false
    }
  ],
  "competitions": [
    {
      "id": 9,
      "countryId": 1,
      "sportId": 1,
      "name": "EFL Cup",
      "longName": "EFL Carabao Cup",
      "hasStandings": false,
      "hasBrackets": true,
      "nameForURL": "efl-cup",
      "popularityRank": 23075590,
      "imageVersion": 5,
      "color": "#008F5E"
    }
  ],
  "competitors": [
    {
      "id": 110,
      "countryId": 1,
      "sportId": 1,
      "name": "Manchester City",
      "shortName": "Man City",
      "symbolicName": "MCI",
      "score": 2.0,
      "isWinner": true,
      "nameForURL": "manchester-city",
      "imageVersion": 1,
      "color": "#ABD1F5"
    }
  ],
  "games": [
    {
      "id": 4609055,
      "sportId": 1,
      "competitionId": 9,
      "competitionDisplayName": "EFL Cup - Quarter Finals",
      "startTime": "2025-12-17T19:30:00+00:00",
      "statusGroup": 4,
      "statusText": "Ended",
      "homeCompetitor": {
        "id": 110,
        "name": "Manchester City",
        "shortName": "Man City",
        "score": 2.0,
        "isWinner": true
      },
      "awayCompetitor": {
        "id": 63,
        "name": "Brentford",
        "score": 0.0,
        "isWinner": false
      },
      "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>"
      }
    }
  ]
}

​
Use Cases

  1. Team Highlight Reels: Display recent notable matches with video highlights
  2. Match Recaps: Show game results with embedded video playback
  3. Fan Engagement: Quick access to exciting recent games
  4. Content Discovery: Feature games with available video content

​
Video Embedding

When hasVideo is true, use the video.embedElement template:
  • Replace #id with video.id
  • Replace #w and #h with desired width and height
const embedHtml = video.embedElement
  .replace('#id', video.id)
  .replace('#w', '560')
  .replace('#h', '315');

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