🏆 GitHub Commit Badge API

A powerful, customizable API that generates beautiful SVG badges displaying GitHub commit activity with advanced theming, animations, and visual enhancements.

🔗 Interactive Documentation & Badge Builder: Try it out!

✨ Features

📊 Multiple Time Periods - Week, month, quarter, half-year, year
🎨 9 Beautiful Themes - Dark, gradient, neon, and more
🌈 10 Custom Colors - Red, green, blue, purple, and more
🎭 4 Badge Styles - Flat, flat-square, plastic, for-the-badge
⚡ 3 Animation Types - Pulse, glow, slide effects
🚀 8 Icons - Fire, rocket, trophy, and more emojis
📈 Mini Sparklines - Embedded commit trend charts
⚡ Smart Caching - 6-hour cache for optimal performance
🛡️ Error Resilience - Graceful fallback and error handling

🎨 Badge Builder

Create the perfect badge with our interactive builder:

Our Badge Builder lets you:

Preview different themes and styles in real-time
Customize all parameters with a user-friendly interface
Copy the generated URL with a single click
See live previews of your badge

🚀 Quick Start

Basic Usage

https://github-commit-badge-api.vercel.app/commits?account=USERNAME

With Custom Styling

https://github-commit-badge-api.vercel.app/commits?account=USERNAME&theme=dark&icon=fire&animated=pulse

📋 API Reference

Base URL

https://github-commit-badge-api.vercel.app/

Endpoint

GET /commits

Parameters

Parameter	Type	Default	Description
`account`	string	required	GitHub username
`period`	string	`month`	Time period: `week`, `month`, `quarter`, `half`, `year` (half = last 6 months)
`theme`	string	`default`	Badge theme (see themes below)
`color`	string	-	Custom color (see colors below)
`style`	string	`flat`	Badge style (see styles below)
`animated`	string	-	Animation type: `pulse`, `glow`, `slide`
`icon`	string	-	Icon to display (see icons below)
`sparkline`	boolean	`false`	Show mini trend chart (`true`/`false`)
`border`	boolean	`false`	Add border to badge (`true`/`false`)

🎨 Themes

Available Themes

Theme	Preview	Description
`default`		Classic blue and gray
`dark`		GitHub dark mode inspired
`github-dark`		Official GitHub dark colors
`dracula`		Popular Dracula theme
`monokai`		Monokai syntax theme
`gradient`		Beautiful gradient backgrounds
`ocean`		Ocean blue theme
`sunset`		Warm sunset colors
`neon`		Neon green cyberpunk

🌈 Colors

Override any theme's value color with custom colors:

Color	Preview	Hex
`red`		#e53e3e
`green`		#38a169
`blue`		#3182ce
`yellow`		#d69e2e
`purple`		#805ad5
`pink`		#d53f8c
`orange`		#dd6b20
`teal`		#319795
`cyan`		#0bc5ea
`gray`		#718096

🎭 Badge Styles

Style	Preview	Description
`flat`		Clean, flat design (default)
`flat-square`		Sharp, square corners
`plastic`		3D plastic look with shadows
`for-the-badge`		Large, bold uppercase style

⚡ Animations

Add life to your badges with CSS animations:

Animation	Preview	Description
`pulse`		Gentle pulsing effect
`glow`		Glowing shadow effect
`slide`		Subtle sliding animation

🚀 Icons

Add personality with emoji icons:

Icon	Emoji	Usage
`fire`	🔥	`?icon=fire`
`star`	⭐	`?icon=star`
`rocket`	🚀	`?icon=rocket`
`code`	💻	`?icon=code`
`chart`	📈	`?icon=chart`
`commit`	📝	`?icon=commit`
`calendar`	📅	`?icon=calendar`
`trophy`	🏆	`?icon=trophy`

📈 Sparklines

Show commit trends with mini charts embedded in your badges:

?sparkline=true

Sparklines display the last 7 days of commit activity as a small line chart within the badge.

🔧 Usage Examples

Basic Examples

