In this article, I will show you the basics of using the nba_api module in python. This is an extremely robust python module that allows you to directly access the NBA.com API. This package is well maintained by Swar Patel, and has good engagement and usage.

This is a huge package (hah) with many features, and this article should give you a basic understanding of how to use it and what is possible with it. After this tutorial, you should be able to install the nba_api module, get player stats, and get team stats. Much of the starter code is distilled from other sources, which I have included if you would like to learn more. The package is well documented, so after this, you should be able to explore its features on your own.

Getting Started (Installing nba_api)

We start by installing the nba_api so that it can be used with our version of python. I recommend using Anaconda (platform) for most of your data science needs.

To install the code open the anaconda prompt, command prompt (windows), or terminal (mac), and type:

pip install nba_api

You should see something that looks like this after pressing Enter:

After installing, open your favorite IDE (I use Spyder) and we can get started.

How the Package is Structured

In order to make use of this package, it helps to understand how it is structured. The full Table of Contents is located here.

The nba_api starts with static data on players and teams. Each player and Team has an id, and this is generally the best way to identify them when making our API calls later.

The package also has many different API endpoints that it can hit. We generally pass in features from the static data to the API endpoints as parameters. All of the endpoints can be seen here.

I recommend exploring the table of contents in detail after finishing this tutorial. I also recommend taking a look a few other starter notebooks that you can use for reference.

Getting Player & Team Ids

In order to make calls to the NBA.com API, we need to know what we are searching for. We have to find the proper ids of players and teams that we would like data on. To get these, we use the following code:

from nba_api.stats.static import players
player_dict = players.get_players()

# Use ternary operator or write function 
# Names are case sensitive
bron = [player for player in player_dict if player['full_name'] == 'LeBron James'][0]
bron_id = bron['id']

# find team Ids
from nba_api.stats.static import teams 
teams = teams.get_teams()
GSW = [x for x in teams if x['full_name'] == 'Golden State Warriors'][0]
GSW_id = GSW['id']

The code should give you the ids for both Lebron James and the Golden State Warriors. With this, we can now query data for this player and team.

Getting Game Data

First, we will attempt to get the game logs for Lebron. We will use the playergamelog API endpoint.

# First we import the endpoint
# We will be using pandas dataframes to manipulate the data
from nba_api.stats.endpoints import playergamelog
import pandas as pd 

#Call the API endpoint passing in lebron's ID & which season 
gamelog_bron = playergamelog.PlayerGameLog(player_id='2544', season = '2018')

#Converts gamelog object into a pandas dataframe
#can also convert to JSON or dictionary  
df_bron_games_2018 = gamelog_bron.get_data_frames()

# If you want all seasons, you must import the SeasonAll parameter 
from nba_api.stats.library.parameters import SeasonAll

gamelog_bron_all = playergamelog.PlayerGameLog(player_id='2544', season = SeasonAll.all)

df_bron_games_all = gamelog_bron_all.get_data_frames()

This should give you a basic dataframe with Lebron’s career game stats.

We can do something similar for team game stats as well. Below is the code for getting all of Golden State’s game data using the leaguegamefinder endpoint.

from nba_api.stats.endpoints import leaguegamefinder

#this time we convert it to a dataframe in the same line of code
GSW_games = leaguegamefinder.LeagueGameFinder(team_id_nullable=GSW_id).get_data_frames()[0]

Accessing Other Data

The two examples above should cover the basics of how to use this module. With a similar process, you can access a tremendous amount of other basketball data. The current list of all of the endpoints looks like this:

You can click on all of these endpoints in the Table of Contents to see what parameters they take.

Again, a special thanks to @swar, @eswan18, and @rsforbes for building the module and providing starter examples.