BeatLeaderAPI Python Wrapper

This Python class provides a convenient wrapper for interacting with the BeatLeader API, specifically for retrieving player scores and song data for the game Beat Saber.

Features

Fetch player scores and song data from the BeatLeader API
Local caching of API responses to reduce API calls and improve performance
Automatic pagination handling to retrieve all available data
Configurable cache expiration
Methods to retrieve both full and minimal song data

Usage

Basic Usage

from saberlist.beatleaderAPI import BeatLeaderAPI

# Initialize the API wrapper
api = BeatLeaderAPI(cache_expiry_days=1)

# Fetch player scores
player_id = '76561199407393962'
scores = api.get_player_scores(player_id)

# Get full song data
songs = api.get_player_songs(player_id)

# Get minimal song data
minimal_songs = api.get_player_songs_minimal(player_id)

Caching

The class uses a local cache to store API responses. By default, the cache is located at:

~/.cache/saberlist/ on Unix-like systems (if ~/.cache/ exists)
./.cache/ in the current working directory (as a fallback)

You can control cache behavior:

# Set cache expiry (in days)
api = BeatLeaderAPI(cache_expiry_days=7)

# Force a fresh API call (ignore cache)
fresh_scores = api.get_player_scores(player_id, use_cache=False)

# Clear cache for a specific player
api.clear_cache(player_id)

# Clear all cache
api.clear_cache()

# Get the current cache directory
cache_dir = api.get_cache_dir()

Pagination

The get_player_scores method automatically handles pagination to retrieve all available scores. You can control this behavior:

# Set a custom page size (default is 100)
scores = api.get_player_scores(player_id, page_size=50)

# Limit the number of pages fetched
scores = api.get_player_scores(player_id, max_pages=5)

Methods

get_player_scores(player_id, use_cache=True, page_size=100, max_pages=None): Retrieves all scores for a player.
get_player_songs(player_id, page=1, count=100, use_cache=True): Retrieves full song data for all unique songs a player has played.
get_player_songs_minimal(player_id, page=1, count=100, use_cache=True): Retrieves minimal song data (id, name, author, mapper, hash, bpm, duration) for all unique songs a player has played.
clear_cache(player_id=None): Clears the cache for a specific player or all cached data.
get_cache_dir(): Returns the path to the current cache directory.

2.4 KiB Raw Blame History