How to build a fantasy basketball app

Fantasy basketball is decided by rate and role, not by totals. The players who win leagues are the ones whose efficiency and usage are about to outrun their name recognition — and that is precisely the number a scraped build never has.

• Points per game rewards volume, not quality. A high-usage player on a bad team outscores a more efficient one and drafts too early every year.
• True shooting and PER need league-wide context — team pace, league totals, minutes — so you cannot compute them from one player page at a time.
• Per-player scraping does not scale to a draft board. You need the league ranked in one call, already qualified for minimum games, or you are making 400 requests to sort a table.
• Player identity is the hidden tax — reconciling names across a stats source, an injury feed and a schedule feed is most of the work in a scraped build.

Every call below was run against production on the date in the footer, and the responses are trimmed copies of what came back. You need a free API key from the dashboard and nothing else — no SDK, no build step.

1. 01

   Get a key and confirm it works

   Create a free key in the dashboard, then confirm the gateway sees it. A 200 here means every later step is an authentication-free problem.

   Verify your keybash

   curl -s "https://api.bigballsdata.com/v1/coverage?sport=basketball" \
     -H "x-api-key: $BBS_API_KEY"

   Real response, trimmed

   jsonjson

   { "data": { "generated_at": "2026-08-15T18:40:42.039Z", "sports": [ { "name": "Basketball", "slug": "basketball", "leagues": [ { "key": "nba", ... } ] } ] } }

2. 02

   Pull the league leaderboard — this is the spine

   GET /v1/nba/leaders ranks the league in one call and applies a games qualifier for you, so small-sample flukes never reach your board. Pass stat=pts, reb, ast, fg_pct, ts_pct or per.

   GET /v1/nba/leadersbash

   curl -s "https://api.bigballsdata.com/v1/nba/leaders?stat=pts&limit=50" \
     -H "x-api-key: $BBS_API_KEY"

   Real response, trimmed

   jsonjson

   {
     "data": {
       "stat": "pts",
       "period": "season",
       "season": 2025,
       "qualified_min_games": 15,
       "leaders": [
         {
           "rank": 1,
           "player": {
             "id": "58a31261-…",
             "name": "Luka Doncic",
             "headshot_url": "https://cdn.nba.com/headshots/nba/latest/260x190/1629029.png"
           },
           "team": { "id": "490c5fad-…", "abbreviation": "LAL" },
           "value": 33.5,
           "games_played": 64
         }
       ]
     }
   }

3. 03

   Switch stat=per — this is the actual edge

   The same endpoint serves full Hollinger PER, computed with per-player team context and league totals rather than approximated. Ranking by PER instead of points is what separates a draft board from a scoring leaderboard: it prices efficiency and role together, and it is the number a scraped build cannot reproduce from one player page at a time.

   Rank by efficiency, not volumetypescript

   type Leader = {
     rank: number;
     player: { id: string; name: string; headshot_url: string | null };
     team: { id: string; abbreviation: string };
     value: number;
     games_played: number;
   };
   
   const base = 'https://api.bigballsdata.com/v1/nba/leaders';
   const headers = { 'x-api-key': process.env.BBS_API_KEY! };
   
   // Two calls, two boards: volume and efficiency.
   const [pts, per] = await Promise.all(
     ['pts', 'per'].map(async (stat) => {
       const res = await fetch(`${base}?stat=${stat}&limit=100`, { headers });
       const { data } = (await res.json()) as { data: { leaders: Leader[] } };
       return data.leaders;
     }),
   );
   
   // Players who rank far better by PER than by points are the value picks:
   // efficient producers whose raw totals under-sell them.
   const ptsRank = new Map(pts.map((l) => [l.player.id, l.rank]));
   const value = per
     .filter((l) => (ptsRank.get(l.player.id) ?? 999) - l.rank > 15)
     .map((l) => ({ name: l.player.name, per: l.value, gp: l.games_played }));

4. 04

   Filter out the unavailable

   GET /v1/injuries returns the current basketball injury list with status, expected return date and a written note. Join it to the leaderboard on player id — no name matching. Note the page size caps at 200, so read the count field and page if you want all of them.

   GET /v1/injuriesbash

   curl -s "https://api.bigballsdata.com/v1/injuries?sport=basketball&limit=200" \
     -H "x-api-key: $BBS_API_KEY"

   Real response, trimmed

   jsonjson

   {
     "data": {
       "sport": "basketball",
       "count": 207,
       "injuries": [
         {
           "player": {
             "id": "ff21c2f1-…",
             "name": "Aaron Gordon",
             "team": { "id": "bf31614a-…", "name": "Denver Nuggets", "abbreviation": "DEN" }
           },
           "status": "Probable",
           "injury_type": null,
           "return_date": "2026-10-01",
           "comment": "Gordon attempted to warm up ahead of Thursday's clash…",
           "updated_at": "2026-07-26T03:46:13.158Z"
         }
       ]
     }
   }

