How to Get NBA Data Using the nba_api Python Module (Beginner)

Nba data collection
Nba nba_api

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:

Image Generated by Ethan Swan: https://github.com/eswan18

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.

About Ken Jee 11 Articles
Ken is one of the founders of Playing Numbers. He has worked in sports analytics for the last 5 years focusing primarily on golf and basketball. He founded playing numbers to help others learn about the field he loves.

12 Comments

  1. This was a great tutorial thanks! I am new to data science and python – When trying to run your gamelog code in Spyder I received a connection error below. Do you know what would cause this? Thanks – fan of the blog

    File “”, line 6, in
    player_info = commonplayerinfo.CommonPlayerInfo(player_id=’1629012′)

    File “C:\Users\frohlict\AppData\Local\Continuum\anaconda3\lib\site-packages\nba_api\stats\endpoints\commonplayerinfo.py”, line 17, in __init__
    ‘LeagueID’: league_id_nullable

    File “C:\Users\frohlict\AppData\Local\Continuum\anaconda3\lib\site-packages\nba_api\library\http.py”, line 101, in send_api_request
    response = requests.get(url=base_url, params=parameters, headers=headers, proxies=proxies)

    File “C:\Users\frohlict\AppData\Local\Continuum\anaconda3\lib\site-packages\requests\api.py”, line 72, in get
    return request(‘get’, url, params=params, **kwargs)

    File “C:\Users\frohlict\AppData\Local\Continuum\anaconda3\lib\site-packages\requests\api.py”, line 58, in request
    return session.request(method=method, url=url, **kwargs)

    File “C:\Users\frohlict\AppData\Local\Continuum\anaconda3\lib\site-packages\requests\sessions.py”, line 508, in request
    resp = self.send(prep, **send_kwargs)

    File “C:\Users\frohlict\AppData\Local\Continuum\anaconda3\lib\site-packages\requests\sessions.py”, line 618, in send
    r = adapter.send(request, **kwargs)

    File “C:\Users\frohlict\AppData\Local\Continuum\anaconda3\lib\site-packages\requests\adapters.py”, line 490, in send
    raise ConnectionError(err, request=request)

    ConnectionError: (‘Connection aborted.’, RemoteDisconnected(‘Remote end closed connection without response’,))

    Tyler

    • Hey Tyler – Thanks for watching the video / reading the article. The connection error suggests that there may be a problem with your internet. I would check that your internet connection is working well, and try again. I hope this helps!

  2. Hi,
    thanks a lot for your video is very helpful. I have to present analysis about what is the success keys of a player in the NBA maybe could you give any tip for use algoritmos of machine learning

    • I would usually recommend a multiple linear regression to start. I would have to know more about the problem before going further than that. Feel free to write in the forum about the nature of your work and myself/ others can give some feedback! Thanks again for watching the video!

  3. Hello, i am a programmer and a big fan of the sports and NBA, i want to do a web app for show stats and apply data science. I know basic python. yo can helpme with some advice, routemap to follow or idea of some project to do. I dont know yet about data science, i am beginning study. Can yo helpme. Thanks

  4. Hello, while trying to install nba_api I receive the following error:

    PackagesNotFoundError: The following packages are not available from current channels:

    – nba_api

    To search for alternate channels that may provide the conda package you’re
    looking for, navigate to

    https://anaconda.org

    and use the search bar at the top of the page.

  5. Hello, while trying to install nba_api I get the following error:

    PackagesNotFoundError: The following packages are not available from current channels:

    To search for alternate channels that may provide the conda package you’re
    looking for, navigate to

    https://anaconda.org

    and use the search bar at the top of the page.

  6. Hey there – I am looking to use the nba_api endpoints however when I run the code I get the following error,

    File “/Users/Chinmay/anaconda3/lib/python3.6/site-packages/requests/adapters.py”, line 123, in __init__
    super(HTTPAdapter, self).__init__()

    TypeError: super(type, obj): obj must be an instance or subtype of type

    Any idea what is going on? Love the videos!

  7. Ken…

    Really love your videos and repositories. Your work is outstanding…

    I love NBA as well, and I want to scrape NBA.com’s play type (https://stats.nba.com/players/playtype-post-up/). I scanned the list of endpoints in github, yet I did not see one for this particular stat. I am relatively new to Python / Anaconda, and am using sports (especially NBA) to learn how to code and scrape. Would I be able to manipulate any of the endpoints to point to the link above (If I am using the semantics correctly)? Any assistance/ advice would be greatly appreciated. Again, thanks for the massive amount of work you have put in.

    Jesse

  8. Hi,

    Great video. i’m big fan of nba too.
    tried to connect using api but ran into below error:

    timeout: The read operation timed out

    During handling of the above exception, another exception occurred:

    ReadTimeoutError Traceback (most recent call last)
    ReadTimeoutError: HTTPSConnectionPool(host=’stats.nba.com’, port=443): Read timed out. (read timeout=30)

    During handling of the above exception, another exception occurred:

    ReadTimeout Traceback (most recent call last)
    /usr/local/lib/python3.6/dist-packages/requests/adapters.py in send(self, request, stream, timeout, verify, cert, proxies)
    527 raise SSLError(e, request=request)
    528 elif isinstance(e, ReadTimeoutError):
    –> 529 raise ReadTimeout(e, request=request)
    530 else:
    531 raise

    ReadTimeout: HTTPSConnectionPool(host=’stats.nba.com’, port=443): Read timed out. (read timeout=30)

Leave a Reply