MLB, NCAA Baseball API | Highlightly (6.2.1)

Refresh interval: Once a minute

Note: Certain highlights might be uploaded whilst the game is playing. Full game recaps tend to be uploaded anywhere from 1 to 48 hours after a match is finished.

Highlights represent the core of our API. They include various different kinds of clips ranging from real time live events such as insane plays, last minute scores to full game recaps, pre/post match interviews.

Currently we aggregate videos from many different sources. Depending on the source and verification process we divide the clips into two categories:

Each highlight has a title which describes what the video is about. Certain entries will have a description as well which is used to further describe the associated clip. The source field defines where the clip was aggregated from (e.g. would be youtube, twitter, reddit, espn, etc.). For certain sources you will see additional information being present in the channel field. By utilising this information you can further narrow down which videos you want to showcase. Highlights might also have an embedUrl property which is used to directly embed the videos into your website or mobile application.

Below is an example of what you can aim to achieve with our highlights data:

Retrieve highlights

Retrieve a list of highlights based on the requested query parameters.

At least one primary query parameter needs to be specified before you can retrieve the data (timezone, limit, offset are considered secondary).

You can specify the timezone field in combination with the date query parameter to get highlights relevant to your location.

There are two other important parameters. The limit parameter defines what the number of returned highlights will be. If the number of actual highlights is above the limit value you can make subsequent requests by increasing the offset value.

Note: The Basic/Free plan might have certain restrictions in place. More information can be found here.

Refresh interval: Once an hour

Note: Endpoint is not available in the Basic/Free plan.

Geo restrictions are a plague that have been around for quite a while. They restrict access to online content based on the viewers geographical location. Trying to show restricted highlights to your users can greatly hinder the viewing experience.

Each highlight has a state property which defines how the geo restrictions are applied.

As presented before, certain highlights have an embedUrl field which can be used to directly embed the video into your website or application. The embeddable field specifies whether this is allowed or not.

Retrieve highlight information by specifying the highlight id path parameter.

Note: Used to check whether a highlight still exists or had its information updated.

Refresh interval: Once a minute

Route returns only general match information. For additional match details check the matches/{matchId} route.

Retrieve a list of matches based on the requested query parameters.

At least one primary query parameter needs to be specified before you can retrieve the data (timezone, limit, offset are considered secondary).

You can specify the timezone field in combination with the date query parameter to get matches relevant to your location.

There are two other important parameters. The limit parameter defines what the number of returned matches will be. If the number of actual matches is above the limit value you can make subsequent requests by increasing the offset value.

Matches have different possible states they can be in:

Below is an example of what you can aim to achieve with the matches endpoint:

Retrieve detailed match information by specifying the match id path parameter.

Fetched data will have additional information about the venue, weather forecast, match stats, who the game's referees are, each team's rosters, and plays.

Note: Used to retrieve additional match information.

Retrieve a list of teams that are supported by the API.

By utilising either league, name, displayName or abbreviation query parameters you can check whether a specific team exists or simply retrieve the associated data.

There are two other important query parameters. The limit parameter defines what the number of returned teams will be. If the number of actual teams is above the limit value you can make subsequent requests by increasing the offset value.

Refresh interval: Immediately once a match is finished.

Retrieve team stats for each league and season by specifying the team's id path parameter. Requires fromDate query parameter to be specified in the YYYY-MM-DD format. Additionally, the timezone query parameter can be specified to futher narrow down the search results based on your location.

Retrieve team information by specifying the team id path parameter.

Note: Used to check whether a team still exists or had its information updated.

Refresh interval: Up to an hour after a match for the associated league and season is finished

Retrieve standings data for a specific league, conference or division.

There are numerous ways on how to fetch the data. You can utilise either abbreviation or leagueName:

Additionally you can specify the year parameter to narrow down the the standings for that season.

