GitHub Contribution Card API
Generate a PNG contribution graph for a GitHub user with custom theme, time range (months or weeks),
and width.
Optional caption font via font (bundled files in contrib/fonts/).
With chart-data=1 or json=1 alone (JSON implies chart data), the endpoint returns plain
text (space-separated counts per UTC day) or application/json with json=1, including
counts, UTC range timestamps, and GraphQL summary fields.
The CGI endpoint is /contrib/generate and responds with an image or text.
Endpoint
GET /contrib/generate?username=octocat&months=12&theme=light&font=helvetica&width=1200&caption_year=1&caption_month=1&caption_day=0&download=0Week-based range (overrides months):
GET /contrib/generate?username=octocat&weeks=16&theme=light&width=1200&download=0Plain contribution counts per day (UTC date range; values match GitHub’s contribution calendar, not git commits only):
GET /contrib/generate?username=octocat&weeks=16&chart-data=1Chart JSON only (json=1 implies chart data; chart-data=1 not required):
GET /contrib/generate?username=octocat&weeks=16&json=1Query string options
| Parameter | Type | Required | Notes |
|---|---|---|---|
username |
string | Yes | GitHub username. Letters, numbers, and hyphens only. |
months |
integer | No | How many months to include (calendar months ending today). Defaults to 12. Ignored if
weeks is set.
|
weeks |
integer | No | How many week columns to show (Sunday-based weeks aligned with GitHub, ending now). If present, takes
precedence over months. Clamped to 1..104. |
chart-data |
0 or 1 |
No |
When 1 (or true/yes/on), response is
text/plain unless json=1 is also set (then JSON). One value per calendar day from
the selected range start through the range end (UTC), in order. Omit if you only need JSON
(json=1 implies chart data).
Same months/weeks range as the PNG. Theme, font, width, captions, header, footer,
header/footer alignment, and image options are ignored.
Alias: chart_data.
|
json |
0 or 1 |
No |
Return application/json instead of plain text. Implies chart data (same as
chart-data=1); you do not need both parameters. Body includes values (int array),
startDate and endDate (integer Unix timestamps in milliseconds
for 00:00:00 UTC on the first and last calendar day in values), rangeFrom /
rangeTo (GitHub API ISO bounds), dayCount, range
(weeks or months echo), and github (contribution totals from
GraphQL). Alias: json_output.
|
theme |
string | No | Theme name. Defaults to light. |
font |
string | No |
Caption label font preset: helvetica (default), dejavu, liberation,
arial, inter, noto, georgia, system.
Bundled .ttf files in contrib/fonts/ are tried first; see
fonts/README.txt.
|
width |
integer | No | Output width in pixels. Clamped by API to 100..4000. |
download |
0 or 1 |
No | 0 = inline image, 1 = attachment download. |
caption_year |
0 or 1 |
No | Draw year labels above the graph when a new year appears. |
caption_month |
0 or 1 |
No | Draw month labels above the graph when a new month starts. |
caption_day |
0 or 1 |
No | Draw weekday labels on the left side of the graph. |
header |
string | No |
Optional URL-encoded text above the chart (same font as caption labels). Placed with ~30px gap below the
header block and above month/year captions (or above the heatmap if captions are off). Long lines wrap to
image width; use %0A for newlines. Max 400 characters after decode.
|
footer |
string | No |
Optional URL-encoded text below the heatmap (~30px gap under the grid), same font and wrap rules as
header.
|
headerAlign |
string | No |
Horizontal alignment for header lines only (does not affect year/month captions):
l or left, c or center (default), r or
right. Alias: header_align.
|
footerAlign |
string | No |
Same as headerAlign for footer lines. Alias: footer_align.
|
transparent |
0 or 1 |
No | Defaults to 0 (opaque theme background). Set 1 for a fully transparent PNG
canvas; squares and captions stay opaque. |
padding |
integer | No |
Margin around the chart in pixels (applied on all sides before scaling). If omitted, default is
20.
Clamped to 0..400.
|
corner_radius |
number | No |
Corner roundness 0–100: percent of the maximum radius (half the square edge), so
100 draws circles.
Default 36 matches the previous GitHub-like rounding.
|
Available themes: light, dark, classic, earth,
pastel,
neon, sunset, ocean, forest, amber,
dracula,
grayscale, github-dark (alias of dark), github-light (alias of light).
API tester
Generated request URL:
Enter a GitHub username to load the preview.