<!-- Simple daily commits -->
![Daily Commits](https://github-commit-badge-api.vercel.app/commits?account=octocat)

<!-- Weekly commits -->
![Weekly Commits](https://github-commit-badge-api.vercel.app/commits?account=octocat&period=week)

<!-- Yearly commits -->
![Yearly Commits](https://github-commit-badge-api.vercel.app/commits?account=octocat&period=year)

Themed Examples

<!-- Dark theme with fire icon -->
![Commits](https://github-commit-badge-api.vercel.app/commits?account=octocat&theme=dark&icon=fire)

<!-- Neon theme with pulse animation -->
![Commits](https://github-commit-badge-api.vercel.app/commits?account=octocat&theme=neon&animated=pulse)

<!-- Gradient with sparkline -->
![Commits](https://github-commit-badge-api.vercel.app/commits?account=octocat&theme=gradient&sparkline=true)

Advanced Examples

<!-- For-the-badge style with trophy -->
![Commits](https://github-commit-badge-api.vercel.app/commits?account=octocat&style=for-the-badge&icon=trophy&color=purple)

<!-- Complete customization -->
![Commits](https://github-commit-badge-api.vercel.app/commits?account=octocat&theme=dracula&animated=glow&sparkline=true&icon=rocket&period=quarter)

HTML Usage

<img src="https://github-commit-badge-api.vercel.app/commits?account=octocat&theme=dark&animated=pulse" 
     alt="Daily Commits" 
     title="Average daily commits">

Complete Dashboard

Create a comprehensive activity dashboard:

# 📊 My GitHub Activity

| Period | Badge |
|--------|-------|
| Weekly | ![Weekly](https://github-commit-badge-api.vercel.app//commits?account=YOUR_USERNAME&period=week&theme=dark&icon=calendar) |
| Monthly | ![Monthly](https://github-commit-badge-api.vercel.app//commits?account=YOUR_USERNAME&period=month&theme=gradient&icon=chart) |
| Quarterly | ![Quarterly](https://github-commit-badge-api.vercel.app//commits?account=YOUR_USERNAME&period=quarter&theme=ocean&icon=rocket) |
| Half Yearly | ![Half Yearly](https://github-commit-badge-api.vercel.app//commits?account=YOUR_USERNAME&period=half&theme=purple&icon=calendar) |
| Yearly | ![Yearly](https://github-commit-badge-api.vercel.app//commits?account=YOUR_USERNAME&period=year&theme=sunset&icon=trophy) |

## 🔥 Trending Activity
![Sparkline](https://github-commit-badge-api.vercel.app//commits?account=YOUR_USERNAME&theme=neon&sparkline=true&animated=glow&style=for-the-badge)

💡 Remember: Replace YOUR_USERNAME with your actual GitHub username in all examples!

📊 Understanding Commit Periods

Our API provides several time periods for tracking commit activity:

Weekly: Last 7 days of activity
Monthly: Last 30 days of activity
Quarterly: Last 90 days of activity
Half Yearly: Last 180 days of activity
Yearly: Last 365 days of activity

Each period shows the average commits per day, giving you a clear picture of your coding habits over different timeframes.

🚀 Deployment

Deploy to Vercel

Clone the repository
Set up environment variables:
```
GITHUB_TOKEN=your_github_token
```
Deploy to Vercel:
```
vercel --prod
```

Environment Variables

Variable	Description	Required
`GITHUB_TOKEN`	GitHub Personal Access Token	Yes
`PORT`	Server port (default: 3000)	No

GitHub Token Setup

Go to GitHub Settings > Developer settings > Personal access tokens
Generate a new token with read:user and public_repo scopes
Add it to your Vercel environment variables

⚡ Performance

Smart Caching: 6-hour cache TTL reduces API calls
Browser Caching: 6-hour browser cache for optimal loading
Error Resilience: Serves stale cache during API failures
Optimized SVG: Lightweight, scalable vector graphics

🔒 Rate Limits

Respects GitHub API rate limits (5000 requests/hour for authenticated requests)
Intelligent caching reduces API usage
Graceful handling of rate limit exceeded scenarios

🐛 Error Handling

The API handles various error scenarios gracefully:

User not found: Shows "user not found" error badge
API errors: Shows "api error" badge
Server errors: Shows "server error" badge
Invalid parameters: Falls back to defaults

Error badges inherit your theme and styling preferences.

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

GitHub GraphQL API for commit data
Shields.io for badge design inspiration
Vercel for hosting platform

💡 Feature Requests

Have ideas for new features? Open an issue with the enhancement label!

Possible future features:

More themes and color schemes
Additional chart types
Streak tracking
Repository-specific badges
Team/organization badges

🌟 Star this repo if you find it useful!

Made with ❤️ for the GitHub community

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
api		api
config		config
utils		utils
views		views
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
vercel.json		vercel.json

Prithvi-raptee/github-commit-badge-api

Folders and files

Latest commit

History

Repository files navigation