There are two other important parameters that are used to navigate through the pagination. The limit parameter defines what the number of returned standings will be. If the number of actual standings is above the limit value you can make subsequent requests by increasing the offset value.

Below is an example on how you could render league associated standings

Prematch odds refresh interval: Multiple times a day

Live odds refresh interval: Once every 10 minutes

Note: Endpoint is not available in the Basic/Free plan.

Retrieve a list of match odds based on the requested query parameters. With oddsType query parameter you can specify whether you want prematch or live odds. If you do not set a specific value prematch odds will be returned.

At least one primary query parameter needs to be specified before you can retrieve the data (timezone, limit, offset, oddsType are considered secondary).

The most popular way of getting match odds is by specifying the matchId query parameter. You can also utilise the date parameter alongside the timezone to fetch all match odds for a given day. By specifying league or bookmaker related fields you can further narrow down your search.

As it stands, we currently offer the support for the following markets:

There are two other important query parameters. The limit parameter defines what the number of returned match odds will be. If the number of actual match odds is above the limit value you can make subsequent requests by increasing the offset value.

Match odds are available up to 28 days after the game finishes and up to 7 days before the game starts.

Below is an example of what can be achieved with bookmaker odds on a match basis:

Refresh interval: Once a day

Retrieve a list of supported bookmakers.

There are two important parameters that are used to navigate through the pagination. The limit parameter defines what the number of returned bookmakers will be. If the number of actual bookmakers is above the limit value you can make subsequent requests by increasing the offset value.

The bookmakers name or id can be used to filter data from the odds endpoint.

Retrieve bookmaker information by specifying the bookmaker id path parameter.

Note: Used to check whether a bookmaker still exists or had its information updated.

Refresh interval: Immediately once a game is considered finished

Retrieve a list of the last five finished games for a specific team. If a game was not finished (e.g. was cancelled or postponed) it will not be returned.

Specify teamId query parameter to retrieve the data. Endpoint is used to create a form section between two teams that are playing a match. Below is an example of what can be achieved:

Retrieve a list of the last ten head 2 head games between two teams. Compare the two teams to find out who is stronger based on their past match results.

Specify teamIdOne and teamIdTwo query parameters to retrieve the data. The order of team ids does not matter.

Below is an example of what you can achieve with the data:

Lineups should be queried up to a few hours before the game starts.

Retrieve home and away team lineups for a specific match.

Below is an example of what you can aim to achieve with the lineup endpoint:

Refresh interval: Every minute

Retrieve detailed per-player MLB box score statistics by specifying the matchId as the path parameter.

The response is an array with two elements:
[homeTeam, awayTeam]

Each team object contains general team information and a list of player box scores, including both batting and pitching statistics.

Team Structure

Each team (home or away) has the following shape:

Player Box Score

Each item in boxScores represents a single player’s performance in the match.

Player Metadata

Player Statistics

Player performance data is provided as a list of statistic records.
Each record includes a statistic name, its category, and the recorded value.

Batting Statistics Explained

• Total At-Bats (AB)
  Number of official at-bats for the player.

• Total Runs Scored (R)
  Number of times the player scored a run.

• Total Hits (H)
  Total number of hits recorded by the player.

• Total Runs Batted In (RBI)
  Number of runs driven in by the player’s offensive actions.

• Total Home Runs (HR)
  Number of home runs hit.

• Total Walks (BB)
  Number of bases on balls earned.

• Total Strikeouts (SO)
  Number of times the player struck out while batting.

• Total Pitches Thrown (Batting)
  Total pitches seen by the player while at bat.

• Batting Average (AVG)
  Hits divided by at-bats.

• On-Base Percentage (OBP)
  Frequency at which the player reaches base safely.

• Slugging Percentage (SLG)
  Measure of batting power based on total bases per at-bat.

Pitching Statistics Explained

• Innings Pitched (IP)
  Total number of innings pitched.

• Hits Allowed (H)
  Number of hits allowed by the pitcher.

