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_apiYou 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.
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!
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!
I need to recovery all players comes from Europe and to know whom is successfully and whom is not. How to get this?
thanks!
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
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.
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.
Hi Bryce – I would recommmend usinng pip install nba_api rather than conda install. THat worked for me when I adjusted it. I hope this helps!
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!
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
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)
Yeah same error occcured to me also.When reffered other blogs the old endpoints of nba_api are blocked.Ken is it right?
What should we do…?
I cant use any endpoints I tried till now.
Ken,
Great article and super helpful. I’m currently picking up Sport Analytics as a hobby and am using your material to learn more about the subject.
Just curious if you know of a way to download all of the “boxScoreTraditionalV2” data points for an entire season and for every team into one data frame.
I know your demo walked us through how to download gamelogs for all seasons for a certain player with the “season all” functionality and am wondering if there’s correspondingly a “game all” functionality for the boxscore endpoint to get it for all players.
Thanks,
Codemaster2000