GitHub Contributions API v4

An API that returns the number of GitHub contributions by scraping a user's GitHub profile. This API is used by React GitHub Calendar (React component).

⚠️ Results are cached for one hour!

How to run

npm install
npm start

For development:

npm run dev

Usage

Send a GET request to the API in the following format:

https://github-contributions-api.jogruber.de/v4/GITHUB_USERNAME

And you will receive an object with complete history of that user's contributions (total per year and for each day):

{
  "total": {
    "2020": 492,
    ...
  },
  "contributions": [
    {
      "date": "2020-01-01",
      "count": 0,
      "level": 0
    },
    {
      "date": "2020-01-02",
      "count": 9,
      "level": 4
    },
    {
      "date": "2020-01-03",
      "count": 5,
      "level": 2
    },
    ...
  ]
}

You can return the results as an object keyed by year, month and day by using the format=nested query parameter:

https://github-contributions-api.jogruber.de/v4/GITHUB_USERNAME?format=nested

{
  "2020": {
    "1": {
      "1": {
        "date": "2020-01-01",
        "count": 9,
        "level": 4
      },
      "2": {
        "date": "2020-01-02",
        "count": 5,
        "level": 2
      },
      "3": {
        "date": "2020-01-03",
        "count": 0,
        "level": 0
      },
      ...
    },
   ...
  }
}

Query specific time frame

Use the y (year) query parameter to retrieve the data for a specific year, a set of years, the last year (GitHub's default view), or the data for all years (default when y parameter is omitted):

https://github-contributions-api.jogruber.de/v4/GITHUB_USERNAME?y=2020
https://github-contributions-api.jogruber.de/v4/GITHUB_USERNAME?y=2016&y=2017
https://github-contributions-api.jogruber.de/v4/GITHUB_USERNAME?y=last
https://github-contributions-api.jogruber.de/v4/GITHUB_USERNAME?y=all # default

{
  "total": {
    "2016": 249,
    "2017": 785
  },
  "contributions": [
    {
      "date": "2016-01-01",
      "count": 1,
      "level": 1
    },
    {
      "date": "2016-01-02",
      "count": 0,
      "level": 0
    },
    ...
  ]
}

Response interface

The responses are structured like this:

interface Contribution {
  date: string
  count: number
  level: 0 | 1 | 2 | 3 | 4
}

interface Response {
  total: {
    [year: number]: number
    [year: string]: number // 'lastYear'
  }
  contributions: Array<Contribution>
}

interface NestedResponse {
  total: {
    [year: number]: number
    [year: string]: number // 'lastYear;
  }
  contributions: {
    [year: number]: {
      [month: number]: {
        [day: number]: Contribution
      }
    }
  }
}