{"id":51294932,"url":"https://github.com/ameyac11/gitlytics","last_synced_at":"2026-06-30T14:00:33.381Z","repository":{"id":364534820,"uuid":"1268025917","full_name":"ameyac11/gitlytics","owner":"ameyac11","description":"📊 Beautiful GitHub traffic analytics dashboard and CLI tool to permanently track views, clones, referrers, and popular paths for all your repositories.","archived":false,"fork":false,"pushed_at":"2026-06-30T13:25:51.000Z","size":5485,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-06-30T14:00:12.483Z","etag":null,"topics":["analytics","cli","dashboard","github-api","github-traffic","gitlytics","pypi-package","python","stream"],"latest_commit_sha":null,"homepage":"https://gitlytics.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ameyac11.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-13T04:24:38.000Z","updated_at":"2026-06-30T13:24:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ameyac11/gitlytics","commit_stats":null,"previous_names":["ameyac11/github-traffic-viewer","ameyac11/github-traffic-monitor","ameyac11/gitlytics"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/ameyac11/gitlytics","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameyac11%2Fgitlytics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameyac11%2Fgitlytics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameyac11%2Fgitlytics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameyac11%2Fgitlytics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ameyac11","download_url":"https://codeload.github.com/ameyac11/gitlytics/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameyac11%2Fgitlytics/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34969682,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","cli","dashboard","github-api","github-traffic","gitlytics","pypi-package","python","stream"],"created_at":"2026-06-30T14:00:17.254Z","updated_at":"2026-06-30T14:00:33.367Z","avatar_url":"https://github.com/ameyac11.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://raw.githubusercontent.com/ameyac11/gitlytics/main/assets/logo.png\" alt=\"Gitlytics Logo\" width=\"150\" /\u003e\n\n# Gitlytics\n### GitHub Traffic Analytics \u0026 Automation \n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/Python-3.9%2B-blue)](https://www.python.org/)\n[![PyPI](https://img.shields.io/pypi/v/gitlytics?color=blue)](https://pypi.org/project/gitlytics/)\n[![React](https://img.shields.io/badge/UI-React-61dafb?logo=react)](https://react.dev/)\n[![FastAPI](https://img.shields.io/badge/Backend-FastAPI-009688?logo=fastapi)](https://fastapi.tiangolo.com/)\n[![Automation](https://img.shields.io/badge/Data%20Backup-Automation%20Tool-purple?logo=github-actions)](https://github.com/ameyac11/gitlytics-github-traffic-automation)\n[![Homepage](https://img.shields.io/badge/Homepage-gitlytics.dev-success)](https://gitlytics.dev)\n[![Live](https://img.shields.io/badge/Live%20Demo-dashboard.gitlytics.dev-success)](https://dashboard.gitlytics.dev)\n[![Docs](https://img.shields.io/badge/Docs-docs.gitlytics.dev-success)](https://docs.gitlytics.dev)\n\n\u003cbr/\u003ePlease consider giving this project a ⭐ if you find it helpful! \u003cbr/\u003e\n\n**Beautiful GitHub traffic analytics for all your repositories — public and private.** \u003cbr/\u003e Track views, clones, referrers, and popular paths indefinitely.\n\n✨ **[Try the live dashboard at dashboard.gitlytics.dev](https://dashboard.gitlytics.dev)** ✨  \n📚 **[Read the documentation at docs.gitlytics.dev](https://docs.gitlytics.dev)**\n\n\u003cbr/\u003e\n\n\u003e **🐍 Native Python API**\n\u003e \n\u003e You can import Gitlytics natively into your own Python applications to fetch live repository data like views, clones, stars, and referrers. Build custom integrations, run custom cron workflows, or serve the dashboard programmatically on your own cloud servers.\n\u003e \n\u003e 📚 **[Read the Full API Documentation](https://docs.gitlytics.dev)**\n\n\u003c/div\u003e\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/ameyac11/gitlytics/main/assets/gitlytics_thumbnail_1.png\" width=\"100%\" /\u003e\n\u003c/div\u003e\n\n---\n\n## 📌 Table of Contents\n\n- [🔗 The Gitlytics Ecosystem](#-the-gitlytics-ecosystem)\n- [🚨 The 14-Day Catch (And How We Fix It)](#-the-14-day-catch-and-how-we-fix-it)\n- [🛠️ Installation](#installation)\n  - [🔑 Generating a GitHub Personal Access Token](#generating-a-github-personal-access-token)\n- [⌨️ The 4 Core CLI Commands](#the-4-core-cli-commands)\n  - [1️⃣ `gitlytics fetch` (Live Terminal Data)](#1-gitlytics-fetch-live-terminal-data)\n  - [2️⃣ `gitlytics sync` (Background Database Cron)](#2-gitlytics-sync-background-database-cron)\n  - [3️⃣ `gitlytics dashboard` (React Web UI)](#3-gitlytics-dashboard-react-web-ui)\n  - [4️⃣ `gitlytics stars` (Stargazer History)](#4-gitlytics-stars-stargazer-history)\n- [🐍 Native Python API](#native-python-api)\n  - [1️⃣ `gitlytics.fetch_traffic()`](#1-gitlyticsfetch_traffic)\n  - [2️⃣ `gitlytics.sync()`](#2-gitlyticssync)\n  - [3️⃣ `gitlytics.serve_dashboard()`](#3-gitlyticsserve_dashboard)\n  - [4️⃣ `gitlytics.fetch_star_history()`](#4-gitlyticsfetch_star_history)\n- [📊 CSV Output Columns](#csv-output-columns)\n- [🌟 Show Your Support](#show-your-support)\n- [📄 License](#license)\n\n---\n\n## 🔗 The Gitlytics Ecosystem\n\nThe full Gitlytics ecosystem spans across a few repositories. If you are looking for the live web dashboard or the automation cron job, check out the links below:\n\n- 📊 **[Gitlytics Live Dashboard](https://dashboard.gitlytics.dev)**: The production web interface to visualize repository traffic analytics, trends, and historical charts.\n- ⚙️ **[Gitlytics Automation](https://github.com/ameyac11/gitlytics-github-traffic-automation)**: The GitHub Action companion tool that automates fetching and saving to defeat GitHub's 14-day traffic limit.\n\n---\n\n## 🚨 The 14-Day Catch (And How We Fix It)\n\n\u003e **⚠️ Did you know?** GitHub normally **only saves your repository traffic data for 14 days**. After two weeks, your valuable views and clones data is permanently deleted.\n\n**Don't lose your data!** We built a companion automation tool that runs silently in the background every 13 days using GitHub Actions to fetch and save your data permanently. \n\n👉 **[Set up GitHub Traffic Automation here](https://github.com/ameyac11/gitlytics-github-traffic-automation)** (It takes literally 2 minutes to set up!)\n\nOnce you have your automated CSV data saved from that tool, you can seamlessly plug it right into `gitlytics` to visualize beautiful, long-term historical charts stretching back months or years!\n\n---\n\n## 🛠️ Installation\n\nInstall via PyPI:\n\n```bash\n# Basic CLI and Python Module installation\npip install gitlytics\n\n# Full installation (includes React Dashboard dependencies)\npip install \"gitlytics[dashboard]\"\n```\n\n### 🔑 Generating a GitHub Personal Access Token\nTo use the tools, you'll need a GitHub token.\n1. Go to **[GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)](https://github.com/settings/tokens)**\n2. Click **Generate new token (classic)**\n3. Select the **`repo`** scope *(required to read traffic data for private repositories)*\n4. Click **Generate token** and copy it!\n\n---\n\n## ⌨️ The 4 Core CLI Commands\n\nGitlytics is powered by 4 massive command-line tools. You can run them anywhere in your terminal.\n\n### 1️⃣ `gitlytics fetch` (Live Terminal Data)\nFetch your live 14-day traffic and print a beautiful ASCII table directly in your console.\n```bash\ngitlytics fetch --token ghp_your_token_here --print-table\n\n# Fetch specific metrics only (e.g., views and clones)\ngitlytics fetch --token ghp_your_token_here --print-table --metrics views clones\n```\n\n### 2️⃣ `gitlytics sync` (Background Database Cron)\nTired of losing data? Use `sync` to permanently append today's traffic to a CSV database. You can even run it as a background cron job (perfect for Raspberry Pi or Linux/Cloud servers)!\n```bash\n# Sync once\ngitlytics sync --token ghp_your_token --data-dir ./data\n\n# Sync specific metrics only\ngitlytics sync --token ghp_your_token --data-dir ./data --metrics views clones\n\n# Run permanently in the background as a cron job (runs at 11:00 PM every day)\ngitlytics sync --token ghp_your_token --data-dir ./data --schedule-cron \"0 23 * * *\"\n```\n\n### 3️⃣ `gitlytics dashboard` (React Web UI)\nLaunch the beautiful React + FastAPI web interface. \n```bash\ngitlytics dashboard\n```\n\u003e **📺 Headless TV Mode:** Want to display the dashboard on an office TV monitor? Pass the historical database and token directly so the UI auto-loads without requiring a manual browser login!\n\u003e ```bash\n\u003e gitlytics dashboard --token \"ghp_xxx\" --data-dir \"./data\"\n\u003e ```\n\n### 4️⃣ `gitlytics stars` (Stargazer History)\nFetch the historical cumulative stargazer growth trajectory for a repository. \n```bash\n# Fetch and print star history table\ngitlytics stars owner/repo --token ghp_your_token\n```\n\n---\n\n## 🐍 Native Python API\n\nYou can import Gitlytics natively into your own Python applications to build custom integrations, run custom cron workflows, or serve the dashboard programmatically on your own cloud servers.\n\n📚 **[Read the Full API Documentation](https://docs.gitlytics.dev)**\n\n### 1️⃣ `gitlytics.fetch_traffic()`\nFetches the last 14 days of traffic data (views, clones, referrers, paths) for one or more repositories.\n\n```python\nimport gitlytics\n\n# Fetch traffic for all repositories accessible by the token\ndf = gitlytics.fetch_traffic(\n    token=\"ghp_your_token\",\n    return_format=\"dataframe\"  # Options: \"dataframe\" (Pandas), \"timeseries\" (chart-ready dict), or \"summary\" (per-repo totals dict)\n)\n\n# Fetch traffic for a single specific repository and print the table to stdout\ngitlytics.fetch_traffic(\n    token=\"ghp_your_token\",\n    repo_name=\"username/my-repo\",\n    print_table=True\n)\n\n# Save output directly to a file (CSV or JSON depending on file extension)\ngitlytics.fetch_traffic(\n    token=\"ghp_your_token\",\n    return_format=\"dataframe\",\n    save_file=\"./data/traffic.csv\"\n)\n```\n\n#### ⚙️ Parameters:\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| `token` | `str` | *Required* | GitHub Personal Access Token with `repo` scope enabled. |\n| `repo_name` | `str` | `None` | Specific repository name (e.g. `\"user/repo\"`). If `None`, fetches all repositories. |\n| `print_table` | `bool` | `False` | If `True`, formats and prints a detailed ASCII traffic table to the console. |\n| `return_format` | `str` | `\"dataframe\"` | The format of returned data: `\"dataframe\"` (Pandas DataFrame), `\"timeseries\"` (chart-ready nested dict), or `\"summary\"` (per-repo totals dict). |\n| `save_file` | `str` | `None` | Optional. File path where the fetched data will be saved (CSV or JSON). |\n| `metrics` | `list` | `None` | Optional. List of metrics to fetch (e.g., `[\"views\", \"clones\"]`). |\n\n---\n\n### 2️⃣ `gitlytics.sync()`\nFetches the live traffic data and appends it to a persistent CSV database. Handles merging overlaps and duplicates. Can be scheduled with an internal cron scheduler for cloud deployments.\n\n```python\nimport gitlytics\n\n# Standard run: Syncs current snapshots to the CSV database and exports UI JSON\ngitlytics.sync(\n    token=\"ghp_your_token\",\n    data_dir=\"./data\",\n    export_json=\"./data/export.json\",\n    export_public_only=True  # Security Firewall: Exclude private repos from the public-facing export.json\n)\n\n# Scheduled Cloud Worker: Run infinitely using standard cron schedule syntax\ngitlytics.sync(\n    token=\"ghp_your_token\",\n    data_dir=\"./data\",\n    schedule_cron=\"0 23 * * *\",  # Runs everyday at 11:00 PM UTC\n    export_json=\"./data/export.json\"\n)\n```\n\n#### ⚙️ Parameters:\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| `token` | `str` | *Required* | GitHub Personal Access Token. |\n| `repo_name` | `str` or `list` | `None` | Specific repository name(s) to sync. If `None`, syncs all repositories. |\n| `data_dir` | `str` | `\"./data\"` | Directory where CSV files are saved. |\n| `output_mode` | `str` | `\"monthly\"` | File grouping frequency: `\"monthly\"` (creates `traffic_YYYY-MM.csv`) or `\"yearly\"` (creates `traffic_YYYY.csv`). |\n| `schedule_cron` | `str` | `None` | Optional cron expression (e.g., `\"*/15 * * * *\"`). If set, runs an infinite scheduler loop. |\n| `export_json` | `str` | `None` | Optional. Path to compile and export a consolidated history JSON for the frontend. |\n| `export_public_only` | `bool` | `True` | Security firewall: if `True`, strips private repository data from the compiled `export_json`. |\n| `metrics` | `list` | `None` | Optional. List of metrics to sync (e.g., `[\"views\", \"clones\"]`). |\n\n---\n\n### 3️⃣ `gitlytics.serve_dashboard()`\nLaunches the FastAPI backend and hosts the embedded React SPA dashboard.\n\n```python\nimport gitlytics\n\n# Host the dashboard programmatically on a custom host/port\ngitlytics.serve_dashboard(\n    host=\"0.0.0.0\",\n    port=8080,\n    token=\"ghp_your_token\",     # Pre-authenticates the dashboard session\n    data_dir=\"./data\"           # Folder containing the historical databases\n)\n```\n\n#### ⚙️ Parameters:\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| `host` | `str` | `\"127.0.0.1\"` | Host IP to bind the FastAPI server. Use `\"0.0.0.0\"` to listen on all interfaces. |\n| `port` | `int` | `8000` | Port to run the web server on. |\n| `token` | `str` | `None` | Optional. Pre-authenticates the dashboard session to bypass the login screen. |\n| `data_dir` | `str` | `None` | Optional. Path to the folder containing your synced CSV or JSON databases. |\n\n---\n\n### 4️⃣ `gitlytics.fetch_star_history()`\nFetches a list of cumulative star counts per date for a given repository. \n\n```python\nimport gitlytics\n\n# Fetch stargazer history timeline\npoints = gitlytics.fetch_star_history(\n    owner=\"ameyac11\",\n    repo=\"gitlytics\",\n    token=\"ghp_your_token\"  # Optional for public repos, recommended to avoid rate limits\n)\n```\n\n#### ⚙️ Parameters:\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| `owner` | `str` | *Required* | Owner of the repository. |\n| `repo` | `str` | *Required* | Repository name. |\n| `token` | `str` | `None` | Optional GitHub Personal Access Token. |\n\n---\n\n\n## 📊 CSV Output Columns\n\nWhen you sync data, the local CSV databases track 23 detailed metrics by default. If you customize the metrics using the `--metrics` CLI flag or `metrics` Python parameter, the CSV columns will dynamically include only the columns corresponding to your selection (along with the default `date`, `repository`, and `is_private` identification columns).\n\n| Column | Type | Description |\n|---|---|---|\n| `date` | `str` | ISO date (`YYYY-MM-DD`) for this day's traffic snapshot. |\n| `repository` | `str` | Full GitHub repository name (`owner/repo`). |\n| `is_private` | `bool` | `True` if repository is private, `False` otherwise. |\n| `views` | `int` | Total page views on this day. |\n| `unique_visitors` | `int` | Unique visitors on this day. |\n| `clones` | `int` | Total git clone operations on this day. |\n| `unique_cloners` | `int` | Unique clone clients on this day. |\n| `stars` | `int` | Current total star count snapshot. |\n| `forks` | `int` | Current total fork count snapshot. |\n| `language` | `str` | Primary programming language of the repository. |\n| `topics` | `str` | JSON array containing repository tags/topics. |\n| `watchers_count` | `int` | Total watchers of the repository. |\n| `pushed_at` | `str` | Last push ISO timestamp. |\n| `created_at` | `str` | Repository creation ISO timestamp. |\n| `open_issues_count` | `int` | Total number of open issues. |\n| `top_referrer` | `str` | Top external traffic referral source (14-day rolling window). |\n| `top_referrer_views` | `int` | Views sent by the top referrer. |\n| `top_referrer_uniques` | `int` | Uniques sent by the top referrer. |\n| `_raw_referrers` | `str` | Raw JSON array of all referral sources. |\n| `top_path` | `str` | Most visited repository file path (14-day rolling window). |\n| `top_path_views` | `int` | Views for the top path. |\n| `top_path_uniques` | `int` | Uniques for the top path. |\n| `_raw_paths` | `str` | Raw JSON array of all popular paths. |\n\n---\n\n## 🌟 Show Your Support\n\nIf you find this project useful, please consider giving it a ⭐ on [GitHub](https://github.com/ameyac11/gitlytics)! It helps more people discover the tool.\n\n## 📄 License\nLicensed under the [Apache License 2.0](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fameyac11%2Fgitlytics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fameyac11%2Fgitlytics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fameyac11%2Fgitlytics/lists"}