5. 05

   Add team context with standings and Elo

   Standings give you the season table and the team ids; Elo gives you a strength rating to weight schedule difficulty. Both are free. Read the note field on the Elo response — out of season it tells you plainly that the rating has not moved since the last game played.

   GET /v1/standings and /v1/teams/:id/elobash

   curl -s "https://api.bigballsdata.com/v1/standings?league=NBA" \
     -H "x-api-key: $BBS_API_KEY"
   
   curl -s "https://api.bigballsdata.com/v1/teams/bf31614a-…/elo" \
     -H "x-api-key: $BBS_API_KEY"

   Real response, trimmed

   jsonjson

   {
     "data": {
       "team_id": "bf31614a-…",
       "name": "Denver Nuggets",
       "abbreviation": "DEN",
       "elo_rating": 1618.2,
       "elo_rank": 7,
       "games_counted": 87,
       "last_match_date": "2026-04-30",
       "note": "off-season — rating unchanged since the last match played on 2026-04-30 (107 days ago); last_computed reflects when the ratings job last ran, not new results"
     }
   }

Everything above runs on a free key. The board works, ranks and drafts. What the free tier does not give you is the modelled layer — the numbers we compute rather than collect — and for a draft tool that layer is the product.

// Free key — /v1/teams/:id/elo
{
  "elo_rating": 1618.2,
  "elo_rank": null,
  "upgrade": { "locked": ["elo_rank", "elo/history", "win_probability"] }
}

// Solo — /v1/players/:id/tier
{
  "tier": 3,
  "tier_label": "All-Star",
  "tier_score": 58.4,
  "percentile": 91.1,
  "position_percentile": 90.9,
  "primary_metric": "per",
  "primary_metric_value": 20.3,
  "review_method": "computed"
}

• Player tier and percentile — one position-adjusted number per player, built on PER. This is the column that makes a draft board feel authoritative, and it carries review_method so you know whether it was computed or reviewed.
• Elo rank and rating history — the free tier returns the rating; rank, the trend and win probability are Solo.
• Season projections and rolling form — /v1/players/:id/season-projection and /v1/players/:id/rolling-stats, for in-season waiver decisions rather than draft-day ones.
• Market data stays separate. Odds, line divergence and closing-line value sit on Edge, not Solo — they come from licensed market feeds rather than our models.

• How to build a fantasy hockey app
• How to build a soccer xG app
• How to build a cricket app

Can I build a fantasy basketball app on the free tier?

Yes. The league leaderboard, injuries, standings, matches and team Elo ratings are all available on a free key, which is 1,000 requests a day (2,000 with GitHub connected) and needs no credit card. The Solo plan adds the modelled layer — player tiers, Elo rank and history, projections.

What NBA data does the API actually hold?

Scores, standings, injuries, team Elo and an aggregated league leaderboard including full Hollinger PER. Per-player box-score coverage is partial — see the roadmap above. Call GET /v1/coverage?sport=basketball for the current machine-readable answer rather than trusting this paragraph.

Why rank by PER instead of points per game?

Because points per game prices volume, and volume is largely a function of usage and team quality. PER folds efficiency, rebounding, assists and turnovers into one pace-adjusted number, so it estimates the thing a draft is actually trying to buy. We compute it with real per-player team context and league totals, not an approximation.

Does sport=basketball mean the NBA?

Not on its own. The basketball sport key also spans NCAAB and the WNBA, so a bare sport=basketball query on /v1/teams or /v1/matches will return college and WNBA rows too. Add &league=nba when you want the NBA specifically. The /v1/nba/* routes are already NBA-scoped.

Do I need the MCP server, or can I just call the REST API?

Either. The MCP server lets an AI agent read the data while it writes your code, which is faster if you are already working in an agentic editor. The REST API is the complete surface and every MCP tool is backed by it. The MCP server currently exposes five read tools; the leaderboard and tier endpoints are REST-only for now.

How do I handle player identity across endpoints?

You do not have to. Every endpoint returns the same player id, so the leaderboard row, the injury list and the tier call join directly. Name reconciliation is the tax you pay when scraping several sources; it is the main thing this API removes.