Skip to main content

​
Overview

The dribble.py script collects shooting performance data categorized by the number of dribbles taken before the shot. This provides insight into shot creation ability, isolation scoring, and rhythm shooting patterns.

​
Data Source

API: NBA.com Stats API
Endpoint: leaguedashplayerptshot with DribbleRange parameter

​
Functions

​
get_dribbleshots()

Retrieves player shooting statistics grouped by dribble count.
​
years
list
required
List of season years to collect (e.g., [2023, 2024])
​
ps
boolean
default:"False"
Set to True for playoff data, False for regular season
Dribble Categories:
  • 0 Dribbles - Catch and shoot immediately
  • 1 Dribble - One dribble before shooting
  • 2 Dribbles - Two dribbles before shooting
  • 3-6 Dribbles - Multiple dribbles, moderate creation
  • 7+ Dribbles - Heavy dribbling, high creation difficulty
Returns: DataFrame with shooting stats for each dribble category 
# From dribble.py:13-77
def get_dribbleshots(years,ps = False):
    dribbles=['0%20Dribbles','1%20Dribble','2%20Dribbles','3-6%20Dribbles','7%2B%20Dribbles']
    terms = ['0','1','2','3_6','7+']
    folder = '/player_shooting/'
    sfolder=''
    stype = "Regular%20Season"
    if ps == True:
        stype="Playoffs"
        sfolder = "/playoffs"
    dataframe=[]
    for year in years:
        i = 0
        for dribble in dribbles:
            season = str(year)+'-'+str(year+1 - 2000)
            part1 = "https://stats.nba.com/stats/leaguedashplayerptshot?CloseDefDistRange=&College=&Conference=&Country=&DateFrom=&DateTo=&Division=&DraftPick=&DraftYear=&DribbleRange="
            part2 = "&GameScope=&GameSegment=&GeneralRange=&Height=&LastNGames=0&LeagueID=00&Location=&Month=0&OpponentTeamID=0&Outcome=&PORound=0&PerMode=Totals&Period=0&PlayerExperience=&PlayerPosition=&Season="
            part3 = "&SeasonSegment=&SeasonType="+stype+"&ShotClockRange=&ShotDistRange=&StarterBench=&TeamID=0&TouchTimeRange=&VsConference=&VsDivision=&Weight="
            url = part1+dribble+part2+season+part3
            # ... API call and processing

​
master_dribble()

Updates master dribble shot files with new season data.
​
year
integer
required
Season year to update
​
ps
boolean
default:"False"
Set to True for playoff data
Returns: Updated master DataFrame

​
Output Files

​
dribbleshot.csv / dribbleshot_ps.csv

Comprehensive shooting data by dribble count.
​
PLAYER_ID
integer
required
NBA player ID
​
PLAYER
string
required
Player name
​
TEAM
string
Team abbreviation
​
AGE
integer
Player age during season
​
GP
integer
Games played
​
G
integer
Games started
​
FREQ%
float
Frequency of shots in this dribble category (0-100%)
​
FGM
integer
Field goals made
​
FGA
integer
Field goal attempts
​
FG%
float
Field goal percentage (0-100%)
​
EFG%
float
Effective field goal percentage (0-100%)
​
2FG FREQ%
float
Two-point frequency within category
​
2FGM
integer
Two-point field goals made
​
2FGA
integer
Two-point attempts
​
2FG%
float
Two-point percentage
​
3FG FREQ%
float
Three-point frequency within category
​
3PM
integer
Three-pointers made
​
3PA
integer
Three-point attempts
​
3P%
float
Three-point percentage
​
dribbles
string
required
Dribble category: “0”, “1”, “2”, “3_6”, “7+”
​
year
integer
required
Season year

​
jumpdribble.csv / jumpdribble_ps.csv

Jump shot data filtered by dribble count (subset of dribbleshot focusing on jump shots).

​
Usage Examples

​
Collect Regular Season Data

import pandas as pd
from dribble import get_dribbleshots

# Get 2024 regular season dribble shooting data
df = get_dribbleshots([2024], ps=False)

# View distribution for a specific player
player_data = df[df['PLAYER'] == 'Stephen Curry']
print(player_data[['dribbles', 'FGA', 'FG%', 'FREQ%']])

​
Update Master File

from dribble import master_dribble

# Update regular season master file with 2024 data
master_df = master_dribble(2024, ps=False)

# Check total records
print(f"Total records: {len(master_df)}")
print(f"Years covered: {master_df['year'].min()} - {master_df['year'].max()}")

​
Analyze Shot Creation

import pandas as pd

df = pd.read_csv('dribbleshot.csv')
df_2024 = df[df['year'] == 2024]

# Find elite shot creators (high volume 7+ dribbles)
shot_creators = df_2024[
    (df_2024['dribbles'] == '7+') & 
    (df_2024['FGA'] >= 100)
].sort_values('FG%', ascending=False)

print(shot_creators[['PLAYER', 'TEAM', 'FGA', 'FG%', 'FREQ%']].head(10))

​
Compare Efficiency by Dribble Count

import pandas as pd
import matplotlib.pyplot as plt

df = pd.read_csv('dribbleshot.csv')
df_2024 = df[(df['year'] == 2024) & (df['FGA'] >= 50)]

# Average efficiency by dribble category
efficiency = df_2024.groupby('dribbles').agg({
    'FG%': 'mean',
    'EFG%': 'mean',
    'FGA': 'sum'
}).reset_index()

print(efficiency)
# Typically: 0 dribbles (C&S) > 1-2 dribbles > 3-6 > 7+ in efficiency

​
Analysis Use Cases

Shot Creation Ability

Identify players who can create their own shot (high 7+ dribble volume and efficiency)

Rhythm Shooting

Find players who shoot better with 1-2 dribbles vs catch-and-shoot

Offensive Role

Understand if a player is primarily a spot-up shooter or isolation scorer

Efficiency Decline

Measure how efficiency drops as dribble count increases

​
Configuration

Rate Limiting: Includes delays between API requests (see script for timing) Season Format: Uses YYYY-YY format (e.g., “2023-24”) API Headers: Requires standard NBA.com headers (User-Agent, Host, Referer)

Build docs developers (and LLMs) love

Get started for freeTalk to us