nba-api-ts

TypeScript NBA API client. Zero dependencies. Wraps 138 stats endpoints and 4 live data endpoints from NBA.com.

Features

• 138 stats endpoints — player, team, game, draft, and league data from stats.nba.com
• 4 live endpoints — real-time scoreboard, box scores, play-by-play, and odds from cdn.nba.com
• Fully typed — every endpoint has typed params, responses, and row interfaces
• Built-in retry, rate limiting, and timeout — exponential backoff, token-bucket rate limiter, configurable timeouts
• Custom fetch injection — plug in TLS impersonation libraries to bypass Akamai bot protection
• Zero dependencies — nothing to audit, nothing to break

Requirements

• Node.js >= 18, Bun, or any runtime with fetch support
• Stats endpoints require a residential IP + TLS impersonation (see Akamai / TLS Fingerprinting)
• Live endpoints work from anywhere

Install

bun add nba-api-ts
# or
npm install nba-api-ts
Copy

Quick Start

import { NBAClient } from 'nba-api-ts';

const nba = new NBAClient();

// Stats — player career totals
const career = await nba.stats.playerCareerStats({ playerID: 203999 });
console.log(career.careerTotalsRegularSeason[0].pts);

// Stats — league-wide player dashboard
const dashboard = await nba.stats.leagueDashPlayerStats({
  season: '2024-25',
  perMode: 'PerGame',
});
console.log(dashboard.leagueDashPlayerStats[0].playerName);

// Live — today's scoreboard (no Akamai, works anywhere)
const scoreboard = await nba.live.scoreboard();
console.log(scoreboard.scoreboard.games.length, 'games today');
Copy

API Reference

NBAClient

const nba = new NBAClient({
  stats: { timeout: 30000, maxRetries: 3, rateLimit: 600, fetch: customFetch },
  live: { timeout: 10000, rateLimit: 0 },
});
Copy

• nba.stats — StatsClient with 138 endpoint methods
• nba.live — LiveClient with 4 methods (scoreboard, boxscore, playByPlay, odds)

Stats Endpoints

138 endpoints are available (full list). Some commonly used ones:

Response Format

Stats API responses use the NBA's headers[] + rowSet[][] format, automatically parsed into typed objects with camelCase keys:

// Raw NBA response:
// { "headers": ["PLAYER_ID", "PTS"], "rowSet": [[203999, 25.0]] }

// Parsed:
// { playerId: 203999, pts: 25.0 }
Copy

Parameters

Common parameter types are available as string unions:

import type { PerModeDetailed, SeasonTypePlayoffs, LeagueID } from 'nba-api-ts';
import { currentSeason, formatSeason, defaults } from 'nba-api-ts';

const season = currentSeason(); // "2025-26"
const prev = formatSeason(2023); // "2023-24"
Copy

Error Handling

import { NBAApiError, NBATimeoutError, NBANetworkError } from 'nba-api-ts';

try {
  await nba.stats.playerCareerStats({ playerID: -1 });
} catch (e) {
  if (e instanceof NBAApiError) {
    console.log(e.statusCode, e.url);
  }
}
Copy

Documentation

• Full endpoint list — all 138 stats + 4 live endpoints with NBA API paths
• API docs — auto-generated TypeDoc reference

Development

bun install
bun test            # unit tests (offline, fast)
bun run build

# Integration tests — hits real NBA API, requires residential IP
NBA_INTEGRATION_TESTS=1 bun test tests/integration

# Integration tests with TLS fingerprint impersonation
NBA_INTEGRATION_TESTS=1 NBA_USE_TLS=1 bun test tests/integration
Copy

Contributing

PRs welcome. Run bun run lint and bun test before submitting.

import { NBAClient } from 'nba-api-ts';
import { ModuleClient, SessionClient } from 'tlsclientwrapper';

const moduleClient = new ModuleClient();
await moduleClient.open();

const session = new SessionClient(moduleClient, {
  tlsClientIdentifier: 'chrome_131',
  timeoutSeconds: 30,
  defaultHeaders: {
    'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
    'Accept': 'application/json, text/plain, */*',
    'Referer': 'https://www.nba.com/',
    'Origin': 'https://www.nba.com',
  },
});

const nba = new NBAClient({
  stats: {
    fetch: async (url) => {
      const res = await session.get(url);
      if (res.status === 0) throw new Error(res.body);
      const headers: Record<string, string> = {};
      for (const [k, v] of Object.entries(res.headers))
        headers[k] = Array.isArray(v) ? v.join(', ') : String(v);
      return new Response(res.body, { status: res.status, headers });
    },
  },
});

const career = await nba.stats.playerCareerStats({ playerID: 203999 });
Copy

License

MIT