Package Exports
- github-contribution-api
Readme
GitHub Contribution API (Node.js)
Fetch and parse GitHub contribution graphs directly in Node.js, without running a separate HTTP service.
- ✅ Node-first API
- ✅ Supports multiple years
- ✅ Array or nested formats
- ✅ Built-in LRU cache
- ✅ Deterministic cache keys
Installation
npm install github-contribution-apiUsage
Basic
import { getContribution } from 'github-contribution-api'
const graph = await getContribution('yukiakai')Defaults:
year:'last'format:'array'cache:true
Specify year(s)
await getContribution('yukiakai', {
year: 2024,
})await getContribution('yukiakai', {
year: [2022, 2023, 2024],
})await getContribution('yukiakai', {
year: 'all',
})Output formats
Array (default)
const graph = await getContribution('yukiakai', {
format: 'array',
}){
total: {
2024: 532,
lastYear: 489
},
contributions: [
{ date: '2024-01-01', count: 3, level: 2 },
{ date: '2024-01-02', count: 0, level: 0 },
...
]
}Nested
const graph = await getContribution('yukiakai', {
format: 'nested',
}){
total: {
2024: 532,
lastYear: 489
},
contributions: {
2024: {
1: {
1: { date: '2024-01-01', count: 3, level: 2 },
2: { date: '2024-01-02', count: 0, level: 0 }
}
}
}
}Nested structure:
[year][month][day] → Contribution
API
getContribution(username, options?)
getContribution(
username: string,
options?: getContributionOptions
): Promise<ContributionResponse | NestedContributionResponse>Options
interface getContributionOptions {
year?: 'all' | 'last' | number | number[]
format?: 'array' | 'nested'
cache?: boolean
}Caching
- Cache enabled by default
- TTL: 1 hour
Disable cache if needed:
await getContribution('yukiakai', {
cache: false,
})Limitations
- Relies on GitHub’s public contribution graph
- If GitHub changes its markup, parsing logic may need updates
- No authentication support (public profiles only)
Inspiration
This project was inspired by
github-contributions-api by grubersjoe
License
MIT © Yuki Akai