College Basketball Data API Service

A Node.js wrapper for the College Basketball Data API that provides easy access to comprehensive college basketball statistics, games, rankings, and betting lines. Fetch historical and current season data through a simple command-line interface.

This service follows the data-collection architecture pattern with organized data storage, rate limiting, comprehensive validation, and CLI orchestration.

Quick Start

CLI Usage

# Install globally
npm install -g cbb-api

export CBB_DATA_API_KEY="my-api-key"

# Fetch games for a season
cbb --games --year 2025

# Get team rankings
cbb --rankings --season 2025

Programmatic Usage

import { CBBDataAPI } from 'cbb-api';

const api = new CBBDataAPI();
api.connect();

// Get games for a date range
const games = await api.getGames({
  startDateRange: '2025-03-15',
  endDateRange: '2025-03-16',
  season: 2025
});

// Get team rankings
const rankings = await api.getRankings({ season: 2025 });

api.close();

Table of Contents

• Overview
• Data Categories
• Authentication Setup
• Installation
• Quick Start
• CLI Usage
• API Methods
• Examples
• Data Organization
• Error Handling
• Troubleshooting

Overview

The College Basketball Data API provides access to comprehensive college basketball statistics. This Node.js service implements:

• 22 API Methods - Games, stats, rankings, lines, plays, lineups, draft data, and more
• Historical Data - Games from 2003+, betting lines from 2013+
• Parameter Validation - Pre-flight validation catches invalid parameters before API calls
• API Key Authentication - Multiple configuration methods with secure handling
• Rate Limiting - Built-in random delays (2-7 seconds) between requests to respect API limits
• Batch Processing - Fetch data for entire seasons or date ranges
• Organized Storage - Structured directories with timestamped files
• CLI Orchestration - Command-line tool for easy batch data collection
• Comprehensive Testing - 104 tests with 77.61% coverage

Data Categories

Conferences

Team conference information and historical membership data.

Endpoints:

• getConferences() - List of all conferences
• getConferenceHistory() - Historical conference membership changes

Draft

NBA draft information for college players.

Endpoints:

• getDraftPicks() - Draft pick information
• getDraftPositions() - Draft position statistics
• getDraftTeams() - Professional teams in the draft

Games (2003+)

Game results, box scores, and broadcast information.

Endpoints:

• getGames() - Game information and scores
• getGamesMedia() - Broadcast/media information
• getGamesPlayers() - Player box scores
• getGamesTeams() - Team box scores

Parameters:

• startDateRange, endDateRange - Date range (YYYY-MM-DD)
• season - Season year
• team, conference - Filter by team or conference
• seasonType, status, tournament - Additional filters

Lines (2013+)

Betting lines and spreads from multiple providers.

Endpoints:

• getLines() - Betting lines for games
• getLinesProviders() - Available line providers

Parameters:

• startDateRange, endDateRange - Date range (YYYY-MM-DD)
• season, team, conference - Filters

Lineups

Lineup combination statistics.

Endpoints:

• getLineupsByTeam() - Season lineup stats for a team (requires team, season)

Plays

Play-by-play data.

Endpoints:

• getPlayTypes() - List of play types
• getPlaysByDate() - All plays for a date (requires date)
• getPlaysByTeam() - Team's plays (requires team)

Rankings

AP Poll, Coaches Poll, and other rankings.

Endpoints:

• getRankings() - Poll rankings (requires season)

Parameters:

• season - Season year (required)
• week, seasonType - Additional filters

Ratings

Team rating systems.

Endpoints:

• getSRSRatings() - Simple Rating System (requires season)

Stats

Player and team statistics.

Endpoints:

• getPlayerSeasonStats() - Player season stats (requires season)
• getPlayerShootingStats() - Player shooting stats (requires season + team OR conference)
• getTeamSeasonStats() - Team season stats (requires season OR team)
• getTeamShootingStats() - Team shooting stats (requires season + team OR conference)

