Skip to content

README.md

Latest commit

 

History

History
127 lines (84 loc) · 4 KB

README.md

File metadata and controls

127 lines (84 loc) · 4 KB

GitHub Contributors Heatmap

Embeddable SVG widget that visualizes the geographic distribution of your repository's contributors. Shows all-time contributor data on a world map with country-level heatmap coloring.

Variants

Map Light

Map Light

Map + List Light

Map + List Light

Map Dark

Map Dark

Map + List Dark

Map + List Dark

Examples generated for the sws2apps/organized-app repository.

Features

  • All-time contributor stats - Aggregates location data from all contributors
  • World map heatmap - Visual intensity based on contributor count per country
  • Country leaderboard - Optional sidebar showing top 10 countries
  • Auto-caching - 24-hour cache to respect GitHub API rate limits
  • SVG output - Crisp rendering at any size, works in GitHub READMEs

Usage

Add this to your README.md:

Map Light

![Contributors Heatmap](https://github-contribution-heatmap.vercel.app/api/heatmap?repo=OWNER/REPO&variant=map&theme=light)

Map + List Light

![Contributors Heatmap](https://github-contribution-heatmap.vercel.app/api/heatmap?repo=OWNER/REPO&variant=list&theme=light)

Map Dark

![Contributors Heatmap Dark](https://github-contribution-heatmap.vercel.app/api/heatmap?repo=OWNER/REPO&variant=map&theme=dark)

Map + List Dark

![Contributors Heatmap Dark](https://github-contribution-heatmap.vercel.app/api/heatmap?repo=OWNER/REPO&variant=list&theme=dark)
Parameter Type Default Description
repo string Yes GitHub repository (owner/name)
variant string list list (with leaderboard) or map (map only)
theme string light light or dark

Self-Hosting

Requirements

  • Python 3.9+
  • GitHub Personal Access Token (for API rate limits)

Deploy to Vercel

  1. Fork this repository
  2. Import to Vercel
  3. Add environment variable: GITHUB_TOKEN = your token
  4. Deploy

Local Development

git clone https://github.com/ux-git/github-contribution-heatmap.git
cd github-contribution-heatmap

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

export GITHUB_TOKEN=your_token_here
python api/main.py

Server runs at http://localhost:5002

API Reference

GET /api/heatmap
Parameter Type Required Description
repo string Yes GitHub repository (owner/name)
variant string No list or map (default: list)
theme string No light or dark (default: light)
refresh string No Set to 1 to bypass cache

How It Works

  1. Fetches all contributors via GitHub API
  2. Resolves each contributor's location to a country code
  3. Aggregates counts per country
  4. Renders SVG with proportional color intensity
  5. Caches results for 24 hours

Limitations

  • Only works with public repositories
  • Contributor locations are self-reported and optional
  • Location resolution uses fuzzy matching (may have edge cases)

Credits