![\"\"](\"https:\/\/wollen.org\/blog\/wp-content\/uploads\/2026\/01\/research-gate-image-1.png\")
<\/a>\n
1. What’s a heatmap?<\/h4>\n
Just like a histogram visualizes a variable’s distribution along one dimension, a heatmap operates on two dimensions. A classic heatmap has square bins. The more points in a bin, the darker the color.<\/p>\n
That makes sense. We could divide the basketball court into a grid and count how many shots fall within each square.<\/p>\n The main drawback is what happens at boundaries. For example, the two points near (20, 20) are right next to each other but they contribute to different bins. As far as the math is concerned they’re totally unrelated data points. A blocky, discontinuous approach like this can obscure what the data is saying.<\/p>\n You might think, “Okay, so make the squares tiny.” That would definitely improve things and we’ll do that, but we can go a step further. Instead of simply grouping shots into bins and counting them, we can look at precise spots on the court and calculate a weighted total of every shot nearby. Because they’re weighted, shots closer to the spot will contribute more than shots further away.<\/p>\n If you repeat that calculation many times all over the court you’ll end up smoothing out the data. This technique is called a Kernel Density Estimate (KDE). It will let us analyze the data in a smooth, continuous way and easily identify “hot spots” on the court.<\/p>\n More often than not, the best way to pull NBA stats is from nba.com<\/a>. The data on their web site is provided by an internal API that remains open to the public\u2014at least for now. nba_api<\/a> is a Python client to interface with it.<\/p>\n Once you’ve installed the package you can start pulling data. First you’ll need a player’s ID. You can find it in the player URL on nba.com or search for it this way.<\/p>\n We want shot chart data so we’ll use the Pass Luka’s nba_api can package the data into a dictionary, a JSON object, or a pandas DataFrame. I prefer pandas.<\/p>\n The DataFrame includes 24 columns so I won’t try to print it here. Suffice it to say you could spend a lot<\/em> of time working with stats from this one endpoint alone.<\/p>\n We’re most interested in (x, y) locations of shots, which are found in the LOC_X<\/em> and LOC_Y<\/em> columns. Let’s narrow down the DataFrame and take a look.<\/p>\n The output:<\/p>\n We don’t have to worry about made vs. missed shots because we’re interested in overall shot selection. At this point, if you wanted to, you could take the DataFrame and create something like the shot chart at the top of this post. But let’s keep pushing forward.<\/p>\n LOC_X<\/em> and LOC_Y<\/em> use an odd unit system. You might think those numbers are inches but they’re not. They’re actually tenths of a foot. So 157 means 15.7 feet. For some reason. Let’s go ahead and divide the values by 10 and create new columns named LOC_X_FT<\/em> and LOC_Y_FT<\/em>.<\/p>\n The data assumes the hoop is at the top of the screen. That’s how shot charts are presented on nba.com so it makes sense. If we plot the data as-is with (0, 0) at the bottom, right-corner threes will be plotted as left-corner threes, and so on. We could<\/em> transform the data now, i.e. subtract LOC_Y<\/em> from 940 (a court is 94 feet long). But it will be easier to skip it and call Additionally, y=0 is located at the center of the hoop, which is 5’3″ from the baseline, so we need to add 5.25. Our y=0 will be the baseline.<\/p>\n Now we have the necessary (x, y) shot data for a heatmap. The code seems tricky at first but it’s only a few lines. Let’s walk through what each line is doing.<\/p>\n Use these lists to create a NumPy Then create a KDE model. Now we have a KDE model capable of calculating values within the 2D area (the basketball court). We need to tell the model what points we’re interested in. That is, all the points contained in Pass those coordinates into To recap, we’ve taken a scattershot of points (Luka’s shot data) and created a regularly spaced, fine mesh grid of smoothed<\/em> points. You might notice how similar this KDE code is to our Matterhorn’s grid interpolation<\/a> in a previous post. The scripts generate very different plots but both involve laying out a I’ll use a custom Matplotlib style that will be linked at the bottom of this post.<\/p>\n Create a Figure and an Axes instance ( We have a couple options for heatmap arrays in Matplotlib. In most cases, Pass in the 2D arrays we created before. Next, paint all the important markings on the court. It requires a bunch of lines, a few arcs, and a circle. You could certainly add more detail if you wanted.<\/p>\n Tick labels are mostly straightforward except I want to mirror y-ticks on the right-hand side of the plot. We can do this by calling As I mentioned earlier, data from nba.com assumes the hoop (0, 0) is at the top of the plot. That’s no problem. We can simply invert both y axes.<\/p>\n Finally, save the figure. A high Luka’s shot chart is more interesting than the Miami Heat squad anyway!<\/p>\n Notice his preference for shooting threes from the left. It also stands out how much right-handed Luka prefers layups from that side of the basket. Still, the “blob” in the protected area is reasonably balanced. Some smaller players show a tendency to attack from the baseline rather than directly through the defense.<\/p>\n These charts are great for side-by-side comparison. I won’t post the code but you can easily arrange several players into a subplot grid. Below are the top eight scorers of the 2025-26 season.<\/p>\n I’m sure these maps are something every NBA analytics team keeps an eye on.<\/p>\n It’s clear that Luka takes a wider variety of shots than other top scorers. No surprise there. His versatility makes him one of the most exciting players to watch. Be aware that colors are normalized for each player. Red on one map doesn’t represent the same shot volume as red on another.<\/p>\n<\/a><\/p>\n<\/a>
\n2. Prepare the data.<\/h4>\n
from nba_api.stats.static import players\r\n\r\nplayer_list = players.find_players_by_full_name(\"Luka Don\u010di\u0107\")<\/pre>\n
shotchartdetail<\/code> endpoint.<\/p>\nplayer_id<\/code> here. team_id=0<\/code> ensures that we receive a player’s complete stats even if they’ve been traded. It’s not necessary for Luka but I usually include it anyway. The other arguments specify the stat we’re interested in (field goal attempts) and coverage (2025-26 regular season).<\/p>\nfrom nba_api.stats.endpoints import shotchartdetail\r\n\r\nresponse = shotchartdetail.ShotChartDetail(player_id=1629029,\r\n team_id=0,\r\n season_nullable=\"2025-26\",\r\n season_type_all_star=\"Regular Season\",\r\n context_measure_simple=\"FGA\")<\/pre>\n
import pandas as pd\r\n\r\ndf = response.get_data_frames()[0]<\/pre>\n
print(df[['GAME_ID', 'PLAYER_NAME', 'EVENT_TYPE', 'LOC_X', 'LOC_Y']].head())<\/pre>\n
GAME_ID PLAYER_NAME EVENT_TYPE LOC_X_FT LOC_Y_FT\r\n0 22500002 Luka Don\u010di\u0107 Made Shot -6.0 17.75\r\n1 22500002 Luka Don\u010di\u0107 Missed Shot 1.8 31.15\r\n2 22500002 Luka Don\u010di\u0107 Made Shot -8.8 30.05\r\n3 22500002 Luka Don\u010di\u0107 Missed Shot -16.7 26.95\r\n4 22500002 Luka Don\u010di\u0107 Missed Shot 0.2 8.05<\/pre>\n
ax.invert_yaxis<\/code> later.<\/p>\ndf['LOC_X_FT'] = df['LOC_X'] \/ 10\r\n\r\ndf['LOC_Y_FT'] = df['LOC_Y'] \/ 10 + 5.25<\/pre>\n
linspace<\/code> is simple. It returns a list of evenly spaced values between two limits. -25 to 25 corresponds to a basketball court’s 50-ft width. 0 to 47.5 is the length of a half court. All of Luka’s shot coordinates will fall within these bounds. A higher number of steps will be less “grainy,” but I prefer a little grain. 200 is a nice medium value.<\/p>\nmeshgrid<\/code>. This method returns a pair of 2D arrays that together represent points within the grid layout. Think of them like a map overlaid on the basketball court.<\/p>\nimport numpy as np\r\n\r\nx_grid = np.linspace(-25, 25, 200)\r\ny_grid = np.linspace(0, 47.5, 200)\r\nx_grid, y_grid = np.meshgrid(x_grid, y_grid)<\/pre>\n
gaussian_kde<\/code> accepts the real-world data. It returns a model that can be used to estimate values within its 2D area.<\/p>\nnp.vstack<\/code> is a bit of a curveball but don’t let it trip you up. It simply arranges the two pandas Series into a vertically stacked<\/em> 2D array, which is how guassian_kde<\/code> expects the data.<\/p>\nbw_method<\/code> is an optional parameter that tweaks how the algorithm handles nearby points. A low bandwidth<\/em>, like 0.04, will reveal more local maxima (hot spots) in the data. A higher bandwidth will tend to blur peaks together into a single large spot. Using a value this low is often a bad idea because it can convey false precision, but for a heatmap I think it’s justified. We aren’t trying to build a model to predict Luka’s future shots out of sample. We’re visualizing his shot selection in the 2025-26 season.<\/p>\nfrom scipy.stats import gaussian_kde\r\n\r\nkde_model = gaussian_kde(np.vstack([df['LOC_X_FT'], df['LOC_Y_FT']]), bw_method=0.04)<\/pre>\n
x_grid<\/code> and y_grid<\/code>.<\/p>\npositions<\/code> is essentially an array of (x, y) ordered pairs. Once again, we vertically stack the data because that’s how the model expects it.<\/p>\nkde_model<\/code> to do the calculations. It returns a 1D array so we reshape<\/code> it to match our 2D arrays.<\/p>\nz_density<\/code> is the final product. It’s the 2D array of “heat” values that we’ll plot in a moment.<\/p>\npositions = np.vstack([x_grid.flatten(), y_grid.flatten()])\r\n\r\nz_density = np.reshape(kde_model(positions), x_grid.shape)<\/pre>\n
z_density<\/code> has a lot more elements than the data we pulled from the API.<\/p>\nmeshgrid<\/code> and calculating a value at each point. Except in this case, values will be visualized with color (2D) rather than elevation (3D).<\/p>\n
\n3. Plot the data.<\/h4>\n
ax<\/code>) for plotting.<\/p>\nimport matplotlib.pyplot as plt\r\n\r\nplt.style.use(\"wollen_shooting.mplstyle\")\r\n\r\nfig, ax = plt.subplots()<\/pre>\n
pcolormesh<\/code> is the best choice. imshow<\/code> can be slightly faster but it treats the grid like square pixels, so you have to think about aspect ratio. Let’s stick with the more flexible method.<\/p>\ncmap<\/code> refers to Matplotlib’s colormap<\/a>. It’s the palette that will determine how hot and cold spots are presented. You can experiment with cmap<\/code> and change the style dramatically. Or create your own color map.<\/p>\nax.pcolormesh(x_grid, y_grid, z_density, cmap=\"turbo\")<\/pre>\n
from matplotlib.patches import Arc, Circle\r\n\r\n\r\ndef paint_court(axes):\r\n for x_vals, y_vals in [([-25, 25], [47, 47]),\r\n ([-3, 3], [4, 4]),\r\n ([-8, -8], [0, 19]),\r\n ([8, 8], [0, 19]),\r\n ([-8, 8], [19, 19]),\r\n ([-22, -22], [0, 14]),\r\n ([22, 22], [0, 14])]:\r\n axes.plot(x_vals, y_vals, color=\"white\", lw=2)\r\n axes.add_artist(Circle((0, 5.25), 0.75, lw=2, ec=\"white\", fc=\"None\"))\r\n axes.add_artist(Arc((0, 5.25), width=47.4, height=47.4, angle=0, theta1=21.8, theta2=158.2, lw=2, ec=\"white\", fc=\"None\"))\r\n axes.add_artist(Arc((0, 5.25), width=8, height=8, angle=0, theta1=0, theta2=180, lw=2, ec=\"white\", fc=\"None\"))\r\n axes.add_artist(Arc((0, 19), width=10, height=10, angle=0, theta1=0, theta2=180, lw=2, ec=\"white\", fc=\"None\"))\r\n axes.add_artist(Arc((0, 47), width=12, height=12, angle=0, theta1=180, theta2=0, lw=2, ec=\"white\", fc=\"None\"))\r\n\r\n\r\npaint_court(ax)<\/pre>\n
ax.twinx<\/code>. I think it helps to see court measurements in feet to judge how long certain shots are.<\/p>\nx_ticks = range(-25, 30, 5)\r\nx_tick_labels = [f\"{abs(n)} ft\" if n != 0 else \"0\" for n in x_ticks]\r\n\r\ny_ticks = range(0, 50, 5)\r\ny_tick_labels = [f\"{abs(n)} ft\" if n != 0 else \"0\" for n in y_ticks]\r\n\r\nax.set(xticks=x_ticks,\r\n xticklabels=x_tick_labels,\r\n xlim=(-25, 25),\r\n yticks=y_ticks,\r\n yticklabels=y_tick_labels,\r\n ylim=(0, 47.5))\r\n\r\nax1 = ax.twinx()\r\n\r\nax1.set(yticks=y_ticks,\r\n yticklabels=y_tick_labels,\r\n ylim=(0, 47.5))<\/pre>\nax.invert_yaxis()\r\nax1.invert_yaxis()<\/pre>\n
dpi<\/code> makes a real difference in this case because of all the detail.<\/p>\nplt.savefig(\"luka_fga.png\", dpi=300)<\/pre>\n
\n4. The output.<\/h4>\n
<\/a><\/p>\n
\n<\/a><\/p>\n