NFL Data Library - Multi-Language Support

This repository contains NFL data libraries for both Python and JavaScript/TypeScript.

🐍 Python Library (nfl_data_py/)

The original Python library for accessing NFL data from various sources.

• Location: nfl_data_py/ directory
• Documentation: See nfl_data_py/README.md
• Installation: pip install nfl_data_py

🟨 JavaScript/TypeScript Library

Modern JavaScript/TypeScript port with full type safety and web compatibility.

• Documentation: See README-JS.md
• Installation: npm install @camfleety/nfl-data-js ✅ Live on NPM

Quick Start (JavaScript/TypeScript)

# Install the published package
npm install @camfleety/nfl-data-js
# or with Bun
bun add @camfleety/nfl-data-js

import nflData from '@camfleety/nfl-data-js';

// Import weekly player stats
const weeklyData = await nflData.importWeeklyData([2023]);

// Import team information  
const teams = await nflData.importTeamDesc();

🏈 Getting Specific NFL Data

Player Performance Data

// Get all weekly player stats for 2023 season
const playerStats = await nflData.importWeeklyData([2023]);

// Get seasonal aggregated stats (faster for season totals)
const seasonStats = await nflData.importSeasonalData([2023]);

// Get QB performance ratings
const qbrData = await nflData.importQbr([2023], 'nfl', 'season');
console.log(`Top QB: ${qbrData[0].name_display} - QBR: ${qbrData[0].qbr_total}`);

Team & Schedule Information

// Get all 32 NFL teams with colors, logos, and details
const teams = await nflData.importTeamDesc();
const chiefs = teams.find(t => t.team_abbr === 'KC');
console.log(`${chiefs.team_name} colors: ${chiefs.team_color}, ${chiefs.team_color2}`);

// Get 2023 season schedule
const schedule = await nflData.importSchedules([2023]);
const week1Games = schedule.filter(game => game.week === 1);
console.log(`Week 1: ${week1Games.length} games`);

// Get current season rosters
const rosters = await nflData.importSeasonalRosters([2023]);
const weeklyRosters = await nflData.importWeeklyRosters([2023]);

Advanced Analytics

// Get Next Gen Stats (tracking data)
const rushingNGS = await nflData.importNgsData('rushing', [2023]);
const passingNGS = await nflData.importNgsData('passing', [2023]);
const receivingNGS = await nflData.importNgsData('receiving', [2023]);

// Get play-by-play data (most detailed)
const pbpData = await nflData.importPbpData([2023]);
console.log(`${pbpData.length} plays in 2023 season`);

Draft & Historical Data

// Get draft picks and combine results
const draftPicks = await nflData.importDraftPicks([2023]);
const combineData = await nflData.importCombineData([2023]);

// Clean and standardize player names
const rawData = [
  { name: 'Gary Jennings Jr', college: 'Ole Miss', team: 'NA' }
];
const cleanedData = nflData.cleanNflData(rawData);
console.log(cleanedData[0]); 
// { name: 'Gary Jennings', college: 'Mississippi', team: null }

Performance & Caching

// Enable caching for faster subsequent requests
const teams = await nflData.importTeamDesc(); // First call - hits network
const teamsAgain = await nflData.importTeamDesc(); // Second call - from cache

// Check cache status
console.log(`Cache size: ${nflData.getCacheSize()} bytes`);

// Clear cache when needed
nflData.clearCache();

Real-World Example: Team Analysis

async function analyzeTeam(teamAbbr: string, season: number) {
  // Get team info
  const teams = await nflData.importTeamDesc();
  const team = teams.find(t => t.team_abbr === teamAbbr);
  
  // Get team's games
  const schedule = await nflData.importSchedules([season]);
  const teamGames = schedule.filter(game => 
    game.away_team === teamAbbr || game.home_team === teamAbbr
  );
  
  // Get team's player stats
  const playerStats = await nflData.importWeeklyData([season]);
  const teamPlayers = playerStats.filter(p => p.recent_team === teamAbbr);
  
  return {
    teamInfo: team,
    gamesPlayed: teamGames.length,
    totalPlayers: teamPlayers.length,
    topRusher: teamPlayers
      .filter(p => p.rushing_yards > 0)
      .sort((a, b) => b.rushing_yards - a.rushing_yards)[0]
  };
}

// Analyze Kansas City Chiefs 2023 season
const chiefsAnalysis = await analyzeTeam('KC', 2023);
console.log(chiefsAnalysis);

🌐 Platform Compatibility

The JavaScript/TypeScript library works seamlessly across all environments:

// ✅ Node.js
import nflData from '@camfleety/nfl-data-js';

// ✅ Bun (recommended - fastest performance)
import nflData from '@camfleety/nfl-data-js';

// ✅ Browser/Web Apps
import nflData from '@camfleety/nfl-data-js';

// ✅ Next.js/React
import nflData from '@camfleety/nfl-data-js';

Features by Environment:

• Node.js: Full functionality + file system caching
• Bun: Full functionality + memory caching (fastest)
• Browser: Full functionality + memory caching
• All: Automatic environment detection & optimized builds

📊 Features Comparison

| Feature | Python | JavaScript/TypeScript | |---------|--------|----------------------| | Play-by-play data | ✅ | ✅ | | Weekly/seasonal stats | ✅ | ✅ | | Team rosters | ✅ | ✅ | | Schedules & team info | ✅ | ✅ | | Draft & combine data | ✅ | ✅ | | Advanced analytics | ✅ | ✅ | | Data cleaning | ✅ | ✅ | | Caching system | ✅ | ✅ | | Type safety | ❌ | ✅ | | Browser support | ❌ | ✅ | | Concurrent requests | ❌ | ✅ |

🤝 Contributing

We welcome contributions to both libraries! Please see individual documentation for specific contribution guidelines.

📄 License

MIT License - see LICENSE for details.

🙏 Recognition

Built on the incredible work of the nflverse community, including Ben Baldwin, Sebastian Carl, Lee Sharpe, and Tan Ho.