NBA Tracker
NBA Game Viewing Assistant
Wrapper for nba_api to support game viewing scenarios:
- Track favorite players/teams
- View schedules and add to calendar
- Real-time scores
- Crunch time alerts (last 5 minutes + score difference < 5)
⚠️ Note: This tool is designed for viewing purposes. For prediction markets/betting use cases, consider more real-time professional data sources (e.g., Sportradar, Genius Sports) with lower latency and higher reliability requirements.
Installation
pip install nba_api pandas
Quick Start
Check Team Standings
from nba_api.stats.endpoints import leaguestandings
standings = leaguestandings.LeagueStandings()
df = standings.get_data_frames()[0]
# Check Hornets record
hornets = df[df['TeamName'] == 'Hornets']
print(hornets[['TeamName', 'WINS', 'LOSSES', 'WinPCT']])
View Today's Schedule
from nba_api.stats.endpoints import scoreboardv3
from datetime import datetime
today = datetime.now().strftime('%Y-%m-%d')
board = scoreboardv3.ScoreboardV3(game_date=today, league_id='00')
data = board.get_dict()
for game in data['scoreboard']['games']:
home = game['homeTeam']
away = game['awayTeam']
print(f"{away['teamName']} @ {home['teamName']}")
Get Player Stats
from nba_api.stats.endpoints import playercareerstats
from nba_api.stats.static import players
# Find player ID
ball_info = players.find_players_by_full_name("LaMelo Ball")
player_id = ball_info[0]['id']
# Get career stats
career = playercareerstats.PlayerCareerStats(player_id=player_id)
df = career.season_totals_regular_season.get_data_frame()
print(df.tail())
Real-time Scores
from nba_api.live.nba.endpoints import scoreboard
games = scoreboard.ScoreBoard()
data = games.get_dict()
for game in data['scoreboard']['games']:
home = game['homeTeam']['teamName']
away = game['awayTeam']['teamName']
home_score = game['homeTeam']['score']
away_score = game['awayTeam']['score']
status = game['gameStatusText']
print(f"{away} @ {home}: {away_score}-{home_score} ({status})")
Example Use Cases
Example 1: Track a Specific Player
Scenario: Track LaMelo Ball's games and add to calendar
from nba_api.stats.static import players
from nba_api.stats.endpoints import playerinjuries, teamgamelog
from datetime import datetime, timedelta
# 1. Find player
ball = players.find_players_by_full_name("LaMelo Ball")[0]
print(f"Player: {ball['full_name']}")
# 2. Check injury status
try:
injuries = playerinjuries.PlayerInjuries(player_id=ball['id'])
injury_df = injuries.get_data_frames()[0]
if not injury_df.empty:
print(f"⚠️ Injury: {injury_df.iloc[0]['INJURY']}")
else:
print("✅ No injuries")
except:
print("⚠️ Injury info not available")
# 3. Get upcoming games
gamelog = teamgamelog.TeamGameLog(
team_id=ball['team_id'],
season='2025-26'
)
df = gamelog.get_data_frames()[0]
# Filter future games
today = datetime.now()
upcoming = []
for idx, row in df.iterrows():
try:
game_date = datetime.strptime(row['GAME_DATE'], '%Y-%m-%d')
if game_date > today:
upcoming.append({
'date': row['GAME_DATE'],
'matchup': row['MATCHUP']
})
except:
continue
print(f"\nUpcoming games:")
for game in upcoming[:5]:
print(f" {game['date']}: {game['matchup']}")
Example 2: Crunch Time Alerts
Scenario: Get notified when game is in crunch time (last 5 min + close score)
from nba_api.live.nba.endpoints import scoreboard, playbyplay
import time
from datetime import datetime
def check_crunch_time():
"""Check for crunch time games (period >= 4, clock < 5:00, score diff <= 5)"""
games = scoreboard.ScoreBoard()
data = games.get_dict()
crunch_games = []
for game in data['scoreboard']['games']:
if game['gameStatus'] != 2: # Only live games
continue
home_score = game['homeTeam']['score']
away_score = game['awayTeam']['score']
score_diff = abs(home_score - away_score)
if score_diff > 5:
continue
# Get detailed time from play-by-play
try:
pbp = playbyplay.PlayByPlay(game_id=game['gameId'])
pbp_data = pbp.get_dict()
if pbp_data['game']['actions']:
last_action = pbp_data['game']['actions'][-1]
period = last_action.get('period', 0)
clock = last_action.get('clock', '12:00')
# Only 4th quarter or OT
if period >= 4:
mins, secs = clock.split(':')
remaining = int(mins) + int(secs) / 60
if remaining < 5:
crunch_games.append({
'game': f"{game['awayTeam']['teamName']} @ {game['homeTeam']['teamName']}",
'score': f"{away_score} - {home_score}",
'clock': clock,
'period': period
})
except:
continue
return crunch_games
# Monitor loop
print("🏀 Monitoring for crunch time games...")
notified = set()
while True:
games = check_crunch_time()
for game in games:
key = f"{game['game']}_{game['clock']}"
if key not in notified:
print(f"\n🔥 CRUNCH TIME!")
print(f" {game['game']}")
print(f" Score: {game['score']}")
print(f" Time: {game['clock']} (Q{game['period']})")
notified.add(key)
time.sleep(30) # Check every 30 seconds
Example 3: Add Games to Calendar
Scenario: Automatically add player's games to Apple Calendar
import subprocess
from datetime import datetime, timedelta
def add_game_to_calendar(player_name, game_date, matchup, calendar="NBA"):
"""Add game to Apple Calendar"""
# Parse game time (assumes 7:00 PM local)
game_time = datetime.strptime(game_date, '%Y-%m-%d')
game_time = game_time.replace(hour=19, minute=0)
title = f"🏀 {player_name}: {matchup}"
end_time = game_time + timedelta(hours=2, minutes=30)
script = f'''
tell application "Calendar"
tell calendar "{calendar}"
make new event at end with properties {{summary:"{title}", start date:date "{game_time.strftime('%Y-%m-%d %H:%M:%S')}", end date:date "{end_time.strftime('%Y-%m-%d %H:%M:%S')}"}}
end tell
end tell
'''
try:
subprocess.run(['osascript', '-e', script], check=True)
print(f"✅ Added: {title} on {game_date}")
return True
except Exception as e:
print(f"❌ Failed: {e}")
return False
# Usage
add_game_to_calendar("LaMelo Ball", "2026-03-18", "Heat @ Hornets")
Common Commands
# Hornets standings
python -c "from nba_api.stats.endpoints import leaguestandings; df = leaguestandings.LeagueStandings().get_data_frames()[0]; print(df[df['TeamName'] == 'Hornets'][['TeamName', 'WINS', 'LOSSES', 'WinPCT']])"
# Today's games
python -c "from nba_api.stats.endpoints import scoreboardv3; from datetime import datetime; board = scoreboardv3.ScoreboardV3(game_date=datetime.now().strftime('%Y-%m-%d'), league_id='00'); [print(f\"{g['awayTeam']['teamName']} @ {g['homeTeam']['teamName']}\") for g in board.get_dict()['scoreboard']['games']]"
# Player career stats
python -c "from nba_api.stats.static import players; from nba_api.stats.endpoints import playercareerstats; p = players.find_players_by_full_name('LaMelo Ball')[0]; df = playercareerstats.PlayerCareerStats(player_id=p['id']).season_totals_regular_season.get_data_frame(); print(df.tail())"
Error Handling
from nba_api.stats.library.http import NBAHTTPError
try:
# API call
pass
except NBAHTTPError as e:
print(f"NBA API Error: {e}")
except Exception as e:
print(f"Unknown error: {e}")
Important Notes
- Rate Limiting: Free but may be throttled if too frequent. Cache data when possible.
- Timezone Conversion: NBA times are US Eastern Time. Convert to local timezone (+12/13 hours for Beijing).
- Live Data Delay: Live API has 1-3 second delay.
- Update Frequency: Stats API updates slowly. Check once per minute max.
More Information
See API_REFERENCE.md for complete endpoint documentation.