Skip to main content

A package to scrape and parse NBA, WNBA and G-League play-by-play data

Project description

Build Status PyPI version Downloads

A package to scrape and parse NBA, WNBA and G-League play-by-play data.


  • Adds lineup on floor for all events
  • Adds detailed data for each possession including start time, end time, score margin, how the previous possession ended, second chance time, offensive rebounds
  • Shots, rebounds and assists broken down by shot zone
  • Supports both and endpoints
  • Supports NBA, WNBA and G-League stats
  • All stats on are derived from these stats


requires Python >=3.6

pip install pbpstats

Setup data directory

There will be cases where events may be out of order or incorrect due to human error. If you want to be able to manually edit events you can set up the enivronment variable PBP_STATS_DATA_DIRECTORY and all request responses will be saved locally so edits can be made. If a file for a game exists locally it will be used instead of making the request to the NBA API. This directory is also where override files to fix periods starters and handle issues with parsing pbp that can't be fixed by editing pbb file are placed.


from pbpstats.stats_game_data import StatsGameData

game_data = StatsGameData('0041800406')
# to ignore rebound event order
# game_data.get_game_data(ignore_rebound_and_shot_order=True)
# to ignore issues parsing pbp that result in a team having back-to-back possessions
# game_data.get_game_data(ignore_back_to_back_possessions=True)

to get player stats for game:

player_stats = game_data.get_aggregated_possession_stats_for_entity_type('player')

to get team stats for game:

team_stats = game_data.get_aggregated_possession_stats_for_entity_type('team')

to get opponent stats for game:

opponent_stats = game_data.get_aggregated_possession_stats_for_entity_type('opponent')

to get lineup stats for game:

lineup_stats = game_data.get_aggregated_possession_stats_for_entity_type('lineup')

to get lineup opponent stats for game:

lineup_opponent_stats = game_data.get_aggregated_possession_stats_for_entity_type('lineupopponent')

to see data for specific possession


Note on Ids

Player and team Ids the same player and team ids used by Lineup ids are '-' separated player ids (with player ids sorted as strings).

Issues with raw play-by-play

See here for how to edit and fix common issues with play-by-play data.

Project details

Download files

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

Files for pbpstats, version 0.0.11
Filename, size File type Python version Upload date Hashes
Filename, size pbpstats-0.0.11-py3-none-any.whl (39.0 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size pbpstats-0.0.11.tar.gz (33.9 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page