Parameters:

• season - Season year
• team, conference - Filter by team or conference
• startDateRange, endDateRange - Date range filters

Teams

Team information and rosters.

Endpoints:

• getTeams() - Historical team information
• getTeamRoster() - Team roster (requires team)

Venues

Arena and venue information.

Endpoints:

• getVenues() - All venues

Authentication Setup

1. Get Your API Key

1. Visit https://collegebasketballdata.com/
2. Create an account or sign in
3. Generate your API key from the dashboard
4. Copy your API key

2. Configure Your API Key

You can provide your API key in multiple ways (listed in priority order):

Option A: Environment Variable

Set the CBB_DATA_API_KEY environment variable in your shell:

# Add to your ~/.bashrc, ~/.zshrc, or equivalent
export CBB_DATA_API_KEY=your_actual_api_key_here

# Or use it for a single command
CBB_DATA_API_KEY=your_key cbb --games --year 2025

This is ideal for CI/CD pipelines and server environments.

Option B: Local .env File (Project-Specific)

Create a .env file in your project directory:

# In your project directory
echo "CBB_DATA_API_KEY=your_actual_api_key_here" > .env

This is best for project-specific configurations.

Option C: Global Config (For Global npm Installs)

Create a global config file at ~/.cbb-data/.env:

# Create config directory
mkdir -p ~/.cbb-data

# Add your API key
echo "CBB_DATA_API_KEY=your_actual_api_key_here" > ~/.cbb-data/.env

This is perfect for global npm installations (npm install -g cbb-api).

Security Note: Never commit .env files or expose your API key publicly.

Installation

Option 1: Install from npm

# Install globally for CLI usage
npm install -g cbb-api

# Or install locally in your project
npm install cbb-api

Option 2: Install from source

# Clone the repository
git clone https://github.com/aself101/cbb-api.git
cd cbb-api

# Install dependencies
npm install

Dependencies:

• commander - CLI argument parsing
• dotenv - Environment variable management
• winston - Logging framework

CLI Usage

Basic Command Structure

# Global install
cbb [endpoint] [options]

# Local install (use npx)
npx cbb [endpoint] [options]

# From source (development)
npm run cbb -- [endpoint] [options]

Category Flags

Fetch multiple related endpoints at once:

--all                    # Fetch all endpoints
--all-conferences        # Fetch all conference endpoints
--all-draft              # Fetch all draft endpoints
--all-games              # Fetch all 4 game endpoints
--all-lines              # Fetch both lines endpoints
--all-ratings            # Fetch all ratings endpoints
--all-stats              # Fetch all 4 stats endpoints

Conference Endpoints

--conferences            # List of all conferences
--conference-history     # Conference membership history

Draft Endpoints

--draft-picks            # NBA draft picks
--draft-positions        # Draft position stats
--draft-teams            # Professional draft teams

Game Endpoints (2003+)

--games                  # Game information
--games-media            # Broadcast information
--games-players          # Player box scores
--games-teams            # Team box scores

Lines Endpoints (2013+)

--lines                  # Betting lines
--lines-providers        # Line providers

Lineup Endpoints

--lineups-team           # Lineup stats for team season (requires --team, --season)

Play Endpoints

--play-types             # List of play types
--plays-date             # Plays for a date (requires --date)
--plays-team             # Plays for a team (requires --team)

Rankings & Ratings Endpoints

--rankings               # Poll rankings (requires --season)
--srs-ratings            # SRS ratings (requires --season)

Stats Endpoints

--player-season-stats    # Player season stats
--player-shooting-stats  # Player shooting stats
--team-season-stats      # Team season stats
--team-shooting-stats    # Team shooting stats

Team Endpoints

--teams                  # Team information
--team-roster            # Team roster (requires --team)

Venue Endpoint

--venues                 # Venue information

Time Options

