MLB & NCAA API

Pagination and limits

These endpoints take limit and offset and return a paginated envelope with data, pagination and plan. The rest return their result directly.

Paginated Not paginated

matches, highlights, standings, players, odds, bookmakers

teams, everything addressed by an id, plus team statistics, head to head, last five games, lineups, box scores and match statistics.

The envelope

A paginated response wraps its results in data and adds two objects.

dataobject[]requiredThe results themselves. The shape depends on the endpoint.
paginationPaginationResponserequiredHow many results exist and where this page sits.3 fields
totalCountnumberrequiredResults matching your query, not the number returned on this page.
offsetnumberrequiredThe offset this page was fetched at.
limitnumberrequiredThe page size used.
planPlanResponserequiredYour current API subscription tier, and a message explaining it.2 fields
tierstringrequiredYour current API subscription tier.
messagestringrequiredExplanation message regarding your current tier.

Example response

200 application/json 
{
  "data": [
    "..."
  ],
  "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"
  }
}

Paging through results

limit sets the page size and offset skips that many results. Page by holding limit steady and advancing offset until you have covered totalCount. 

const key = process.env.HIGHLIGHTLY_API_KEY
const limit = 40
const all = []

let offset = 0
let total = Infinity

while (offset < total) {
  const url = `https://baseball.highlightly.net/highlights?leagueName=MLB&limit=${limit}&offset=${offset}`
  const response = await fetch(url, {
    headers: { 'x-rapidapi-key': key }
  })

  if (!response.ok) {
    throw new Error(`Highlightly responded ${response.status}`)
  }

  const { data, pagination } = await response.json()

  all.push(...data)

  total = pagination.totalCount
  offset += limit
}

totalCount is the number of results matching your query, not the number on the current page, so it is the value to page against.

Your plan

Every paginated response carries a plan object. On a restricted tier some results might be hidden, and this arrives as a normal response rather than an error, so a short page is not necessarily the end of the data.

plan.tier is your current subscription tier, and plan.message is an explanation message regarding that tier. Both are always present. An example message reads as follows.

Some results might be hidden with FREE tier. Check your API coverage for more information.

The message carries a link to your coverage details, so you can surface it to your users directly.

Three endpoints are affected on the Basic and Free plans. Highlights may be restricted, and odds and geo restrictions are not available at all. The same restrictions apply with an All Sports API subscription.

Plans and their limits are listed on the MLB API page and the All Sports API page.

Rate limits

Two response headers track your quota.

Header Meaning
x-ratelimit-requests-limit Requests your plan allows. Static.
x-ratelimit-requests-remaining Requests left. At zero, requests fail until the daily quota resets.

Paging a large result set spends quota quickly, since each page is one request. Each endpoint caps limit at its own maximum, shown in its parameter table, so page at that maximum and cache results whose refresh interval is measured in hours rather than minutes.

On an All Sports API subscription, one quota covers every sport. Baseball requests draw on the same allowance as requests to any other sport, so paging a large baseball result set also reduces what is left for the rest.