Highlights

Highlights are the core of the NFL & NCAAF API. They cover everything from a single touchdown pass through to full game recaps and pre and post match interviews.

Refresh interval

Once a minute

Plan

Might have certain restrictions on Basic/Free

Pagination

limit and offset

Verified and unverified clips

Clips are aggregated from many different platforms. Depending on the source and what verification it has been through, each one falls into one of two types.

Reading a highlight

Every highlight carries a title describing what the video shows. Many also carry a description that expands on it.

The source field records where the clip was aggregated from, for example youtube, twitter, reddit or espn. For some sources a channel is present as well, which is the uploading channel's title. Together these let you narrow down which videos you want to show. Where embedUrl is present you can embed the video directly in your own site or app.

Categories

The category field describes what kind of content the clip contains. Categorisation happens automatically when a highlight is aggregated. A clip that cannot be placed confidently is labelled other rather than being forced into a category it does not belong to, so filtering on category in your own code will not return unrelated content.

The vocabulary is specific to American football, and it distinguishes scoring plays by how the score happened.

Plan coverage

On the Basic plan, NFL highlights are excluded. A Pro plan or higher removes the restriction and returns highlights from every league this API covers.

Querying

At least one primary query parameter must be specified before you can retrieve data. timezone, limit and offset are secondary and do not count on their own.

Combine timezone with date to get highlights relevant to your own location. Filter by league with leagueName, or by game with matchId. Teams can be filtered by id, name, abbreviation or display name, so homeTeamAbbreviation works without resolving an id first.

limit sets how many highlights come back. When the number of matching highlights exceeds it, request the next page by increasing offset. The pagination object in every response tells you the totalCount to page through.

Parameters

Request

curl --request GET \
  --url 'https://american-football.highlightly.net/highlights?leagueName=NCAA&date=2024-08-31' \
  --header 'x-rapidapi-key: YOUR_API_KEY'

const params = new URLSearchParams({
  leagueName: 'NCAA',
  date: '2024-08-31'
})
const response = await fetch(`https://american-football.highlightly.net/highlights?${params}`, {
  headers: {
    'x-rapidapi-key': process.env.HIGHLIGHTLY_API_KEY
  }
})

if (!response.ok) {
  throw new Error(`Highlightly responded ${response.status}`)
}

const data = await response.json()

import os
import requests

response = requests.get(
    'https://american-football.highlightly.net/highlights',
    params={
        'leagueName': 'NCAA',
        'date': '2024-08-31',
    },
    headers={
        'x-rapidapi-key': os.environ['HIGHLIGHTLY_API_KEY'],
    },
    timeout=10,
)

response.raise_for_status()
data = response.json()

Response

Example response

{
  "data": [
    {
      "id": 1,
      "type": "VERIFIED",
      "imgUrl": "https://example.com/images/preview/1.png",
      "title": "NFL: New Orleans Saints vs Kansas City Chiefs",
      "description": "Game recap of the match.",
      "url": "https://example.com/highlight/v23r23fds2cff",
      "embedUrl": "https://example.com/embed/v23r23fds2cff",
      "match": {
        "id": 1,
        "round": "Regular Season - 32",
        "date": "2023-05-20T15:30:00.000Z",
        "league": "NFL",
        "season": 2023,
        "awayTeam": {
          "id": 1,
          "logo": "https://example.com/logos/team/111.png",
          "name": "Saints",
          "displayName": "New Orleans Saints",
          "abbreviation": "NO"
        },
        "homeTeam": {
          "id": 1,
          "logo": "https://example.com/logos/team/111.png",
          "name": "Saints",
          "displayName": "New Orleans Saints",
          "abbreviation": "NO"
        },
        "state": {
          "period": 2,
          "clock": 8,
          "description": "In progress",
          "score": {
            "current": "21 - 7",
            "firstPeriod": "0 - 0",
            "secondPeriod": "7 - 7",
            "thirdPeriod": "7 - 0",
            "fourthPeriod": "7 - 0",
            "firstOvertimePeriod": "7 - 0",
            "secondOvertimePeriod": "7 - 0"
          },
          "report": "Final"
        }
      },
      "channel": "NFL",
      "source": "youtube",
      "category": "match-highlights"
    }
  ],
  "pagination": {
    "totalCount": 490,
    "offset": 20,
    "limit": 100
  },
  "plan": {
    "tier": "BASIC",
    "message": "Some results might be hidden with FREE tier. Check your API coverage for more information: https://rapidapi.com/highlightly-api-highlightly-api-default/api/sport-highlights-api/details"
  }
}

Values are the examples declared in the OpenAPI spec, not a captured live response.

Errors