BoardGameGeek Data Extractor

A production-grade Python library for extracting, transforming, and persisting data from the BoardGameGeek XML API2.

Features

• 🎯 Simple Synchronous API - Easy-to-use functions for scripts and notebooks
• ⚡ Async Support - High-performance async client for advanced use cases
• 📊 Data Persistence - Save to JSON and CSV formats
• 🔄 Data Transformation - Convert Pydantic models to dicts and DataFrames
• 🎮 Comprehensive Coverage - Search, games, collections, plays, users, and families
• 🛡️ Robust - Built-in rate limiting, retry logic, and error handling
• 🔑 Secure - API token authentication
• 📝 Well-Documented - Extensive guides, API reference, and examples

Documentation

📚 User Guide - Installation, configuration, and usage

📖 API Reference - Complete API documentation

💡 Examples - Real-world usage examples

Quick Start

Installation

pip install -e .
# or with uv
uv add .

Configuration

Set your BGG API token (required):

# Create a .env file
echo "BGG_API_TOKEN=your_token_here" > .env

CLI Usage

# Search for a game
bgg-extractor search --query "Wingspan" --output results.json

# Get game details
bgg-extractor things --ids 174430 13 --stats --output games.json

# Get user collection
bgg-extractor collection --username eekspider --stats --output collection.csv

Python Library

from bgg_extractor import search, get_things, save_json

# Search for a game
results = search("Catan")
print(f"Found {len(results.items)} items")

# Get game details
game_ids = [item.id for item in results.items[:5]]
games = get_things(game_ids, stats=True)

# Save to file
save_json(games.items, "catan_games.json")

Development

• Run tests: pytest
• Lint: ruff check src
• Typecheck: mypy src

Contributing

See CONTRIBUTING.md