beatsaber-playlist-tool/docs/SimpleBeatLeaderAPI.md

# SimpleBeatLeaderAPI Python Wrapper

This simple 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

```python
from helpers.SimpleBeatLeaderAPI import SimpleBeatLeaderAPI

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

# Fetch player scores
player_id = '76561199407393962'
scores = api.get_player_scores(player_id)
scores.keys()
scores['data'][0]

# Get full song data
songs = api.get_player_songs(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:

```python
# Set cache expiry (in days)
api = SimpleBeatLeaderAPI(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:

```python
# 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.