NBA & NCAAB API / head-2-head

Head to head

GET https://nba.highlightly.net/head-2-head NBA & NCAAB API
GET https://sports.highlightly.net/nba/head-2-head All Sports API

Retrieve the last ten head to head games between two teams.

Pagination
Not paginated

Specify teamIdOne and teamIdTwo, both from teams. The order does not matter, so you do not need to work out which side is at home before calling.

Use it to compare two teams on their past results, which is the usual companion to a game preview. For each team's recent form independent of the opponent, use last five games.

A head to head comparison between two teams

Parameters

Parameter Type Description
teamIdOnerequired number No description in the spec.e.g. 3
teamIdTworequired number No description in the spec.e.g. 23

Request

curl --request GET \
  --url 'https://nba.highlightly.net/head-2-head?teamIdOne=3&teamIdTwo=23' \
  --header 'x-rapidapi-key: YOUR_API_KEY'
const params = new URLSearchParams({
  teamIdOne: '3',
  teamIdTwo: '23'
})
const response = await fetch(`https://nba.highlightly.net/head-2-head?${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://nba.highlightly.net/head-2-head',
    params={
        'teamIdOne': '3',
        'teamIdTwo': '23',
    },
    headers={
        'x-rapidapi-key': os.environ['HIGHLIGHTLY_API_KEY'],
    },
    timeout=10,
)

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

Response

idnumberrequired
leaguestringrequiredNBANCAA
seasonnumberrequired
stateNbaMatchStateResponserequired6 fields
clocknumberrequiredTime left for a game to finish.
scoreNbaMatchScoreResponserequired2 fields
awayTeamnumber[]requiredCurrent away team result for each inning.
homeTeamnumber[]requiredCurrent home team result for each inning.
periodnumberrequiredCurrent period
descriptionstringrequiredCurrent game state descriptionSuspendedPostponedCancelledAbandonedFinishedScheduledIn progressEnd periodHalf timeUnknown
homeTeamNbaTeamInfoResponserequired5 fields
idnumberrequired
displayNamestringrequired
namestringrequired
logostring
abbreviationstringrequired
awayTeamNbaTeamInfoResponserequired5 fields
idnumberrequired
displayNamestringrequired
namestringrequired
logostring
abbreviationstringrequired
datestringrequired

Example response

200 application/json 
[
  {
    "id": 5294,
    "league": "NBA",
    "season": 2024,
    "state": {
      "clock": 0,
      "score": {
        "awayTeam": [
          0
        ],
        "homeTeam": [
          0
        ]
      },
      "period": 4,
      "description": "Finished"
    },
    "homeTeam": {
      "id": 3,
      "displayName": "Denver Nuggets",
      "name": "Nuggets",
      "logo": "https://highlightly.net/nba/images/teams/3.png",
      "abbreviation": "DEN"
    },
    "awayTeam": {
      "id": 3,
      "displayName": "Denver Nuggets",
      "name": "Nuggets",
      "logo": "https://highlightly.net/nba/images/teams/3.png",
      "abbreviation": "DEN"
    },
    "date": "2024-04-07T01:00:00.000Z"
  }
]

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.