A Node.js wrapper for KenPom.com college basketball statistics with CLI support. Scrapes data from KenPom using authenticated HTTP requests with automatic Cloudflare bypass.
This service follows the data-collection architecture pattern with organized data storage, rate limiting, comprehensive logging, and CLI orchestration.
# Install globally
npm install -g kenpom-api
# Configure credentials
export KENPOM_EMAIL="your.email@example.com"
export KENPOM_PASSWORD="your_password"
# Fetch ratings for current season
kenpom --ratings
import { KenpomAPI } from 'kenpom-api';
const api = new KenpomAPI();
// Login (required before fetching data)
await api.login();
// Fetch Pomeroy ratings
const ratings = await api.getPomeroyRatings(2025);
console.log('Teams:', ratings.length);
// Close connection when done
await api.close();
KenPom.com provides the most comprehensive college basketball statistics available. This Node.js service implements:
| Endpoint | Min Year | Description |
|---|---|---|
| Pomeroy Ratings | 1999 | Team rankings with efficiency metrics |
| Trends | - | Statistical trends over time |
| Refs | 2016 | Referee rankings and game scores |
| HCA | - | Home court advantage statistics |
| Arenas | 2010 | Arena capacity and attendance data |
| Game Attributes | 2010 | Excitement, tension, comebacks, upsets |
| Program Ratings | - | All-time program rankings |
| Endpoint | Min Year | Description |
|---|---|---|
| Efficiency | 1999 | Adjusted offensive/defensive efficiency |
| Four Factors | 1999 | Shooting, turnovers, rebounding, FT rate |
| Team Stats | 1999 | 20+ team statistics (offense/defense) |
| Point Distribution | 1999 | Scoring distribution patterns |
| Height/Experience | 2007 | Average height and experience metrics |
| Player Stats | 2004 | 18 individual player metrics |
| KPOY | 2011 | Player of the Year rankings |
| Endpoint | Min Year | Description |
|---|---|---|
| Valid Teams | 1999 | List of team names for a season |
| Schedule | 1999 | Game-by-game results and records |
| Scouting Report | 1999 | 70+ detailed stats and rankings |
| Endpoint | Description |
|---|---|
| Conference Standings | Conference win/loss records |
| Conference Offense | Offensive stats by conference |
| Conference Defense | Defensive stats by conference |
| Conference Stats | Aggregate stats for all conferences |
| Endpoint | Min Year | Description |
|---|---|---|
| FanMatch | 2014 | Daily game predictions and results |
KenPom.com requires a paid subscription to access data:
You can provide your credentials in multiple ways (listed in priority order):
Pass credentials directly when initializing:
const api = new KenpomAPI({
email: 'your.email@example.com',
password: 'your_password'
});
This is useful for programmatic usage or testing.
Set environment variables in your shell:
# Add to your ~/.bashrc, ~/.zshrc, or equivalent
export KENPOM_EMAIL=your.email@example.com
export KENPOM_PASSWORD=your_password
This is ideal for CI/CD pipelines and server environments.
Create a .env file in your project directory:
# In your project directory
echo "KENPOM_EMAIL=your.email@example.com" >> .env
echo "KENPOM_PASSWORD=your_password" >> .env
This is best for project-specific configurations.
Security Note: Never commit .env files or expose your credentials publicly. The .env file should be added to .gitignore.
# Install globally for CLI usage
npm install -g kenpom-api
# Or install locally in your project
npm install kenpom-api
# Clone the repository
git clone https://github.com/aself101/kenpom-api.git
cd kenpom-api
# Install dependencies
npm install
Dependencies:
cheerio - HTML parsingcommander - CLI argument parsingdotenv - Environment variable managementwinston - Logging frameworkTier 1 (lightweight):
Tier 2 (headless browser - optional):
# Global install
kenpom [options]
# Local install (use npx)
npx kenpom [options]
# From source (development)
node cli.js [options]
Fetch groups of endpoints at once:
--all # Fetch all endpoints
--all-single # Fetch all single-fetch endpoints (no year iteration)
--all-yearly # Fetch all yearly endpoints
--all-teams # Fetch team schedules for all teams
# Single-fetch (no year iteration)
--arenas # Arena data (2010+)
--program-ratings # All-time program ratings
--trends # Statistical trends
--hca # Home court advantage
# Yearly endpoints
--ratings # Pomeroy ratings (1999+)
--efficiency # Efficiency stats (1999+)
--four-factors # Four factors (1999+)
--team-stats # Team statistics (1999+)
--point-dist # Point distribution (1999+)
--height # Height/experience (2007+)
--player-stats # Player statistics (2004+)
--kpoy # Player of the Year (2011+)
--refs # Referee rankings (2016+)
--game-attribs # Game attributes (2010+)
--valid-teams # List of valid team names (1999+)
# Team/Date based
--schedule # Team schedules (requires --team or fetches all)
--fanmatch # FanMatch for entire season (2014+)
--fanmatch-date <date> # FanMatch for single date (YYYY-MM-DD)
--year <year> # Single season year
--start <year> # Start year for range
--end <year> # End year for range
--team <name> # Team name filter
--conference <code> # Conference code filter
--metric <name> # Metric for player/game stats (default: eFG)
--all-metrics # Fetch all 18 player metrics
--defense # Fetch defensive stats (for team-stats)
--output-dir <path> # Output directory (default: datasets)
--log-level <level> # DEBUG, INFO, WARNING, ERROR
--client <tier> # tier1, tier2, auto (default: auto)
--dry-run # Preview what would be fetched
--examples # Show usage examples
Player Stats (18 metrics):
ORtg, Min, eFG, Poss, Shots, OR, DR, TO, ARate, Blk, FTRate, Stl, TS, FC40, FD40, 2P, 3P, FT
Game Attributes:
Excitement, Tension, Dominance, ComeBack, FanMatch, Upsets, Busts
A10, ACC, AE, Amer, ASun, B10, B12, BE, BSky, BSth, BW, CAA, CUSA, Horz, Ivy, MAAC, MAC, MEast, MVC, MWC, NEC, OVC, Pac, Pat, SB, SC, SEC, Slnd, Sum, SWAC, WAC, WCC
const api = new KenpomAPI({
email: 'user@example.com', // KenPom email (default: env KENPOM_EMAIL)
password: 'password', // KenPom password (default: env KENPOM_PASSWORD)
logLevel: 'INFO', // DEBUG, INFO, WARNING, ERROR, NONE
clientTier: 'auto', // tier1, tier2, or auto
});
// Login to KenPom (required before fetching data)
await api.login();
// Close connection when done
await api.close();
getPomeroyRatings(season)Get team ratings with efficiency metrics.
const ratings = await api.getPomeroyRatings(2025);
// Returns: Array of 364 teams with 22 columns
// Columns: Rk, Team, Conf, W-L, AdjEM, AdjO, AdjO.Rank, AdjD, AdjD.Rank,
// AdjT, AdjT.Rank, Luck, Luck.Rank, SOS-AdjEM, SOS-AdjEM.Rank,
// SOS-OppO, SOS-OppO.Rank, SOS-OppD, SOS-OppD.Rank,
// NCSOS-AdjEM, NCSOS-AdjEM.Rank, Seed
getTrends()Get statistical trends over time.
const trends = await api.getTrends();
getRefs(season)Get referee rankings (2016+).
const refs = await api.getRefs(2025);
// Returns: Rank, Name, Rating, Games, Last Game, Game Score
getHca()Get home court advantage statistics.
const hca = await api.getHca();
// Returns: Team, Conference, HCA, HCA.Rank, PF, PF.Rank, etc.
getArenas(season)Get arena statistics (2010+).
const arenas = await api.getArenas(2025);
// Returns: Rank, Team, Conference, Arena, Arena.Capacity, Alternate, Alternate.Capacity
getGameAttribs(season, metric)Get game attributes (2010+).
const exciting = await api.getGameAttribs(2025, 'Excitement');
// Returns: Rank, Date, Game, Location, Arena, Conf.Matchup, Value
getProgramRatings()Get all-time program ratings.
const programs = await api.getProgramRatings();
// Returns: Rank, Team, Conference, Rating, Best/Worst seasons, NCAA tournament history
getEfficiency(season)Get efficiency and tempo statistics (1999+).
const efficiency = await api.getEfficiency(2025);
getFourFactors(season)Get Four Factors statistics (1999+).
const fourFactors = await api.getFourFactors(2025);
// Returns: 24 columns including eFG%, TO%, OR%, FTRate for offense and defense
getTeamStats(season, defense)Get team statistics (1999+).
// Offensive stats
const offense = await api.getTeamStats(2025, false);
// Defensive stats
const defense = await api.getTeamStats(2025, true);
// Returns: 20 columns of detailed team statistics
getPointDist(season)Get points distribution (1999+).
const pointDist = await api.getPointDist(2025);
// Returns: 14 columns showing scoring distribution
getHeight(season)Get height and experience statistics (2007+).
const height = await api.getHeight(2025);
getPlayerStats(season, metric, conf, confOnly)Get player statistics (2004+).
// Single metric
const shooters = await api.getPlayerStats(2025, 'eFG');
// Conference filter
const accPlayers = await api.getPlayerStats(2025, 'eFG', 'ACC');
// Conference games only
const accConfGames = await api.getPlayerStats(2025, 'eFG', 'ACC', true);
getAllPlayerStats(season, conf, confOnly)Get all 18 player metrics for a season (2004+).
const allStats = await api.getAllPlayerStats(2025);
// Returns: Object with metric names as keys
// { ORtg: [...], Min: [...], eFG: [...], ... }
getKpoy(season)Get Player of the Year rankings (2011+).
const kpoy = await api.getKpoy(2025);
// Returns: { kpoy: [...], mvp: [...] }
getValidTeams(season)Get list of valid team names for a season (1999+).
const teams = await api.getValidTeams(2025);
// Returns: Array of team names (e.g., ['Duke', 'North Carolina', ...])
getSchedule(team, season)Get team schedule (1999+).
const schedule = await api.getSchedule('Duke', 2025);
// Returns: Array of games with Date, Opponent, Result, Location, etc.
getScoutingReport(team, season, conferenceOnly)Get detailed scouting report with 70+ stats (1999+).
const report = await api.getScoutingReport('Duke', 2025);
// Returns: Object with detailed offensive/defensive stats and rankings
getConferenceStandings(conf, season)Get conference standings.
const standings = await api.getConferenceStandings('ACC', 2025);
getConferenceOffense(conf, season)Get conference offensive stats.
const offense = await api.getConferenceOffense('ACC', 2025);
getConferenceDefense(conf, season)Get conference defensive stats.
const defense = await api.getConferenceDefense('ACC', 2025);
getConferenceStats(conf, season)Get aggregate stats for one or all conferences.
// Single conference
const accStats = await api.getConferenceStats('ACC', 2025);
// All conferences
const allConfs = await api.getConferenceStats(null, 2025);
getFanMatch(date)Get FanMatch predictions and results (2014+).
const fanmatch = await api.getFanMatch('2025-03-15');
// Returns: { date, url, games: [...], summary: {...} }
getCurrentSeason()Get the current/latest published season.
const season = await api.getCurrentSeason();
// Returns: 2025
kenpom --ratings
import { KenpomAPI } from 'kenpom-api';
const api = new KenpomAPI();
await api.login();
const ratings = await api.getPomeroyRatings();
console.log(`Top team: ${ratings[0].Team} (${ratings[0].AdjEM})`);
await api.close();
# Fetch all yearly endpoints for 2020-2025
kenpom --all-yearly --start 2020 --end 2025
# Fetch all player metrics for a season
kenpom --player-stats --all-metrics --year 2025
# Fetch specific metric for a conference
kenpom --player-stats --metric eFG --conference ACC --year 2025
const api = new KenpomAPI();
await api.login();
// Get all player stats
const allStats = await api.getAllPlayerStats(2025);
// Find top shooters
const topShooters = allStats.eFG.slice(0, 10);
console.log('Top 10 eFG%:', topShooters.map(p => `${p.Player}: ${p.eFG}`));
await api.close();
# Get Duke's schedule
kenpom --schedule --team Duke --year 2025
# Get all team schedules (takes a while)
kenpom --schedule --year 2025
const api = new KenpomAPI();
await api.login();
// Get schedule
const schedule = await api.getSchedule('Duke', 2025);
console.log(`Duke: ${schedule.length} games`);
// Get detailed scouting report
const report = await api.getScoutingReport('Duke', 2025);
console.log(`AdjO: ${report.AdjO}, AdjD: ${report.AdjD}`);
await api.close();
# Single date
kenpom --fanmatch-date 2025-03-15
# Entire season
kenpom --fanmatch --year 2025
const api = new KenpomAPI();
await api.login();
const fanmatch = await api.getFanMatch('2025-03-15');
console.log(`${fanmatch.games.length} games on ${fanmatch.date}`);
for (const game of fanmatch.games) {
console.log(`${game.Team1} vs ${game.Team2}: Predicted ${game.PredictedWinner}`);
}
await api.close();
# Preview without fetching
kenpom --all --year 2025 --dry-run
Output:
================================================================================
KenPom Data Fetcher
================================================================================
Mode: single year: 2025
Years to process: 1
Output directory: datasets
DRY RUN: No data will be fetched
================================================================================
Selected endpoints:
✓ Arenas (2010+)
✓ Program Ratings
✓ Trends
✓ Home Court Advantage
✓ Pomeroy Ratings (1999+)
...
Data is saved to datasets/ by default, organized by endpoint type:
datasets/
├── arenas/
│ └── arenas.json
├── program_ratings/
│ └── program_ratings.json
├── trends/
│ └── trends.json
├── hca/
│ └── hca.json
├── ratings/
│ └── ratings_2025.json
├── efficiency/
│ └── efficiency_2025.json
├── four_factors/
│ └── four_factors_2025.json
├── team_stats/
│ ├── team_stats_2025.json
│ └── team_stats_defense_2025.json
├── point_dist/
│ └── point_dist_2025.json
├── height/
│ └── height_2025.json
├── player_stats/
│ ├── player_stats_eFG_2025.json
│ └── player_stats_2025.json # All metrics
├── kpoy/
│ └── kpoy_2025.json
├── refs/
│ └── refs_2025.json
├── game_attribs/
│ └── game_attribs_2025.json
├── valid_teams/
│ └── valid_teams_2025.json
├── schedule/
│ └── 2025/
│ ├── Duke_schedule_2025.json
│ └── North Carolina_schedule_2025.json
└── fanmatch/
└── 2025/
├── fanmatch_2025-03-15.json
└── fanmatch_2025-03-16.json
Data Format:
All data is saved as JSON arrays or objects:
[
{
"Rk": 1,
"Team": "Houston",
"Conf": "B12",
"W-L": "32-4",
"AdjEM": 30.52,
"AdjO": 119.2,
"AdjO.Rank": 14,
"AdjD": 88.7,
"AdjD.Rank": 1
}
]
The API uses a tiered approach to handle Cloudflare protection:
# Auto mode (default) - tries Tier 1 first, then Tier 2
kenpom --ratings --client auto
# Force specific tier
kenpom --ratings --client tier1
kenpom --ratings --client tier2
// Auto mode (default)
const api = new KenpomAPI({ clientTier: 'auto' });
// Force specific tier
const api = new KenpomAPI({ clientTier: 'tier2' });
The service includes built-in rate limiting with random delays (2-7 seconds) between requests. This helps avoid being blocked by KenPom.
const api = new KenpomAPI();
try {
await api.login();
// ... fetch data
} catch (error) {
if (error.message.includes('Login verification failed')) {
console.error('Check your credentials');
}
} finally {
await api.close(); // Always close the connection
}
The API validates season parameters and throws clear errors:
// This will throw an error - player stats only available from 2004
await api.getPlayerStats(2003, 'eFG');
// Error: Season 2003 is not available for PLAYER_STATS. Minimum year: 2004
This package is written in TypeScript and provides full type definitions out of the box. No additional @types packages are required.
import { KenpomAPI } from 'kenpom-api';
import type {
// API Options
KenpomAPIOptions,
KenpomCredentials,
LogLevel,
ClientTier,
// Data Types
PomeroyRating,
EfficiencyData,
FourFactorsData,
TeamStatsData,
PlayerStats,
ScheduleGame,
FanMatchResponse,
ScoutingReportStats,
// Validation Types
PlayerMetric,
GameAttribMetric,
Conference,
} from 'kenpom-api';
All API methods return properly typed data:
const api = new KenpomAPI();
await api.login();
// Returns PomeroyRating[]
const ratings = await api.getPomeroyRatings(2025);
ratings[0].Team; // string
ratings[0].AdjEM; // string
ratings[0].Conf; // string
// Returns FourFactorsData[]
const factors = await api.getFourFactors(2025);
factors[0]['Off-eFG%']; // string
// Returns ScheduleGame[]
const schedule = await api.getSchedule('Duke', 2025);
schedule[0].Result; // string
schedule[0].Location; // string
await api.close();
Type-safe access to configuration and utilities:
// Configuration constants and validators
import {
PLAYER_METRICS,
GAME_ATTRIB_METRICS,
CONFERENCES,
validatePlayerMetric,
validateConference,
validateSeason,
} from 'kenpom-api/config';
// Utility functions
import {
writeToFile,
readFromFile,
generateYearRange,
generateDateRange,
} from 'kenpom-api/utils';
// HTML parsers (advanced usage)
import {
parsePomeroyRatings,
parseFourFactors,
parseSchedule,
} from 'kenpom-api/parsers';
// Type definitions only
import type { PlayerMetric, Conference } from 'kenpom-api/types';
The package is compiled with strict TypeScript settings. All exported types are accurate and reflect the actual data structures returned by the KenPom.com website.
Error: KenPom credentials not found
Solution: Create .env file with your credentials:
KENPOM_EMAIL=your.email@example.com
KENPOM_PASSWORD=your_password
Error: Login verification failed - "Logged in as" not found
Solution:
--client tier2Error: All login attempts failed
Solution:
--client tier2Error: Cannot find module
Solution: Install dependencies:
cd kenpom-api
npm install
Warning: Tier 2 client not available
Solution: Install optional dependencies for headless browser support:
npm install puppeteer-extra puppeteer-extra-plugin-stealth
# Clone repository
git clone https://github.com/aself101/kenpom-api.git
cd kenpom-api
# Install dependencies
npm install
# Run CLI from source
node cli.js --examples
node cli.js --ratings --year 2025 --dry-run
npm test # Run all 229 tests with Vitest
npm run test:watch # Watch mode for development
npm run test:coverage # Generate coverage report (86.98% overall)
Test Coverage:
npm run kenpom # Run CLI
npm run kenpom:help # Show help
npm run kenpom:ratings # Fetch ratings
npm run kenpom:efficiency # Fetch efficiency stats
Pass additional flags with --:
npm run kenpom -- --ratings --year 2025 --dry-run
KenPom does not publish official rate limits, but the service includes:
Recommendation: When fetching large amounts of data (e.g., all team schedules), consider running during off-peak hours and using longer delays.
This package is part of the data-collection ecosystem. Check out these other sports data services:
cbb-data-api - College Basketball Data REST API wrapperodds-api - Sports betting odds API wrapperDisclaimer: This project is an independent community wrapper and is not affiliated with KenPom.com. Please respect KenPom.com's terms of service and rate limits. A valid KenPom subscription is required.
This package includes built-in rate limiting (2-7 second delays between requests), but users are ultimately responsible for how they use this tool. Please:
Abuse of this package (e.g., excessive scraping, circumventing access controls) may result in your account being suspended or banned from KenPom.com. The maintainers of this package are not responsible for any consequences arising from misuse. Let's try and be decent with this.
Version 1.0 represents a complete rewrite from JavaScript to TypeScript. If you're upgrading from v0.x, note the following changes:
ESM Only - The package now uses ES modules exclusively. Update your imports:
// Before (CommonJS)
const { KenpomAPI } = require('kenpom-api');
// After (ESM)
import { KenpomAPI } from 'kenpom-api';
Node.js 20+ - Minimum Node.js version is now 20.18.0 (up from 14.x).
Async/Await Required - All API methods now return Promises. The callback-style API has been removed.
/config, /utils, /parsers, and /types--examples flag, improved dry-run outputThe core API surface remains the same. Method names, parameters, and return structures are unchanged:
// Same API as v0.x, now with types
const api = new KenpomAPI();
await api.login();
const ratings = await api.getPomeroyRatings(2025);
await api.close();
This project is licensed under the MIT License - see the LICENSE file for details.
Note: This service implements web scraping for data collection. Fine-tuning and custom parsing can be added as needed following the same patterns established in the parsers module.
FAQs
KenPom.com API wrapper - College basketball statistics for Node.js with CLI
We found that kenpom-api demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.
Security News
The Axios compromise shows how time-dependent dependency resolution makes exposure harder to detect and contain.