Skip to main content

Python API wrapper for with a focus on NBA and WNBA applications

Project description



Python API wrapper for with a focus on NBA and WNBA applications


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 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.


If successful, py_ball should accomplish the following:

  • By working with the community, improve the quality of documentation for
  • 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.


While nba_api improves greatly upon the documentation of the 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


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):


  1. Initially map 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!)


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


The 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,

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.


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

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

py_ball-1.41.tar.gz (88.1 kB view hashes)

Uploaded source

Built Distribution

py_ball-1.41-py3-none-any.whl (106.4 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page