NFL & NCAAF API / matches

Get match by ID

GET https://american-football.highlightly.net/matches/{id} NFL & NCAAF API
GET https://sports.highlightly.net/american-football/matches/{id} All Sports API

Retrieve detailed information for one match.

This is the detail view. Matches returns general information for a list of games. This route returns the same fields plus six optional ones.

Injuries are part of this response rather than a separate endpoint, so an availability view is built from here.

Parameters

Parameter Type Description
idrequired numberpath Requested match id.

Request

curl --request GET \
  --url 'https://american-football.highlightly.net/matches/{id}' \
  --header 'x-rapidapi-key: YOUR_API_KEY'
const response = await fetch('https://american-football.highlightly.net/matches/{id}', {
  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/matches/{id}',
    headers={
        'x-rapidapi-key': os.environ['HIGHLIGHTLY_API_KEY'],
    },
    timeout=10,
)

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

Response

idnumberrequired
roundstringrequired
datestringrequired
leaguestringrequired
seasonnumberrequired
awayTeamAmericanFootballMatchTeamResponserequired5 fields
idnumberrequired
logostring
namestring
displayNamestringrequired
abbreviationstringrequired
homeTeamAmericanFootballMatchTeamResponserequired5 fields
idnumberrequired
logostring
namestring
displayNamestringrequired
abbreviationstringrequired
stateAmericanFootballMatchStateResponserequired12 fields
periodnumberCurrent in play period.
clocknumberCurrent minute of the in play period.
descriptionstringrequiredCurrent status/description of the match.SuspendedPostponedCancelledAbandonedFinishedIn progressEnd periodHalf timeUnknownScheduled
scoreAmericanFootballMatchScoreResponserequired7 fields
currentstringHome - Away score for the match.
firstPeriodstringHome - Away score in 1st period.
secondPeriodstringHome - Away score in 2nd period.
thirdPeriodstringHome - Away score in 3rd period.
fourthPeriodstringHome - Away score in 4th period.
firstOvertimePeriodstringHome - Away score in the first overtime period.
secondOvertimePeriodstringHome - Away score in the second overtime period.
reportstringAdditional description of the match state.
venueAmericanFootballMatchVenueResponse3 fields
citystringrequired
namestringrequired
statestringrequired
forecastDetailedMatchForecastResponse2 fields
statusstring
temperaturestring
matchStatisticsAmericanFootballMatchStatsResponse8 fields
homeTeamTeamStatisticsResponserequired3 fields
statisticsStatisticsItem[]required2 fields
namestringrequired
valuenumberrequired
awayTeamTeamStatisticsResponserequired3 fields
statisticsStatisticsItem[]required2 fields
namestringrequired
valuenumberrequired
injuriesAmericanFootballInjuriesResponse[]13 fields
teamAmericanFootballTeamDataResponserequired6 fields
idnumberrequired
logostringrequired
namestringrequired
leaguestringrequired
displayNamestringrequired
abbreviationstringrequired
dataAmericanFootballInjuryDataItem[]required5 fields
statusstringrequired
playerAmericanFootballInjuryItemPlayerrequired3 fields
namestringrequired
jerseynumber
positionstring
eventsAmericanFootballEventResponse[]37 fields
endAmericanFootballEventStartEndPeriodResponserequired3 fields
clockstringrequired
periodstringrequired
yardLinenumberrequired
teamAmericanFootballTeamDataResponserequired6 fields
idnumberrequired
logostringrequired
namestringrequired
leaguestringrequired
displayNamestringrequired
abbreviationstringrequired
playsstring[]required
playDetailsAmericanFootballPlayDetailResponse[]requiredStructured counterpart to plays, in the same order and of the same length. Carries down and distance, which the plays strings do not.17 fields
startAmericanFootballDownDistanceResponseSituation at the snap.5 fields
downnumberCurrent down, 1 through 4. Null on non-scrimmage plays such as kickoffs, timeouts and period markers.
distancenumberYards required for a first down. Null wherever down is null. Goal-to-go when equal to yardsToEndzone.
yardLinenumber
yardsToEndzonenumber
possessionTextstring
endAmericanFootballDownDistanceResponseSituation after the play resolves. For a live view of the current game state, read this from the most recent play.5 fields
downnumberCurrent down, 1 through 4. Null on non-scrimmage plays such as kickoffs, timeouts and period markers.
distancenumberYards required for a first down. Null wherever down is null. Goal-to-go when equal to yardsToEndzone.
yardLinenumber
yardsToEndzonenumber
possessionTextstring
textstringrequiredNarrative play text. Matches the corresponding entry in the drive plays array.
typestringPlay classification, for example Rush, Pass Reception, Kickoff, Penalty, Official Timeout.
periodnumber
clockstring
isPenaltybooleanrequired
startAmericanFootballEventStartEndPeriodResponserequired3 fields
clockstringrequired
periodstringrequired
yardLinenumberrequired
resultstringrequired
descriptionstringrequired
isScoringPlaybooleanrequired
predictionsPredictionResponse18 fields
prematchPrediction[]required8 fields
typestringrequired
modelTypestringrequired
generatedAtstringrequired
descriptionstringrequired
probabilitiesPredictionProbabilitiesrequired3 fields
homestringrequired
drawstring
awaystringrequired
livePrediction[]required8 fields
typestringrequired
modelTypestringrequired
generatedAtstringrequired
descriptionstringrequired
probabilitiesPredictionProbabilitiesrequired3 fields
homestringrequired
drawstring
awaystringrequired

Example response

200 application/json 
[
  {
    "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"
    },
    "venue": {
      "city": "Baltimore",
      "name": "M&T Bank Stadium",
      "state": "MD"
    },
    "forecast": {
      "status": "cloudy",
      "temperature": "11.97°C"
    },
    "matchStatistics": {
      "homeTeam": {
        "statistics": [
          {
            "name": "Rushing Attempts",
            "value": 34
          }
        ]
      },
      "awayTeam": {
        "statistics": [
          {
            "name": "Rushing Attempts",
            "value": 34
          }
        ]
      }
    },
    "injuries": [
      {
        "team": {
          "id": 35,
          "logo": "https://highlightly.net/american-football/images/teams/35.png",
          "name": "Saints",
          "league": "NFL",
          "displayName": "New Orleans Saints",
          "abbreviation": "NO"
        },
        "data": [
          {
            "status": "Questionable",
            "player": {
              "name": "Alvin Kamara",
              "jersey": 41,
              "position": "Running Back"
            }
          }
        ]
      }
    ],
    "events": [
      {
        "end": {
          "clock": "11:43",
          "period": "1st quarter",
          "yardLine": 40
        },
        "team": {
          "id": 35,
          "logo": "https://highlightly.net/american-football/images/teams/35.png",
          "name": "Saints",
          "league": "NFL",
          "displayName": "New Orleans Saints",
          "abbreviation": "NO"
        },
        "plays": [
          ""
        ],
        "playDetails": [
          {
            "start": {
              "down": 3,
              "distance": 7,
              "yardLine": 71,
              "yardsToEndzone": 29,
              "possessionText": "DET 29"
            },
            "end": {
              "down": 3,
              "distance": 7,
              "yardLine": 71,
              "yardsToEndzone": 29,
              "possessionText": "DET 29"
            },
            "text": "C.Brown up the middle to CIN 31 for 5 yards (D.White).",
            "type": "Pass Reception",
            "period": 1,
            "clock": "14:53",
            "isPenalty": false
          }
        ],
        "start": {
          "clock": "11:43",
          "period": "1st quarter",
          "yardLine": 40
        },
        "result": "Punt",
        "description": "5 plays, 6 yards, 3:17",
        "isScoringPlay": false
      }
    ],
    "predictions": {
      "prematch": [
        {
          "type": "prematch",
          "modelType": "three-way",
          "generatedAt": "2025-03-12T19:00:20.000Z",
          "description": "Team A is most likely to win the game against Team B.`",
          "probabilities": {
            "home": "30.22%",
            "draw": "0.00%",
            "away": "69.78%"
          }
        }
      ],
      "live": [
        {
          "type": "prematch",
          "modelType": "three-way",
          "generatedAt": "2025-03-12T19:00:20.000Z",
          "description": "Team A is most likely to win the game against Team B.`",
          "probabilities": {
            "home": "30.22%",
            "draw": "0.00%",
            "away": "69.78%"
          }
        }
      ]
    }
  }
]

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

Errors

Status Description
400 Bad request descriptive error.
500 Internal server error.