BoardGameGeek-Data-Extractor
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