py_ball

Python API wrapper for stats.nba.com with a focus on NBA and WNBA applications

Introduction

The motivation for this stems from nba_py by seemethere and nbastatsR by abresler. The work towards a Python API wrapper in nba_py is a great start, but the documentation of the stats.nba.com API is lacking. nbastatsR is an extremely valuable resource for the R community, and this work hopes to extend the breadth and depth of that package. In my research, I have also come across the recent effort of nba_api by swar. This looks similar to nba_py and I am hoping to collaborate.

Goals

If successful, py_ball should accomplish the following:

• By working with the community, improve the quality of documentation for stats.nba.com.
• Further enable the dissemination of basketball statistics to increase the understanding of the sport and encourage the practice of basketball analytics.
• Produce introductory analyses leveraging NBA and WNBA data to reduce the barrier of entry to basketball analytics through demonstration.
• Focus on the WNBA in an effort to stress inclusivity and contribute to women's basketball analytics.

Documentation

While nba_api improves greatly upon the documentation of the stats.nba.com API in nba_py, py_ball strives to take documentation further through the following:

• Fully documented code, including function, class, and script docstrings.
• Extend endpoint and parameter documentation to include feature definitions.

Current Documentation

Classes:

The functionality of the classes within the package are documented in both the docstrings and this site. The endpoints, parameters, and tables are documented in the Wiki (linked below):

• BoxScore
• Draft
• Image
• LeaderBoard
• League
• LeagueDash
• LeagueHustle
• PlayByPlay
• Player
• Salaries (using Hoopshype)
• ScoreBoard
• Shots
• Team
• WinProbability

Development

1. Initially map stats.nba.com API and fully document code.
2. Refactor code to generate a more consistent structure across classes.
3. Document endpoints and parameters with definitions. (See Wiki here)
4. Research other basketball-related APIs to map.
5. Write unit tests for the package.
6. Begin introductory basketball analytics analyses.
   • Franchise History (here!)
   • Draft Combine Player Sheet (here!)
   • Live NBA/WNBA scoreboard (here!)
   • Shot Probability Model (here!)
   • Location Data Exploration (here!)
   • Assist Networks (here!)
   • Win Probability Model (here!)

Installation

The package is built for Python 3 and leverages the packages in the requirements.txt file. py_ball can be installed via pip (more info here):

pip install py_ball

Usage

The stats.nba.com API requires a request header for all API calls. A good discussion on this, including steps to obtain a proper request header, can be found here. With a request header in HEADER, the example below demonstrates usage of the package to pull franchise history for the WNBA:

from py_ball import league, image

league_id = '10' #WNBA
franchises = league.League(headers=HEADERS,
                           endpoint='franchisehistory',
                           league_id=league_id)

Each class, with the exception of the Headshot and Logo classes, has a data attribute. This is a dictionary containing table names as keys and a list of dictionaries of table data as values. The Headshot and Logo classes have an image attribute that is a PNG object.

Contact

Follow along for updates or reach out on Twitter @py_ball_!