GitRank Live 🚀

Real-time GitHub ranking badge generator - Generate dynamic SVG badges that show your GitHub ranking based on stars, forks, followers, or commits!

✨ Features

• 🏆 Real-time GitHub ranking - Compare your stats against millions of developers
• 📊 Multiple metrics - Stars, forks, followers, and commits
• 🎨 Customizable badges - 4 different styles (flat, flat-square, for-the-badge, plastic)
• 🌍 Country-based ranking - Optional regional comparisons
• ⚡ Lightning fast - Responds in under 500ms with smart caching
• 🔒 Rate-limited - Respects GitHub API limits with intelligent caching
• 🚀 Zero-config deployment - Ready for Vercel, Railway, or Docker

🎯 Quick Start

1. Using the Badge (Hosted)

![GitRank Live](https://gitrank.zehrasec.com/api/badge?user=octocat&metric=stars)
![GitHub Followers Rank](https://gitrank.zehrasec.com/api/badge?user=octocat&metric=followers&style=for-the-badge)

2. Run Locally

# Clone the repository
git clone https://github.com/yashab-cyber/gitrank.git
cd gitrank

# Install dependencies  
npm install

# Set up environment variables
cp .env.example .env
# Edit .env and add your GitHub token (optional but recommended)

# Start the server
npm run dev

3. Docker

# Build and run with Docker
docker build -t gitrank .
docker run -p 3000:3000 --env-file .env gitrank

# Or use Docker Compose
docker-compose up

📖 API Reference

Badge Endpoint

GET /api/badge?user={username}&metric={metric}&style={style}&country={country}

Parameters:

• user (required): GitHub username
• metric (optional): stars | forks | followers | commits (default: stars)
• style (optional): flat | flat-square | for-the-badge | plastic (default: flat)
• country (optional): Country name for regional ranking

Response: SVG badge with caching headers

User Stats Endpoint

GET /api/stats/{username}

Returns detailed user statistics in JSON format.

Ranking Info Endpoint

GET /api/ranking-info

Returns information about ranking algorithms and percentiles.

🏆 Ranking System

GitRank Live calculates percentiles based on these benchmarks:

Metric	Top 1%	Top 5%	Top 10%	Top 25%	Top 50%
Stars	10,000+	2,000+	500+	100+	20+
Forks	2,000+	500+	100+	25+	5+
Followers	5,000+	1,000+	300+	50+	10+
Commits	2,000+	500+	200+	50+	20+

🎨 Badge Styles

Flat (default)

![Flat Style](https://gitrank.zehrasec.com/api/badge?user=octocat&metric=stars&style=flat)

Flat Square

![Flat Square](https://gitrank.zehrasec.com/api/badge?user=octocat&metric=stars&style=flat-square)

For The Badge

![For The Badge](https://gitrank.zehrasec.com/api/badge?user=octocat&metric=stars&style=for-the-badge)

Plastic

![Plastic](https://gitrank.zehrasec.com/api/badge?user=octocat&metric=stars&style=plastic)

🌍 Regional Rankings

Add country-specific rankings by including the country parameter:

![US Ranking](https://gitrank.zehrasec.com/api/badge?user=octocat&metric=followers&country=united+states)
![India Ranking](https://gitrank.zehrasec.com/api/badge?user=octocat&metric=stars&country=india)

Supported countries: United States, China, India, Germany, United Kingdom, Canada, France, Japan, Brazil, Russia, and more.

⚡ Performance & Caching

• Smart caching: User data cached for 12 hours
• Rate limiting: 1000 requests per hour per IP
• GitHub API optimization: Efficient pagination and data fetching
• CDN ready: Perfect for global deployment

🚀 Deployment

Vercel (Recommended)

1. Fork this repository
2. Connect to Vercel
3. Add environment variables:
   • GITHUB_TOKEN: Your GitHub personal access token (optional)
4. Deploy!

Railway

Render

1. Connect your GitHub repository
2. Set build command: npm install
3. Set start command: npm start
4. Add environment variables

Docker

docker build -t gitrank .
docker run -p 3000:3000 -e GITHUB_TOKEN=your_token gitrank

🔧 Environment Variables

# Required
PORT=3000                    # Server port
NODE_ENV=production         # Environment

# Optional
GITHUB_TOKEN=your_token     # GitHub personal access token (recommended)
CACHE_TTL=43200            # Cache duration in seconds (12 hours)
RATE_LIMIT_WINDOW=3600000  # Rate limit window in ms (1 hour)
RATE_LIMIT_MAX=1000        # Max requests per window

🧪 Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test file
npm test tests/api.test.js

📊 Usage Examples

Personal Profile README

## 🏆 My GitHub Stats

![Stars Ranking](https://gitrank.zehrasec.com/api/badge?user=yourusername&metric=stars&style=for-the-badge)
![Followers Ranking](https://gitrank.zehrasec.com/api/badge?user=yourusername&metric=followers&style=for-the-badge)
![Commits Ranking](https://gitrank.zehrasec.com/api/badge?user=yourusername&metric=commits&style=for-the-badge)

Repository Badges

![Maintainer Stars](https://gitrank.zehrasec.com/api/badge?user=maintainer&metric=stars)
![Maintainer Followers](https://gitrank.zehrasec.com/api/badge?user=maintainer&metric=followers)

Organization Showcases

## Team Rankings
![CEO GitHub Rank](https://gitrank.zehrasec.com/api/badge?user=ceo&metric=followers&style=flat-square)
![CTO GitHub Rank](https://gitrank.zehrasec.com/api/badge?user=cto&metric=stars&style=flat-square)

🔄 API Rate Limits

GitRank Live handles GitHub API rate limits intelligently:

• Without token: 60 requests/hour per IP (GitHub limit)
• With token: 5,000 requests/hour (GitHub limit)
• Caching: 12-hour cache reduces API calls by 95%
• Smart batching: Efficient data fetching strategies

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

📝 Changelog

v1.0.0 (2024-12-27)

• ✨ Initial release
• 🏆 GitHub ranking system
• 📊 Four metrics: stars, forks, followers, commits
• 🎨 Four badge styles
• 🌍 Country-based rankings
• ⚡ Performance optimizations
• 🚀 Multi-platform deployment support

📄 License

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

🙏 Acknowledgments

• GitHub for providing the excellent API
• The open-source community for inspiration
• All contributors and users of GitRank Live

👨‍💻 Developer

GitRank Live is created and maintained by Yashab Alam, Founder & CEO of ZehraSec.

🌐 Connect with Yashab Alam

• 💻 GitHub: @yashab-cyber
• 📸 Instagram: @yashab.alam
• 💼 LinkedIn: Yashab Alam

🏢 ZehraSec - Official Company

• 🌐 Website: www.zehrasec.com
• 📸 Instagram: @_zehrasec
• 📘 Facebook: ZehraSec Official
• 🐦 X (Twitter): @zehrasec
• 💼 LinkedIn: ZehraSec Company
• 💬 WhatsApp: Business Channel

💰 Support Development

Love GitRank Live? Your support helps maintain and improve this project!

📝 View Donation Options - Multiple payment methods available including crypto and PayPal

📞 Support

• 🐛 Bug reports: GitHub Issues
• 💡 Feature requests: GitHub Discussions
• 📧 Email: support@gitrank.live
• 💬 Twitter: @GitRankLive

---

🌟 Star this repository if you found it helpful!

Made with ❤️ by Yashab Alam (@ZehraSec)

💰 Support Development | 🌐 ZehraSec Website