Isometric Contributions API

Generate beautiful isometric contribution graphs with themes, caching and customization

Endpoint

GET /api/graph

Query Parameters

Parameter	Type	Required	Default	Description
`username`	string	Required	-	GitHub username
`year` / `y`	number\|string	Optional	none (365 days)	Year to fetch contributions for (e.g., `2025`) or `none` for 365-day rolling window ending today. Defaults to 365-day history (supports `year` or `y`)
`width`	number	Optional	1000	Image width in pixels
`height`	number	Optional	600	Image height in pixels
`stats`	boolean	Optional	false	Include statistics overlay (use `stats=true`)
`credit`	boolean	Optional	false	Show username credit (use `credit=true`)
`theme`	string	Optional	github	Visual theme: `github`, `dark`, `light`, `neon`, `minimal`, `ocean`

URL Builder [Hide] Click to collapse

Build your custom graph URL with live preview:

Username *

Theme

Year

Width (px)

Height (px)

Stats Credit

Format: URL Markdown HTML

Enter a username to see preview

Theme Gallery

Preview different themes with the same data:

Theme	Preview	URL
GitHub		`/api/graph?username=spectrewolf8&theme=github`
Dark		`/api/graph?username=spectrewolf8&theme=dark`
Light		`/api/graph?username=spectrewolf8&theme=light`
Neon		`/api/graph?username=spectrewolf8&theme=neon`
Minimal		`/api/graph?username=spectrewolf8&theme=minimal`
Ocean		`/api/graph?username=spectrewolf8&theme=ocean`
(Default) 365-Day Rolling Window		`/api/graph?username=spectrewolf8&year=none`

Examples

Basic usage (365-day rolling window):

/api/graph?username=spectrewolf8

By default, shows the last 365 days of contributions ending today

With specific year:

/api/graph?username=spectrewolf8&year=2025

Explicit 365-day mode:

/api/graph?username=spectrewolf8&year=none

With stats:

/api/graph?username=spectrewolf8&stats=true

Custom dimensions:

/api/graph?username=spectrewolf8&width=1920&height=1080

With theme:

/api/graph?username=spectrewolf8&theme=dark&stats=true

Full customization:

/api/graph?username=spectrewolf8&year=2025&width=1200&height=700&stats=true&credit=true&theme=neon

Caching

Images are cached per username and parameters combination for 24 hours. Multiple requests with the same parameters will be served from cache instantly. Check the X-Cache header: HIT for cached, MISS for newly generated.

Response Headers

Content-Type: image/png
Cache-Control: public, max-age=86400 (24 hours)
X-Cache: HIT | MISS (cache status)

Error Responses

Errors return JSON with an error message:

{
  "error": "Error message here"
}

Try It

Try different themes and configurations:

API Usage Statistics

Usage statistics for the current month:

Total Requests

New Users

Cache Hit Rate

Source

Explore the project or report issues on GitHub: github.com/Spectrewolf8/isometric-contributions