Skip to content

readme.md

Latest commit

 

History

History
269 lines (202 loc) · 4.71 KB

readme.md

File metadata and controls

269 lines (202 loc) · 4.71 KB

📊 GitHub Language Stats API

🚀 FastAPI + MongoDB Atlas + GitHub API

A production-ready backend API that analyzes GitHub repository languages, computes total usage, stores historical snapshots, and serves publicly accessible endpoints. Built with FastAPI, MongoDB Atlas, and deployed on Render.

🌟 Overview

This backend project:

  • Fetches all repositories of a GitHub user
  • Aggregates language usage across all repos
  • Computes bytes + percentage usage
  • Caches results for 24 hours using MongoDB
  • Stores full historical snapshots over time
  • Exposes clean API endpoints with Pydantic models
  • Runs asynchronously using FastAPI + httpx
  • Fully deployed online and globally accessible

Perfect for:

  • Developer dashboards
  • Portfolio projects
  • GitHub analytics tools
  • Resume enhancement
  • Learning full backend engineering

🧠 Tech Stack

Layer Technology
Backend Framework FastAPI
HTTP Client httpx (async)
Database MongoDB Atlas
Driver Motor (async)
Deployment Render
Config python-dotenv
Data Models Pydantic

🗂 Project Structure

github-stats/
│── app/
│   ├── main.py
│   ├── github_api.py
│   ├── stats_service.py
│   ├── database.py
│   ├── models.py
│── requirements.txt
│── .env
│── .gitignore
│── README.md

🌐 Live Demo

Frontend Coming Soon .....

🚀 Base URL

https://githubstats-gqcp.onrender.com/

📘 Swagger Docs

https://githubstats-gqcp.onrender.com/docs

Embed in Your README

<img src="https://githubstats-gqcp.onrender.com/card/stats?username=YOUR_GITHUB_USERNAME" />

Example:

<img src="https://githubstats-gqcp.onrender.com/card/stats?username=itsdevansh5" />

📡 API Documentation

1️⃣ GET /

Health check route

Returns API status.

Example:

{"message": "GitHub Stats API is running!"}

2️⃣ GET /stats/{username}

Fetches latest GitHub language statistics.

✨ Features:

  • Fetches repositories
  • Aggregates all language data
  • Computes percentages
  • Saves snapshot
  • Uses 24-hour caching

Example:

/stats/itsdevansh5

Response:

{
  "username": "itsdevansh5",
  "cached": false,
  "total_bytes": {
    "Python": 63697231,
    "C++": 224954,
    "HTML": 246905
  },
  "percentages": {
    "Python": 93.13,
    "C++": 0.33,
    "HTML": 0.36
  }
}

If cached:

{
  "cached": true,
  ...
}

3️⃣ GET /history/{username}

Returns all historical snapshots of the user.

Example:

{
  "username": "itsdevansh5",
  "history": [
    {
      "fetched_at": "2025-12-10T12:34:11",
      "total_bytes": { ... },
      "percentages": { ... }
    },
    {
      "fetched_at": "2025-12-11T12:34:11",
      "total_bytes": { ... },
      "percentages": { ... }
    }
  ]
}

3️⃣ GET /card

Generates a dynamic SVG GitHub stats card for a user.

Query Params:

  • username — GitHub username (required)

Example:

<img src="https://githubstats-gqcp.onrender.com/card?username=itsdevansh5" />
Screenshot (23)

🧮 How Percentages Are Calculated

GitHub returns byte counts:

Python → 63697231
C++    → 224954
HTML   → 246905

Percentage formula:

percent = (bytes_of_lang / sum(all_bytes)) × 100

Rounded to 2 decimals.

🔐 Environment Variables

Your .env should contain:

MONGO_URL="mongodb+srv://<user>:<password>@cluster.mongodb.net/?retryWrites=true&w=majority"
GITHUB_TOKEN="ghp_your_github_token_here"

⚠️ Never commit .env to GitHub.
Add this to .gitignore:

.env

🚀 Deployment (Render)

1️⃣ Push code to GitHub

2️⃣ Go to Render → New Web Service

3️⃣ Choose your repo

4️⃣ Set settings:

Build Command

pip install -r requirements.txt

Start Command

uvicorn app.main:app --host=0.0.0.0 --port=$PORT

5️⃣ Add Environment Variables:

MONGO_URL=your_url_here
GITHUB_TOKEN=your_token_here
PYTHON_VERSION=3.11

6️⃣ Deploy 🎉

📝 To-Do / Future Improvements

  • Add user authentication
  • Add rate-limiting per IP
  • Add frontend dashboard
  • Add export to CSV / JSON
  • Add charts (Pie, Bar, Trends)
  • Add caching with Redis
  • Make it a full SaaS product

🎉 Author

Made with ❤️ by Devansh
A backend + cloud enthusiast building real-world projects.

⭐ Enjoy using the GitHub Stats API!