WoW Guild Character Data Fetcher

This project fetches World of Warcraft character data for all members of a specified guild using Blizzard's Battle.net API. It stores the data in a DuckDB database and provides a Dash-based analytics dashboard to visualize roster demographics, item levels, and progression.

Prerequisites

• Python 3.13+
• uv (package manager)
• An active Battle.net API key (CLIENT_ID and CLIENT_SECRET)

Setup

1. Clone the repository.
2. Navigate to the project directory and sync the environment:

uv sync

3. Obtain the CLIENT_ID and CLIENT_SECRET for the Battle.net API by following these instructions.
4. Create a .env file in the project root directory with the following content:

CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret

Replace your_client_id and your_client_secret with the actual values obtained in step 3.

Importing Data

Single Guild

To fetch character information for a specific realm and guild, run the import.py script:

uv run python import.py <realm> <guild>

Replace <realm> and <guild> with the desired realm and guild names. This will store the fetched data in characters.duckdb.

Top Guilds Batch Import

To import data from a curated list of top US PvE and PvP guilds:

./import_top_guilds.sh

Running the Dashboard

Start the analytics dashboard with:

uv run app.py

Open your browser and navigate to http://127.0.0.1:8050.

Features

• Roster Analytics: View class, spec, race, and faction breakdowns.
• Progression Tracking: Level distribution (max level 80) and Item Level vs. Achievement Points scatter plot.
• Filtering: Filter by Guild, Class, and Max Level (80).
• Theme: Dark "World of Warcraft" inspired UI.

Docker

Build and run the container:

docker build -t wow-fetcher .
docker run -p 8000:8000 --env-file .env wow-fetcher