• Runs Allowed (R)
  Total runs given up.

• Total Earned Runs (ER)
  Runs that scored without defensive errors.

• Total Walks Allowed (BB)
  Number of batters walked.

• Total Strikeouts (SO)
  Number of batters struck out.

• Home Runs Allowed (HR)
  Number of home runs conceded.

• Earned Run Average (ERA)
  Average number of earned runs allowed per nine innings.

• Total Pitches Thrown (Pitching)
  Total number of pitches thrown by the pitcher.

Notes

• A player may appear with batting stats, pitching stats, or both.
• Some players may have zero values if they did not record a statistic in that category.
• Statistic availability may vary depending on player participation in the match.

Refresh interval: 15 minutes

Route returns only general player information. For additional player details check the players/{playerId} and players/{playerId}/statistics routes.

Retrieve a list of players based on the requested query parameters.

Returned results will be paginated. The limit parameter defines what the number of returned players will be. If the number of actual players is above the limit value you can make subsequent requests by increasing the offset value.

Refresh interval: Once a day

Retrieve detailed player summary for specified playerId.

Detailed player summary consists of the following information:

Refresh interval: Once a day

Retrieve detailed player statistics for specified playerId.

Detailed player statistics are aggregated on a perSeason level. Each season has the following available coverage:

Recorded stats are dependant on the player position. In total, the following stats are available:

Note: As mentioned earlier, statistics are associated with specific player positions. This means the results you receive will vary depending on the player's position.

Refresh interval: Every minute

Retrieve aggregated MLB team statistics for a single match by specifying the matchId as the path parameter.

The response is an array with two elements:
[teamA, teamB]

Each element represents a team and contains general team information along with aggregated statistics across batting, pitching, and fielding.

Team Structure

Each team object has the following shape:

Team Statistics

Each item in statistics represents a single aggregated metric recorded during the match.

Statistic Record

Batting Statistics

Batting statistics summarize the team’s offensive performance.

• Total At Bats
  Number of official team at-bats.

• Total Hits
  Total number of hits recorded by the team.

• Total Runs
  Total runs scored by the team.

• Total RBIs
  Total runs driven in by the team’s offensive actions.

• Total Home Runs
  Total home runs hit by the team.

• Total Walks
  Total bases on balls earned.

• Total Strikeouts
  Total strikeouts by batters.

• Batting Average (AVG)
  Team hits divided by total at-bats.

• On-Base Percentage (OBP)
  Frequency at which the team reaches base safely.

• Slugging Percentage (SLG)
  Measure of team batting power based on total bases per at-bat.

• On-Base Plus Slugging (OPS)
  Combined on-base and slugging percentage.

Pitching Statistics

Pitching statistics summarize the team’s performance while pitching.

• Innings Pitched (IP)
  Total innings pitched by the team.

• Hits Allowed (H)
  Number of hits allowed by team pitchers.

• Runs Allowed (R)
  Total runs conceded.

• Total Earned Runs (ER)
  Runs that scored without defensive errors.

• Total Walks Allowed (BB)
  Number of batters walked.

• Total Strikeouts (SO)
  Number of batters struck out.

• Home Runs Allowed (HR)
  Total home runs conceded.

• Earned Run Average (ERA)
  Average number of earned runs allowed per nine innings.

• Total Pitches Thrown
  Total number of pitches thrown by team pitchers.

Fielding Statistics Explained

Fielding statistics summarize the team’s defensive performance.

• Total Putouts
  Number of recorded outs by fielders.

• Total Assists
  Number of assists recorded.

• Total Errors
  Number of defensive errors committed.

• Total Chances
  Total defensive chances.

• Fielding Percentage
  Percentage of successful defensive plays.

Notes

• All statistics are aggregated at the team level.
• Not all statistic categories or metrics are guaranteed to be present for every match.
• Some values may be 0 depending on match flow and team participation.