--year <year>            # Single season year
--start <year>           # Start year for range
--end <year>             # End year for range
--season <year>          # Season for stats/rankings endpoints
--start-date <date>      # Explicit start date (YYYY-MM-DD)
--end-date <date>        # Explicit end date (YYYY-MM-DD)
--date <date>            # Single date for plays-date (YYYY-MM-DD)
--week <week>            # Week number for rankings

Filter Options

--team <name>            # Filter by team name
--conference <code>      # Filter by conference abbreviation
--play-type <type>       # Play type filter
--shooting-only          # Filter to shooting plays only

Other Options

--output-dir <path>      # Output directory (default: datasets)
--log-level <level>      # DEBUG, INFO, WARNING, ERROR, NONE
--dry-run                # Preview without fetching
--examples               # Show usage examples

API Methods

Core Pattern

All API methods follow the same pattern:

import { CBBDataAPI } from 'cbb-api';

const api = new CBBDataAPI({ logLevel: 'INFO' });
api.connect();

// Make API calls
const data = await api.methodName({ options });

// Clean up
api.close();

Conference Methods

getConferences()

Get list of all conferences.

const conferences = await api.getConferences();

getConferenceHistory(options)

Get historical conference membership data.

const history = await api.getConferenceHistory({
  conference: 'ACC'  // Optional filter
});

Draft Methods

getDraftPicks(options)

Get NBA draft pick information.

const picks = await api.getDraftPicks({
  season: 2024,
  team: 'Duke',      // Optional
  player: 'Smith'    // Optional
});

getDraftPositions(options)

Get draft position statistics.

const positions = await api.getDraftPositions({
  season: 2024
});

getDraftTeams()

Get professional teams that drafted players.

const teams = await api.getDraftTeams();

Game Methods (2003+)

getGames(options)

Get game information and scores.

const games = await api.getGames({
  startDateRange: '2025-03-15',
  endDateRange: '2025-03-16',
  season: 2025,
  team: 'Duke',           // Optional
  conference: 'ACC',      // Optional
  seasonType: 'regular',  // Optional
  status: 'completed',    // Optional
  tournament: 'NCAA'      // Optional
});

getGamesMedia(options)

Get broadcast information for games.

const media = await api.getGamesMedia({
  startDateRange: '2025-03-15',
  endDateRange: '2025-03-16',
  season: 2025
});

getGamesPlayers(options)

Get player box score statistics.

const playerStats = await api.getGamesPlayers({
  startDateRange: '2025-03-15',
  endDateRange: '2025-03-16',
  season: 2025
});

getGamesTeams(options)

Get team box score statistics.

const teamStats = await api.getGamesTeams({
  startDateRange: '2025-03-15',
  endDateRange: '2025-03-16',
  season: 2025
});

Lines Methods (2013+)

getLines(options)

Get betting lines for games.

const lines = await api.getLines({
  startDateRange: '2025-03-15',
  endDateRange: '2025-03-16',
  season: 2025,
  team: 'Duke',       // Optional
  conference: 'ACC'   // Optional
});

getLinesProviders()

Get list of available betting line providers.

const providers = await api.getLinesProviders();

Lineup Methods

getLineupsByTeam(options)

Get lineup combinations and statistics for a team's season.

const lineups = await api.getLineupsByTeam({
  team: 'Duke',        // Required
  season: 2025,        // Required
  seasonType: 'regular'  // Optional
});

Play Methods

getPlayTypes()

Get list of available play types.

const playTypes = await api.getPlayTypes();

getPlaysByDate(options)

Get all plays for games on a specific date.

const plays = await api.getPlaysByDate({
  date: '2025-03-15',       // Required (YYYY-MM-DD)
  seasonType: 'regular',    // Optional
  playType: 'shot'          // Optional
});

getPlaysByTeam(options)

Get all plays for a specific team.

const plays = await api.getPlaysByTeam({
  team: 'Duke',             // Required
  season: 2025,             // Optional
  seasonType: 'regular',    // Optional
  playType: 'shot',         // Optional
  shootingPlaysOnly: true   // Optional
});

