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-api

Usage

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