Skip to main content

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

Project description

Downloads

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

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

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_!

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.0.3.tar.gz (44.0 kB view hashes)

Uploaded Source

Built Distribution

py_ball-1.0.3-py3-none-any.whl (63.0 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page