MLB & NCAA API / matches

Matches

GET https://baseball.highlightly.net/matches MLB & NCAA API
GET https://sports.highlightly.net/baseball/matches All Sports API

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 rather than UTC.

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

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 object. Its description holds one of the values below, and score holds the score. Some matches also carry report, an additional description of the state such as Final.

State Meaning
Scheduled Match has not been started yet.
In Progress Game is currently in progress.
Period End Break time between periods.
Half Time Half time pause between the first and second half.
Rain Delay Delayed for bad weather. Will either be resumed or suspended.
Finished Match has been concluded.
Postponed Prevented from being played. The start time moves to a future moment.
Suspended Was in play and was halted. Will resume from the exact point it stopped.
Canceled Game will not be played.
Abandoned Ended prematurely by the officials and cannot be resumed or completed, though it may be resumed later from the point it stopped.
Unknown Unknown coverage or state.

Baseball matches rendered in a client application

Parameters

Parameter Type Description
leagueoptional string No description in the spec.e.g. MLB
dateoptional string Date that follows the YYYY-MM-DD format.e.g. 2024-08-31
timezoneoptional stringdefault Etc/UTC Valid timezone identifier.e.g. Europe/London
seasonoptional number No description in the spec.e.g. 2024
homeTeamIdoptional number No description in the spec.e.g. 10291199
awayTeamIdoptional number No description in the spec.e.g. 10291203
homeTeamNameoptional string No description in the spec.e.g. Rangers
awayTeamNameoptional string No description in the spec.e.g. Athletics
homeTeamAbbreviationoptional string No description in the spec.e.g. TEX
awayTeamAbbreviationoptional string No description in the spec.e.g. OAK
homeTeamDisplayNameoptional string No description in the spec.e.g. Texas Rangers
awayTeamDisplayNameoptional string No description in the spec.e.g. Oakland Athletics
limitoptional numberdefault 100 No description in the spec.e.g. 100
offsetoptional numberdefault 0 No description in the spec.e.g. 0

Request

curl --request GET \
  --url 'https://baseball.highlightly.net/matches?league=MLB&date=2024-08-31' \
  --header 'x-rapidapi-key: YOUR_API_KEY'
const params = new URLSearchParams({
  league: 'MLB',
  date: '2024-08-31'
})
const response = await fetch(`https://baseball.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://baseball.highlightly.net/matches',
    params={
        'league': 'MLB',
        'date': '2024-08-31',
    },
    headers={
        'x-rapidapi-key': os.environ['HIGHLIGHTLY_API_KEY'],
    },
    timeout=10,
)

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

Response

dataBaseballMatchResponse[]required30 fields
idnumberrequired
roundstringrequired
datestringrequired
leaguestringrequired
seasonnumberrequired
awayTeamBaseballMatchTeamResponserequired5 fields
idnumberrequired
logostring
namestring
displayNamestringrequired
abbreviationstringrequired
homeTeamBaseballMatchTeamResponserequired5 fields
idnumberrequired
logostring
namestring
displayNamestringrequired
abbreviationstringrequired
stateBaseballMatchStateResponserequired12 fields
descriptionstringrequiredFinishedPostponedPeriod EndRain DelayScheduledHalf TimeIn ProgressCanceledUnknownSuspendedAbandoned
reportstringAdditional description of the match state.
scoreBaseballMatchScoreResponserequired9 fields
homeBaseballMatchScorerequired3 fields
hitsnumber
errorsnumber
inningsstring[]requiredScores for each played inning.
awayBaseballMatchScorerequired3 fields
hitsnumber
errorsnumber
inningsstring[]requiredScores for each played inning.
currentstring
paginationPaginationResponserequired3 fields
totalCountnumberrequiredAvailable number of items, relevant to the provided query.
offsetnumberrequired
limitnumberrequired
planPlanResponserequired2 fields
tierstringrequiredYour current API subscription tier.
messagestringrequiredExplanation message regarding your current tier.

Example response

200 application/json 
{
  "data": [
    {
      "id": 394,
      "round": "regular-season",
      "date": "2024-03-06T00:30:00.000Z",
      "league": "NCAA",
      "season": 2024,
      "awayTeam": {
        "id": 219,
        "logo": "https://example.com/logos/team/219.png",
        "name": "Bears",
        "displayName": "Baylor",
        "abbreviation": "BAY"
      },
      "homeTeam": {
        "id": 219,
        "logo": "https://example.com/logos/team/219.png",
        "name": "Bears",
        "displayName": "Baylor",
        "abbreviation": "BAY"
      },
      "state": {
        "description": "Finished",
        "report": "Final",
        "score": {
          "home": {
            "hits": 4,
            "errors": 2,
            "innings": [
              0,
              0,
              1,
              1,
              0,
              0,
              1,
              1,
              1
            ]
          },
          "away": {
            "hits": 4,
            "errors": 2,
            "innings": [
              0,
              0,
              1,
              1,
              0,
              0,
              1,
              1,
              1
            ]
          },
          "current": "5 - 8"
        }
      }
    }
  ],
  "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

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