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 + List (Default)

Map + List (Dark)

Map Only

Map Only (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:

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

Variants

Variant	Parameter	Description
Map + List	variant=list (default)	Map with top 10 countries sidebar
Map only	variant=map	World map with heatmap coloring
Dark theme	theme=dark	Dark mode variant (works with both)

<!-- Map with country list (Default) -->
![Contributors Heatmap](https://github-contribution-heatmap.vercel.app/api/heatmap?repo=OWNER/REPO)

<!-- Dark mode -->
![Contributors Heatmap Dark](https://github-contribution-heatmap.vercel.app/api/heatmap?repo=OWNER/REPO&theme=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

• Map data source: sirLisko/world-map-country-shapes (based on SimpleMaps.com)
• Original SVG licensed under MIT by Pareto Software, LLC.