GitHub Top Languages API

Deployable GitHub language chart generator — embeddable SVGs for READMEs and websites.

More Examples

16 Languages

Dark Theme

Light Theme

Default Theme

Table of Contents

• Features
• Usage
• Parameters
• Deployment & Configuration
  • Prerequisites
  • Configure .env
  • Local Development
  • Deploying
• License

Features

• Generates a chart of your top programming languages (up to 16).
• Customizable: Control the title, size, theme, and number of languages displayed.
  • Theming: Supports default, light, and dark themes.
  • Custom Colours: Set background (bg), text (text), and individual language colours (c1-c16) via query parameters.
• Dynamic Layout: The legend automatically shifts to a two-column layout when displaying 9 or more languages.
• Automatically fetches all public GitHub repositories, and private repositories with a token.
• Ignores forks and optionally specific repositories (IGNORED_REPOS).
• Uses hourly caching to reduce API calls and improve performance.

Usage

Markdown (For READMEs)

![Top Languages](https://your-deployment-url.vercel.app/api/languages)

HTML (For Websites)

<img 
  src="https://your-deployment-url.vercel.app/api/languages" 
  alt="My Top Programming Languages" 
/>

Customization Options

API-Only Parameters

Parameter	Type	Description	Default	Example
test	Boolean	Uses sample data instead of fetching from GitHub API.	false	?test=true
error	String	Forces an error SVG with the given message. For testing only.	—	?error=test

Query Parameters

Full parameter reference lives in the lib README.

Example URL

To get 10 languages, a dark theme, and a custom title:

![My Custom Chart](https://your-deployment-url.vercel.app/api/languages?count=10&theme=dark&title=My%20Top%2010%20Languages)

Deployment & Configuration

Prerequisites

• Node.js 22+
• TypeScript 5.0+
• (Optional) Vercel or other Node.js hosting

Installation

git clone https://github.com/gh-top-languages/api.git
cd api
npm install

Configuration

Copy .env.example to .env, and update the variables.

• GITHUB_USERNAMES: GitHub usernames to fetch repositories from. Accepts a single value (masonlet), comma-separated (masonlet,secondlet), or a JSON array with optional per-user tokens (["masonlet", {"name": "other", "token": "github_pat_..."}]).
• GITHUB_ORGS: GitHub organization names to fetch repositories from. Accepts a single value (gh-top-languages), comma-separated (gh-top-languages,starweb-libs), or a JSON array with optional per-org tokens (["gh-top-languages", {"name": "starweb-libs", "token": "github_pat_..."}])
• IGNORED_REPOS: Optional comma-separated repo names to exclude from the chart.

Running Locally

vercel dev
# Your endpoint will be available at http://localhost:3000/api/languages (or your configured port)

Deployment

The default endpoint is /api/languages

Error Responses

All errors return HTTP 200 with an error SVG so they render in GitHub README embeds.

Common error messages:

• GitHub API error: {status} {statusText} — GitHub API request failed
• No language data available — no public repositories found
• At least one of GITHUB_USERNAMES or GITHUB_ORGS must be set — missing environment configuration

License

MIT License - see LICENSE for details.