Badge Feature

tokei-api provides dynamic badges that you can add to your README or other documentation. These badges visually display code statistics.

Available Badges

  • Lines of Code: Total lines of code
  • Top Language: Most used programming language
  • Languages: Number of languages used
  • Code to Comment: Ratio of code to comments
Lines of Code Top Language Languages Code to Comment

How to Use Badges

tokei-api provides badges for both GitHub repositories and any other Git repository. You can add these badges to your README or other documentation.

For GitHub Repositories

To add badges for a GitHub repository, use the following markdown format:

[![Lines of Code](https://img.shields.io/endpoint?url=https%3A%2F%2Ftokei.kojix2.net%2Fbadge%2Fgithub%2Fowner%2Frepo%2Flines)](https://tokei.kojix2.net/github/owner/repo)

For example, badges for this project (tokei-api):

[![Lines of Code](https://img.shields.io/endpoint?url=https%3A%2F%2Ftokei.kojix2.net%2Fbadge%2Fgithub%2Fkojix2%2Ftokei-api%2Flines)](https://tokei.kojix2.net/github/kojix2/tokei-api)
[![Top Language](https://img.shields.io/endpoint?url=https%3A%2F%2Ftokei.kojix2.net%2Fbadge%2Fgithub%2Fkojix2%2Ftokei-api%2Flanguage)](https://tokei.kojix2.net/github/kojix2/tokei-api)
[![Languages](https://img.shields.io/endpoint?url=https%3A%2F%2Ftokei.kojix2.net%2Fbadge%2Fgithub%2Fkojix2%2Ftokei-api%2Flanguages)](https://tokei.kojix2.net/github/kojix2/tokei-api)
[![Code to Comment](https://img.shields.io/endpoint?url=https%3A%2F%2Ftokei.kojix2.net%2Fbadge%2Fgithub%2Fkojix2%2Ftokei-api%2Fratio)](https://tokei.kojix2.net/github/kojix2/tokei-api)

For Any Git Repository

For repositories hosted on other platforms (GitLab, Bitbucket, etc.), first analyze the repository using the form on the home page, then use the following markdown format:

[![Lines of Code](https://img.shields.io/endpoint?url=https%3A%2F%2Ftokei.kojix2.net%2Fapi%2Fbadge%2Flines%3Furl%3Dhttps%3A%2F%2Fexample.com%2Fuser%2Frepo.git)](https://example.com/user/repo)

Replace https://example.com/user/repo.git with your repository URL. You can use any of the badge types: lines, language, languages, or ratio.

Badge Types and Endpoints

Badge Type GitHub Endpoint Generic Endpoint Description
Lines of Code /badge/github/:owner/:repo/lines /api/badge/lines?url=... Total lines of code in the repository
Top Language /badge/github/:owner/:repo/language /api/badge/language?url=... Most used programming language
Languages Count /badge/github/:owner/:repo/languages /api/badge/languages?url=... Number of programming languages used
Code to Comment Ratio /badge/github/:owner/:repo/ratio /api/badge/ratio?url=... Ratio of code to comments
Note: These badges are dynamic and will automatically reflect the latest analysis of your repository. For efficiency, analysis results are cached for 24 hours. If you've made changes to your repository and want to update the badge data, you can run a new analysis after the cache period expires.

Integration with shields.io

tokei-api badges are compatible with shields.io endpoint format. This allows for consistent styling with other badges you might be using in your documentation.

The badge endpoints return JSON in the following format: 

{
  "schemaVersion": 1,
  "label": "Lines of Code",
  "message": "1.2k",
  "color": "blue"
}