Rankings Methods

getRankings(options)

Get poll rankings (AP, Coaches, etc.).

const rankings = await api.getRankings({
  season: 2025,             // Required
  week: 10,                 // Optional
  seasonType: 'regular'     // Optional
});

Ratings Methods

getSRSRatings(options)

Get Simple Rating System ratings.

const ratings = await api.getSRSRatings({
  season: 2025              // Required
});

Stats Methods

getPlayerSeasonStats(options)

Get player season statistics.

const stats = await api.getPlayerSeasonStats({
  season: 2025,             // Required
  team: 'Duke',             // Optional
  conference: 'ACC',        // Optional
  seasonType: 'regular',    // Optional
  startDateRange: '2025-01-01',  // Optional
  endDateRange: '2025-03-31'     // Optional
});

getPlayerShootingStats(options)

Get player season shooting statistics.

const stats = await api.getPlayerShootingStats({
  season: 2025,             // Required
  team: 'Duke',             // Required: team OR conference
  // conference: 'ACC',     // Alternative to team
  seasonType: 'regular'     // Optional
});

getTeamSeasonStats(options)

Get team season statistics.

const stats = await api.getTeamSeasonStats({
  season: 2025,             // Required: season OR team
  // team: 'Duke',          // Alternative to season
  conference: 'ACC',        // Optional
  seasonType: 'regular'     // Optional
});

getTeamShootingStats(options)

Get team season shooting statistics.

const stats = await api.getTeamShootingStats({
  season: 2025,             // Required
  team: 'Duke',             // Required: team OR conference
  // conference: 'ACC',     // Alternative to team
  seasonType: 'regular'     // Optional
});

Team Methods

getTeams(options)

Get historical team information.

const teams = await api.getTeams({
  conference: 'ACC',        // Optional
  season: 2025              // Optional
});

getTeamRoster(options)

Get team roster with player details.

const roster = await api.getTeamRoster({
  team: 'Duke',             // Required
  season: 2025              // Optional
});

Venue Methods

getVenues()

Get arena/venue information.

const venues = await api.getVenues();

Examples

Note: Examples use cbb command (global install). For local install, use npx cbb instead.

Example 1: Fetch Season Games

cbb --games --year 2025

Example 2: Fetch All Data for a Season

cbb --all --year 2025

Example 3: Fetch Rankings

cbb --rankings --season 2025

Example 4: Fetch Multiple Seasons of Lines

cbb --lines --start 2020 --end 2025

Example 5: Fetch Team-Specific Data

cbb --team-roster --team Duke --season 2025
cbb --games --team Duke --year 2025

Example 6: Fetch Play-by-Play Data

# All plays for a date
cbb --plays-date --date 2025-03-15

# Team plays for a season
cbb --plays-team --team Duke --season 2025

# Available play types
cbb --play-types

Example 7: Fetch Draft Data

cbb --draft-picks --season 2024
cbb --draft-teams
cbb --all-draft --season 2024

Example 8: Dry Run Preview

cbb --all --year 2025 --dry-run

Example 9: Using API Class in Code

import { CBBDataAPI } from 'cbb-api';

const api = new CBBDataAPI({ logLevel: 'INFO' });
api.connect();

try {
  // Get rankings
  const rankings = await api.getRankings({ season: 2025 });
  console.log(`Found ${rankings.length} ranking entries`);

  // Get team stats
  const stats = await api.getTeamSeasonStats({ season: 2025 });
  console.log(`Found stats for ${stats.length} teams`);

  // Get games for March Madness
  const games = await api.getGames({
    startDateRange: '2025-03-18',
    endDateRange: '2025-04-08',
    season: 2025,
    tournament: 'NCAA'
  });
  console.log(`Found ${games.length} tournament games`);

} finally {
  api.close();
}

Data Organization

Data is organized by endpoint type and year:

