A Beginner’s Guide: Using the NBA API to obtain data for Shot Charts (Part 1)

This tutorial will provide an overview into querying the NBA API to obtain shot (Field Goal) details for a player throughout his career. The step by step instructions will provide an overview of each action we are performing.

There is also a consolidated function included at the end of this tutorial with the purpose of making it easier. This is recommended once you have looked through the steps and have

The Documentation for the NBA API (Credit to Swar Patel) is linked below— which outlines the endpoints with data that is available for querying using the API. This tutorial only covers 1 specific endpoint (/ShotChartDetail) within the API.

swar/nba_api

One additional shoutout — As with many acts of exploration in data science, I am merely standing on the shoulders of giants. Credit to Daniel Teo at DataVizardry for his tutorial on using the NBA API, which outlines how to pull shot chart details for a season for the entire NBA. His tutorial has been included below for additional reference.

NBA Shot Charts Part 1: Getting the Data (Python)

Now let’s started with using the NBA API! As a FYI: I am using Jupyter Notebook & Python 3.8.5 to run the following code.

1. Install the NBA API

! pip install nba_api

2. Import the necessary packages from the API

from nba_api.stats.static import players
from nba_api.stats.endpoints import shotchartdetail
import pandas as pd

3. Each NBA Player has an unique ID number — let’s see what the player directory looks like

# Storing Directory for All Players
player_dictionary = players.get_players()
# Returning first 5 players in player_dictionary
player_dictionary[0:5]

This is what should be returned — As you can see, our player dictionary should return the first 5 players in alphabetical order by last name with a unique id # and whether they are active/retired.

First 5 Players in our Player Dictionary

4. Now that all of the players and their IDs are available — let’s search for a specific player that we would like to get data for using their FULL NAME

For this example — I will use LeBron James

Using list comprehension, we can return the key value pairs from the player dictionary for LeBron James. Important Note — names are case sensitive (the “B” in LeBron is in upper case )

lebron = [player for player in player_dictionary if player['full_name'] == 'LeBron James']
lebron

This is the result for LeBron James — Player ID 2544

Result for LeBron James

5. Query ShotChartDetail for Lebron James

Explaining the paramaters passed in:

team_id = 0 — set to 0 as we are not querying any specific team

player_id = 2544 — the value that we obtained for LeBron James

context_measure_simple = ‘FGA’ — to specify that we would like data on both Field Goals Made (FGM) and Field Goals Attempted (FGA)

season_type_all_star = [‘Regular Season’, ‘Playoffs’] — restricting data to regular season and playoffs / excluding preseason and all-star game shot data

shotlog_lebron = shotchartdetail.ShotChartDetail(team_id = 0, player_id = '2544', 
context_measure_simple = 'FGA', 
season_type_all_star = ['Regular Season', 'Playoffs'])

6. Turn the shotlog into a dataframe

lebron_df = shotlog_lebron.get_data_frames()[0]
lebron_df.head(10)

This is our result when displaying the first 10 rows of the dataframe — it has many more features(columns) than what it shown below.

7. Export dataframe to CSV

LeBron = pd.read_csv('LeBron_James.csv')

Now the data is ready for you to explore further and mold into a shot chart!

Wrapping Up

Now that you have a good understanding of how to query for data using 1 player— you’re probably wondering how do I make the process easier if you wanted to pull data for multiple players in the future?

Below is a function which includes all the steps above in 1 block — all you have to do is provide the player’s full name (REMEMBER: Case Sensitive!)

def get_shot_data(player_full_name):
    player_dictionary = players.get_players()
     
    player_info = [player for player in player_dictionary if player['full_name'] == player_full_name][0]
    player_id = player_info['id']
    print(player_id)
    
    player_shotlog = shotchartdetail.ShotChartDetail(team_id = 0, player_id = player_id, 
                                                 context_measure_simple = 'FGA', 
                                                 season_type_all_star = ['Regular Season', 'Playoffs'])
    
    player_df = player_shotlog.get_data_frames()[0]
    player_df.to_csv(f'./Data/{player_full_name}.csv')
    return player_df.head()

For Example — to obtain ShotChartData for Kobe Bryant

get_shot_data('Kobe Bryant')