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 Midnight-era roster demographics, item levels, faction and race trends, 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. Create a Blizzard developer application and obtain a CLIENT_ID and CLIENT_SECRET from the Battle.net developer portal.
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.

Curated Batch Import

To import data from the curated realm and guild list in import_top_guilds.sh:

bash import_top_guilds.sh

The batch list includes a mix of verified US progression guilds and larger community-heavy guilds.

If you want a clean refresh of the local dataset before re-importing, delete the existing database first:

rm characters.duckdb
bash 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: View level distribution for the current Midnight level cap of 90 and compare item level against achievement points.
• Filtering: Filter by Guild, Class, and current-cap characters.
• Interactive Drilldowns: Click class, faction, and race charts to filter the rest of the dashboard.
• Theme: A refreshed Midnight-inspired dashboard layout with improved mobile behavior.

Docker

Build and run the container:

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