🎲 BGG Collection API

Extract and analyze BoardGameGeek collections with detailed game information

📋 Available Endpoints

GET
/api/v1/collection/{username}

Get a user's complete collection (owned and wishlist game IDs)

Query Parameters:

• debug=true - Enable debug output
• retries=3 - Number of retry attempts (1-10)
• details=true - Include detailed game information from BGG API
GET
/api/v1/collection/{username}/detailed NEW

Get a user's complete collection with full game details (name, rating, mechanics, etc.)

Query Parameters:

• debug=true - Enable debug output
• retries=3 - Number of retry attempts (1-10)
⚠️ Performance Note: This endpoint may take 2 - 4 seconds for large collections as it fetches detailed information from BGG's XML API.
GET
/api/v1/collection/{username}/stats

Get collection statistics

Query Parameters:

• detailed=true - Include detailed statistics (avg rating, weight, etc.)
• retries=3 - Number of retry attempts (1-10)
POST
/api/v1/games NEW

Get detailed information for specific games by their BGG IDs

Request Body: JSON array of game IDs

Query Parameters:

• debug=true - Enable debug output
• retries=3 - Number of retry attempts (1-10)
⚠️ Limits: Maximum 100 game IDs per request. Games are fetched from BGG's XML API.
GET
/api/v1/health

API health check endpoint

🚀 Example Usage

Note: All API requests require authentication. Include your API key in the Authorization header.

Basic Collection (IDs only):

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://localhost:8080/api/v1/collection/username"

{
  "success": true,
  "data": {
    "username": "username",
    "owned": [174430, 169786, 233398],
    "wishlist": [291457, 312484, 325718],
    "timestamp": "2025-01-15T10:30:45Z"
  }
}

Collection with Game Details:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://localhost:8080/api/v1/collection/username?details=true"
# OR
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://localhost:8080/api/v1/collection/username/detailed"

{
  "success": true,
  "data": {
    "username": "username",
    "owned_games": [
      {
        "id": 174430,
        "name": "Gloomhaven",
        "year_published": 2017,
        "min_players": 1,
        "max_players": 4,
        "playing_time": 120,
        "min_age": 14,
        "description": "Gloomhaven is a game of Euro-inspired...",
        "average_rating": 8.8,
        "weight": 3.86,
        "rank": 1,
        "categories": ["Adventure", "Fantasy"],
        "mechanics": ["Action Queue", "Campaign"],
        "designers": ["Isaac Childres"],
        "publishers": ["Cephalofair Games"]
      }
    ],
    "wishlist_games": [...],
    "timestamp": "2025-01-15T10:30:45Z"
  }
}

Detailed Statistics:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://localhost:8080/api/v1/collection/username/stats?detailed=true"

{
  "success": true,
  "data": {
    "username": "username",
    "owned_count": 245,
    "wishlist_count": 67,
    "total_count": 312,
    "average_rating": 7.8,
    "average_weight": 2.4,
    "average_play_time": 85,
    "oldest_game_year": 1995,
    "newest_game_year": 2024
  }
}

Get Game Details by IDs:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"game_ids": [174430, 169786, 233398]}' \
     "http://localhost:8080/api/v1/games"

{
  "success": true,
  "data": [
    {
      "id": 174430,
      "name": "Gloomhaven",
      "year_published": 2017,
      "min_players": 1,
      "max_players": 4,
      "playing_time": 120,
      "min_age": 14,
      "description": "Gloomhaven is a game of Euro-inspired tactical combat...",
      "average_rating": 8.8,
      "weight": 3.86,
      "rank": 1,
      "categories": ["Adventure", "Fantasy"],
      "mechanics": ["Action Queue", "Campaign"],
      "designers": ["Isaac Childres"],
      "publishers": ["Cephalofair Games"]
    },
    {
      "id": 169786,
      "name": "Scythe",
      "year_published": 2016,
      "min_players": 1,
      "max_players": 5,
      "playing_time": 115,
      "min_age": 14,
      "description": "Scythe gives players almost complete control...",
      "average_rating": 8.3,
      "weight": 3.89,
      "rank": 2,
      "categories": ["Economic", "Territory Building"],
      "mechanics": ["Area Majority / Influence", "Card Drafting"],
      "designers": ["Jamey Stegmaier"],
      "publishers": ["Stonemaier Games"]
    }
  ]
}

⚡ Performance Information

Response Times

  • Basic collection: <1 second
  • Detailed collection: <3 seconds
  • Statistics (basic): <1 second
  • Statistics (detailed): <1 second
  • Game details by IDs: <2 seconds

Rate Limiting

  • Automatic delays between requests
  • Respects BGG server limitations
  • Built-in retry logic with backoff
  • Graceful error handling

🔗 Data Sources