DOCSEARCHbyAlgolia
Submit Docs

basketball_reference_web_scraper

repository·v4·Indexed 20 days ago

https://github.com/jaebradley/basketball_reference_web_scraper

A Python-based web scraper and client (version 4.22.1) designed to programmatically extract basketball statistics from Basketball-Reference.com. It provides functionality to retrieve league standings, player and team box scores, season totals, advanced statistics, team rosters, and play-by-play data. The library includes specialized Enums for teams and positions, as well as custom exception handling for invalid seasons, dates, and player/team combinations.

Tokens
7.8K
Snippets
40
Records
50
Agent score
68%

What's inside basketball_reference_web_scraper

  2. Configure API output formats and file writing

    v4

    By default, API methods return Python objects (such as a list of dictionaries). You can customize the output using the following optional arguments:

    • output_type: Use OutputType.JSON or OutputType.CSV to change the return format.
    • output_file_path: A string specifying the file path where the output should be written.
    • output_write_option: Use OutputWriteOption to define how the file is handled (e.g., OutputWriteOption.WRITE, OutputWriteOption.APPEND).
    • json_options: Options for JSON serialization.

    Important Constraints

    • CSV Requirement: If you set output_type to OutputType.CSV, you must provide an output_file_path.
    • JSON Flexibility: OutputType.JSON can be returned without specifying a file path.
    • Default Write Mode: If you provide an output_file_path but do not specify an output_write_option, the default is OutputWriteOption.WRITE.

  8. Run and organize tests

    v4

    Tests are split into two categories:

    • Unit tests: Located in the tests/unit directory.
    • Integration tests: Located in the tests/integration directory.

    Note that for extensive integration tests (such as those for API methods), tests are grouped into separate files even if they share an implementation file. For example, API method integration tests are found under the client directory even if they are implemented within client.py.

    Warning: Integration tests may occasionally encounter rate-limiting errors during execution.

  9. Get play-by-play data

    v4

    Retrieve play-by-play data for a specific game. Because of the URL pattern used by Basketball Reference, you must provide the home_team (using the Team enum), year, month, and day.

    Supports Python data structures, JSON, and CSV.

    from basketball_reference_web_scraper import client
from basketball_reference_web_scraper.data import OutputType, Team

client.play_by_play(
    home_team=Team.BOSTON_CELTICS, 
    year=2018, month=10, day=16, 
    output_type=OutputType.JSON, 
    output_file_path="./2018_10_06_BOS_PBP.json"
)

  10. Get regular season player shooting statistics

    v4

    Retrieve shooting statistics for all players in a season.

    Note: This method currently only returns Python data structures (a list of dictionaries). It does not support exporting to JSON or CSV at this time.

    from basketball_reference_web_scraper import client

stats = client.players_regular_season_shooting_statistics(season_end_year=2026)
# Returns a list of dictionaries containing fields like 'slug', 'name', 'position', etc.

  11. Get all current player contracts using a processor

    v4

    Retrieve current player contract data. Unlike other methods, contracts() does not return a list of dictionaries. Instead, it uses a streaming approach to be memory efficient.

    You must provide a contract_processor (a Callable) that defines how to handle each Contract object as it is processed.

    Returns Contract model objects from basketball_reference_web_scraper.contracts.data.models.

    from basketball_reference_web_scraper import client

contract_data = []
client.contracts(contract_processor=lambda contract: contract_data.append(contract))

# Each 'contract' in the list is a Contract object containing:
# - player (Player model)
# - team (Team enum)
# - salaries_by_season_start_year (dict)
# - remaining_guaranteed_salary (Salary model)

  12. Get player season totals (Basic and Advanced)

    v4

    Retrieve season-long statistics for players.

    • players_season_totals: Returns basic statistics.
    • players_advanced_season_totals: Returns advanced statistics.

    Both methods support Python data structures, JSON, and CSV output formats.

    from basketball_reference_web_scraper import client
from basketball_reference_web_scraper.data import OutputType

# Basic stats
client.players_season_totals(season_end_year=2018, output_type=OutputType.JSON)

# Advanced stats
client.players_advanced_season_totals(season_end_year=2018, output_type=OutputType.CSV)