datasets/
├── conferences/
│   ├── conferences.json
│   └── history_ACC.json
├── draft/
│   ├── picks_2024.json
│   ├── positions_2024.json
│   └── teams.json
├── games/
│   └── 2025/
│       ├── games_2025-03-15.json
│       └── games_2025-03-16.json
├── games_media/
│   └── 2025/
│       └── media_2025-03-15.json
├── games_players/
│   └── 2025/
│       └── players_2025-03-15.json
├── games_teams/
│   └── 2025/
│       └── teams_2025-03-15.json
├── lines/
│   └── 2025/
│       └── lines_2025-03-15.json
├── lines_providers/
│   └── providers.json
├── lineups/
│   └── Duke_2025.json
├── plays/
│   ├── play_types.json
│   ├── date_2025-03-15.json
│   └── team_Duke_2025.json
├── rankings/
│   └── rankings_2025.json
├── ratings/
│   └── srs_2025.json
├── rosters/
│   └── Duke_2025.json
├── player_season_stats/
│   └── 2025/
│       └── Duke_player_stats_2025.json
├── player_shooting_stats/
│   └── 2025/
│       └── Duke_player_shooting_2025.json
├── team_season_stats/
│   └── 2025/
│       └── team_stats_2025.json
├── team_shooting_stats/
│   └── 2025/
│       └── Duke_team_shooting_2025.json
├── teams/
│   └── teams_2025.json
└── venues/
    └── venues.json

Error Handling

The service includes comprehensive error handling with clear messages:

Parameter Validation

Parameters are validated before API calls:

Error: Required parameter 'season' is missing
Error: At least one of [team, conference] must be provided
Error: startDateRange must be in ISO 8601 format (YYYY-MM-DD), got: 03-15-2025
Error: Season 2002 is before minimum year 2003 for getGames

HTTP Errors

Error: HTTP 401: Unauthorized
Error: HTTP 429: Too Many Requests
Error: HTTP 500: Internal Server Error

Connection Errors

Error: HTTP client not initialized. Call connect() first.
Error: API key not found. Set CBB_DATA_API_KEY environment variable or provide apiKey during initialization.

Troubleshooting

API Key Not Found

Error: API key not found. Set CBB_DATA_API_KEY environment variable or provide apiKey during initialization.

Solution: Create .env file with your API key:

CBB_DATA_API_KEY=your_api_key_here

Invalid Date Format

Error: startDateRange must be in ISO 8601 format (YYYY-MM-DD), got: 03/15/2025

Solution: Use YYYY-MM-DD format for all dates:

cbb --games --start-date 2025-03-15 --end-date 2025-03-20

Season Too Early

Error: Season 2000 is before minimum year 2003 for getGames

Solution: Use seasons within supported range:

• Games endpoints: 2003+
• Lines endpoints: 2013+

Rate Limiting (429)

Error: HTTP 429: Too Many Requests

Solution: The CLI includes built-in rate limiting (2-7 second random delays). If you still hit limits:

• Wait a few minutes before retrying
• Reduce the scope of your request
• Contact the API provider for rate limit increases

Module Not Found

Error: Cannot find module 'commander'

Solution: Install dependencies:

cd cbb-api
npm install

Minimum Year Requirements

| Endpoint Category | Minimum Year | |-------------------|--------------| | Games | 2003 | | Games Media | 2003 | | Games Players | 2003 | | Games Teams | 2003 | | Lines | 2013 |

Development Scripts

Note: These npm scripts are only available when working from the source repository.

npm run cbb              # Run CLI
npm run cbb:help         # Show help
npm run cbb:examples     # Show usage examples
npm test                 # Run all 104 tests
npm run test:watch       # Watch mode
npm run test:coverage    # Generate coverage report

Pass additional flags with --:

npm run cbb -- --games --year 2025

Additional Resources

• College Basketball Data API
• API Documentation

Disclaimer: This project is an independent community wrapper and is not affiliated with collegebasketballdata.com.

License

MIT