Pagination and limits

Six Basketball API endpoints return a paginated envelope. The rest return their result directly.

The envelope

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

Example response

{
  "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://basketball.highlightly.net/highlights?leagueId=1635&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.

Default page sizes differ per endpoint. Teams defaults to 500, matches and leagues to 100, highlights to 40, bookmakers to 20 and odds to 5, so read the limit you get back rather than assuming one number everywhere. On every paginated endpoint except bookmakers the default is also the maximum, and bookmakers accepts up to 100.

Your plan

On the Basic and Free plans some results might be hidden, so a short page is not necessarily the end of the data.

Every paginated response carries a plan object. plan.tier is your current API subscription tier, and plan.message is an explanation message regarding that tier. For example, the message can read as follows.

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

In that example the message ends with a link to the API coverage details.

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 Basketball API page and the All Sports API page.

Rate limits

Two response headers track your quota.

Paging a large result set spends quota quickly, since each page is one request. A query returning 4,000 results at the default highlights page size of 40 costs 100 requests, and 40 is also the highest limit highlights accepts. Narrow the query with filters to reduce that, and cache results whose refresh interval is measured in hours rather than minutes.

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