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.
Examples generated for the sws2apps/organized-app repository.
- 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
Add this to your README.md:
| 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 |
- Python 3.9+
- GitHub Personal Access Token (for API rate limits)
- Fork this repository
- Import to Vercel
- Add environment variable:
GITHUB_TOKEN= your token - Deploy
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.pyServer runs at http://localhost:5002
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 |
- Fetches all contributors via GitHub API
- Resolves each contributor's location to a country code
- Aggregates counts per country
- Renders SVG with proportional color intensity
- Caches results for 24 hours
- Only works with public repositories
- Contributor locations are self-reported and optional
- Location resolution uses fuzzy matching (may have edge cases)
- Current map: amCharts Mercator SVG, CC BY 4.0, modified. Attribution is included in every generated image.
- Prepared geometry is copied unchanged from
ux-git/contributors-map-widgetat c2314d6. That repository contains the original asset, preparation script and geometry tests. - The retained legacy
sirlisko-world-map.svgis from sirLisko/world-map-country-shapes, based on SimpleMaps, MIT by Pareto Software, LLC. It is no longer rendered.
python tests/test_location_resolution.py
python -m unittest discover -s tests -p 'test_rendering.py'Pushing main triggers the connected Vercel deployment. Verify the production response contains data-map-version="mercator-v2"; a successful push alone does not prove deployment. The prior server release is 6a729b6e2a59cd97781ad6ed635c6e6c0aaaa4b3; rollback can be made with a revert commit.