GitHub GraphQL Contributions APIで貢献カレンダーを取得

GitHub GraphQL Contributions APIで取得できるデータ

GitHub GraphQL コントリビューションカレンダー APIは、画像ではなく日付と件数を使いたいときに便利です。ユーザーのloginを指定し、期間を決めてcontributionsCollectionを取得し、contributionCalendarを選びます。レスポンスには合計値と、日ごとの貢献データを含む週の配列が入ります。

日別レコードではdateとcontributionCountが基本です。colorとweekdayはカレンダー表示の再現に使え、totalContributionsは指定期間の合計を表します。これはプロフィールの貢献アクティビティであり、リポジトリのコミット履歴でも完全な監査ログでもありません。非公開の活動がすべてアプリに見える保証もありません。

GitHubのリファレンスによると、非公開および内部リポジトリの貢献を含めるには、任意のread:user権限が必要です。製品に必要な場合だけ要求し、それ以外ではトークンの権限を小さく保ちます。

GraphQL APIへのリクエストはGitHubのエンドポイントに送るPOSTで、認証が必要です。トークンはサーバーまたはローカルの環境変数に置き、必要なアクセスだけを許可してください。ブラウザーのJavaScript、公開リポジトリ、共有するクエリ例に秘密情報を入れてはいけません。

GitHub GraphQL contributions APIのリクエストを作る

GitHub GraphQLのエンドポイントはhttps://api.github.com/graphqlです。AuthorizationにBearerトークンを付けたPOSTを送り、JSON本文にqueryとvariablesを入れます。クエリ文字列と変数の値を分けると、内容をレビューしやすく、別ユーザーや期間でも再利用できます。

例ではリポジトリのコミットを列挙せず、プロフィールのカレンダーを選びます。カレンダー表示に必要な合計、週、各週の日別フィールドだけを指定しています。年間合計だけが必要なら、totalContributionsのみを取得し、カレンダーのネストしたフィールドは省略できます。

GraphQLはJSONレスポンスの外枠を返します。データがあると決めつける前に、HTTPステータスと最上位のerrors配列を両方確認してください。データとGraphQLエラーが同時に返る場合もあるため、開発時はエラーメッセージと対象フィールドへのパスを分けて記録します。

クエリと変数

query UserContributionCalendar($login: String!, $from: DateTime!, $to: DateTime!) {
  user(login: $login) {
    contributionsCollection(from: $from, to: $to) {
      contributionCalendar {
        totalContributions
        weeks {
          contributionDays {
            date
            contributionCount
            color
            weekday
          }
        }
      }
    }
  }
}

{
  "login": "octocat",
  "from": "2026-01-01T00:00:00Z",
  "to": "2026-02-01T00:00:00Z"
}

queryとvariablesオブジェクトをPOSTのJSON本文に含めます。実際のトークンは例に入れず、追加フィールドは公式スキーマで確認してください。

貢献カレンダーのフィールドを読む

レスポンスのパスはdata.user.contributionsCollection.contributionCalendarです。ユーザーを解決できない場合、認証アカウントからフィールドを取得できない場合、レスポンスにエラーが含まれる場合があります。ネストしたプロパティにアクセスする前に各階層を検証してください。

totalContributionsは指定期間の合計です。weeksはカレンダーを週ごとにまとめ、contributionDaysは各日を表します。contributionCountはその日の数値、dateは日付、weekdayは曜日を示す数値で1が月曜日です。colorは16進数の色で、このカレンダーでは濃い色ほど貢献数が多いことを示します。日付と件数を基礎データにし、色は表示用メタデータとして扱います。

日別データはアクセシブルな表、ヒートマップ、週ごとの集計、グラフに利用できます。活動がない日も削除せず残してください。ゼロの日を落とすと日付の並びがずれ、活動を誤った日に結び付けるおそれがあります。

日付範囲を明示する

fromとtoにはISO 8601形式のDateTimeを渡します。UTCの境界を明示すると定期レポートを再現しやすく、利用者、サーバー、グラフでタイムゾーンが異なる場合の日付ずれも防げます。時刻を変換する前に、GitHubのカレンダー日付とローカル表示時刻のどちらで集計するか決めましょう。

ローリング表示では開始日と終了日を一度計算し、レスポンスと一緒に保存します。比較する期間は長さをそろえ、長い履歴は範囲を分割してください。単一のレスポンスを無制限のアーカイブと考えてはいけません。

UTCの深夜近くで始まる期間と終わる期間、活動が見えない期間を試します。合計と日別データが要求した範囲に合うか確認してください。合計が0でも有効な結果であり、クエリ失敗とは限りません。

グラフ化する前にレスポンスを正規化する

内部の簡潔なデータ形式を作ると、グラフ、CSV出力、定期スナップショットでAPIレスポンスを扱いやすくなります。週の配列を日別の順序付きリストにし、日付と件数を残します。表示で必要なときだけ色やweekdayも保存しましょう。オブジェクトのキー順に頼らず、展開後に日付で並べ替えます。

本番アプリでは、日付を解釈できることと件数が有限の非負値であることを検証します。ユーザーがない、配列が空、日付が重複、GraphQLデータが部分的、レート制限になった場合の処理を表示前に決めてください。欠落データを無言でゼロに置き換えるより、明確な空状態を示す方が正確です。

プロフィールカレンダーとリポジトリ履歴では調べる内容が違います。プロフィールのマスが欠ける理由は貢献グラフのルールガイドで、コミット記録はコミット履歴のガイドで確認してください。

週を日別レコードに展開する

const days = (calendar.weeks || [])
  .flatMap((week) => week.contributionDays || [])
  .map(({ date, contributionCount, color, weekday }) => ({
    date,
    count: Number(contributionCount),
    color,
    weekday,
  }))
  .sort((a, b) => a.date.localeCompare(b.date));

この処理の前にカレンダーを検証し、データがない場合を明示的に扱います。時系列を保つため、件数ゼロの日も残します。

• GitHub貢献グラフのルールガイド — プロフィール上の計上ルールとマスが欠ける原因を説明します。
• GitHubコミット履歴のガイド — リポジトリの記録、ファイル、比較範囲を扱います。
• GitHub Cityを試す — 元のプロフィールグラフを確認してから公開パターンを3Dで表示します。

GraphQLのレスポンスと制限を確認する

リクエストに失敗したらHTTPステータス、レスポンスJSON、errors配列を合わせて確認します。無効なクエリはデータより先に拒否されることがあります。一方、有効なクエリでも期間内に貢献がないユーザーを返すことがあります。診断内容を絞り、BearerトークンやAuthorizationヘッダー全体をログに残さないでください。

プライバシーと貢献データの意味を尊重する

貢献カレンダーはプロフィールのアクティビティであり、非公開リポジトリの一覧や仕事の完全な記録ではありません。GitHubのプライバシー設定によって見える活動が変わり、認証アプリは用途に必要なデータだけを求めるべきです。グラフを他の人に見せるときは、データ元と期間を説明してください。

トークンは認証情報です。サーバー側のシークレット管理やローカル環境変数から読み込み、可能なら権限を絞り、漏えいした認証情報を更新し、ログから秘匿します。公開ブラウザページのHTMLやJavaScriptに個人用トークンを埋め込んではいけません。

貢献件数を品質や生産性の総合スコアとして見せないでください。合計値だけではレビューの深さ、保守作業、表示されない非公開活動を説明できません。視覚化では日付のあるGitHub貢献カレンダーのスナップショットとして表示します。