Matches

Retrieve a list of matches.

Refresh interval

Once a minute

Pagination

limit and offset

Detail

General information only

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 matches relevant to your own location. timezone defaults to Etc/UTC.

Teams can be filtered by id, name, abbreviation or display name, so homeTeamAbbreviation works without resolving an id first. league separates professional from college.

limit sets how many matches come back. When the number of matching games exceeds it, request the next page by increasing offset. See Pagination and limits.

Match states

Every match carries a state, and that object is where the live detail sits. It holds the state itself as description, the period currently being played, clock as the current minute of that period, the score, and a report giving a short summary such as Final.

So a single call to this endpoint gives you a scoreboard. You do not need the detail route to show the score, the quarter and the current minute.

Parameters

Request

curl --request GET \
  --url 'https://american-football.highlightly.net/matches?league=NFL&date=2024-08-23' \
  --header 'x-rapidapi-key: YOUR_API_KEY'

const params = new URLSearchParams({
  league: 'NFL',
  date: '2024-08-23'
})
const response = await fetch(`https://american-football.highlightly.net/matches?${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/matches',
    params={
        'league': 'NFL',
        'date': '2024-08-23',
    },
    headers={
        'x-rapidapi-key': os.environ['HIGHLIGHTLY_API_KEY'],
    },
    timeout=10,
)

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

Response

Example response

{
  "data": [
    {
      "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"
      }
    }
  ],
  "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