GitHub GraphQL API: Beitragskalender mit Tageswerten

Welche Daten die GitHub GraphQL Contributions API liefert

Die GitHub GraphQL Beitragskalender API ist hilfreich, wenn eine Anwendung Kalenderdaten mit Datumsangaben und Zählwerten statt eines Screenshots benötigt. Geben Sie den Login eines Nutzers an, fragen Sie dessen contributionsCollection für einen festgelegten Zeitraum ab und wählen Sie contributionCalendar. Die Antwort enthält eine Gesamtsumme sowie Wochen mit einzelnen Beitragstagen.

Ein brauchbarer Tagesdatensatz enthält date und contributionCount. color und weekday können die Kalenderdarstellung unterstützen, während totalContributions die Summe des Zeitraums angibt. Diese Werte beschreiben Profilaktivität. Sie sind weder ein Commit-Protokoll eines Repositorys noch ein vollständiges Auditprotokoll und garantieren nicht, dass die Anwendung jede private Aktivität sieht.

Laut GitHub-Referenz werden Beiträge aus privaten und internen Repositorys nur mit der optionalen Berechtigung read:user einbezogen. Fordern Sie sie nur an, wenn das Produkt sie benötigt; andernfalls sollten die Token-Berechtigungen möglichst eng bleiben.

Die Anfrage ist ein GraphQL-POST an den GitHub-Endpunkt und erfordert Authentifizierung. Speichern Sie das Token auf einem Server oder in einer lokalen Umgebungsvariable, erlauben Sie nur erforderlichen Zugriff und legen Sie Geheimnisse niemals in Browser-JavaScript, einem öffentlichen Repository oder einem geteilten Abfragebeispiel ab.

Eine Anfrage an die GitHub GraphQL Beitragskalender API erstellen

Der GraphQL-Endpunkt von GitHub ist https://api.github.com/graphql. Senden Sie eine POST-Anfrage mit einem Bearer-Token in Authorization und einem JSON-Body mit query und variables. Wenn Abfragetext und Variablenwerte getrennt sind, lässt sich der Aufruf leichter prüfen, testen und mit einem anderen Login oder Zeitraum wiederverwenden.

Das Beispiel fragt den Profilkalender ab, statt Commits aus Repositorys aufzulisten. Es wählt nur die Felder für eine Kalenderansicht aus: Summe, Wochen und deren Beitragstage. Für eine reine Jahressumme genügt totalContributions; die verschachtelten Kalenderfelder können dann entfallen.

GraphQL liefert einen JSON-Antwortumschlag. Prüfen Sie den HTTP-Status und das oberste errors-Array, bevor Sie Daten voraussetzen. Eine Antwort kann gleichzeitig brauchbare Daten und GraphQL-Fehler enthalten. Protokollieren Sie bei der Entwicklung deshalb die Fehlermeldung und den Pfad zum betroffenen Feld getrennt.

Abfrage und Variablen

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"
}

Fügen Sie die Abfrage und das variables-Objekt in den JSON-Body des POST ein. Verwenden Sie hier kein echtes Token und prüfen Sie weitere Felder im offiziellen Schema.

Die Felder des Beitragskalenders lesen

Der Antwortpfad lautet data.user.contributionsCollection.contributionCalendar. Behandeln Sie jede Ebene im Anwendungscode als optional: Der Nutzer kann nicht aufgelöst werden, ein Feld kann für das authentifizierte Konto fehlen oder die Antwort kann Fehler enthalten. Greifen Sie erst auf verschachtelte Eigenschaften zu, nachdem Sie die Antwort geprüft haben.

totalContributions ist die Summe des gewählten Zeitraums. weeks gruppiert den Kalender nach Wochen, und jeder Eintrag in contributionDays steht für ein Datum. contributionCount ist der Aktivitätswert des Tages, date das Kalenderdatum und weekday eine Zahl für den Wochentag; 1 bedeutet Montag. color ist ein Hexwert, wobei dunklere Stufen in diesem Kalender mehr Beiträge darstellen. Speichern Sie Datum und Zahl als Kerndaten und behandeln Sie die Farbe als Darstellungsmetadatum.

Die Tagesliste eignet sich für eine barrierearme Tabelle, eine Beitrags-Heatmap, eine Wochenübersicht oder ein Diagramm. Lassen Sie auch Tage ohne Aktivität stehen: Wenn Nullwerte entfernt werden, kann sich die Reihenfolge verschieben und Aktivität dem falschen Datum zuordnen.

Einen eindeutigen Zeitraum wählen

Übergeben Sie from und to als DateTime-Werte im ISO-8601-Format. Explizite UTC-Grenzen machen wiederkehrende Berichte reproduzierbar und vermeiden Tagesverschiebungen, wenn Nutzer, Server und Diagramm unterschiedliche Zeitzonen verwenden. Legen Sie vor einer Zeitumrechnung fest, ob nach GitHubs Kalenderdatum oder einer lokalen Zeitzone gruppiert wird.

Berechnen und speichern Sie bei einer rollierenden Ansicht beide Endpunkte. Verwenden Sie für Vergleiche gleich lange Zeitfenster und teilen Sie lange Historien in begrenzte Intervalle auf. Eine einzelne Antwort ist kein unbegrenztes Archiv.

Testen Sie einen Zeitraum, der nahe Mitternacht UTC beginnt und endet, sowie einen Zeitraum ohne sichtbare Aktivität. Summe und Tagesliste müssen zum angefragten Fenster passen. Eine Summe von null ist ein gültiges Ergebnis und kein Beweis für eine fehlgeschlagene Anfrage.

Die Antwort vor dem Diagramm normalisieren

Ein kompaktes internes Datenmodell vereinfacht Diagramme, CSV-Exporte und geplante Momentaufnahmen. Klappen Sie die Wochen in eine sortierte Tagesliste auf und behalten Sie Datum und Zählwert. color oder weekday speichern Sie nur, wenn die Darstellung sie benötigt. Sortieren Sie nach dem Aufklappen nach Datum, statt sich auf eine zufällige Objektschlüsselreihenfolge zu verlassen.

Prüfen Sie in einer Produktionsanwendung, ob jeder Tag ein lesbares Datum und einen endlichen, nicht negativen Zählwert hat. Entscheiden Sie vor der Anzeige, wie fehlende Nutzer, leere Sammlungen, doppelte Daten, teilweise GraphQL-Daten und Rate-Limit-Antworten behandelt werden. Ein klarer Leerzustand ist hilfreicher als ein kaputter Kalender oder das unbemerkte Ersetzen fehlender Daten durch Nullen.

Der Profilkalender beantwortet eine andere Frage als der Repository-Verlauf. Die Anleitung zu GitHub-Beitragsdiagrammregeln hilft bei fehlenden Profilkacheln; die Anleitung zum GitHub-Commit-Verlauf behandelt einzelne Repository-Datensätze.

Wochen zu Tagesdatensätzen abflachen

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));

Prüfen Sie den Kalender vor diesem Schritt und behandeln Sie fehlende Daten ausdrücklich. Bewahren Sie Tage mit null Beiträgen für eine korrekte Zeitachse.

• Anleitung zu GitHub-Beitragsdiagrammregeln — Erklärt Zählregeln im Profil und fehlende Kacheln.
• Anleitung zum GitHub-Commit-Verlauf — Behandelt Datensätze, Dateien und Bereiche eines Repositorys.
• GitHub City ausprobieren — Erkunden Sie ein öffentliches Muster in 3D, nachdem Sie das Quelldiagramm geprüft haben.

GraphQL-Antworten und Limits untersuchen

Untersuchen Sie bei einem Fehler gemeinsam HTTP-Status, Antwort-JSON und errors-Array. GitHub kann eine ungültige Abfrage vor der Datenrückgabe ablehnen; eine gültige Abfrage kann aber auch einen Nutzer ohne Aktivität im Zeitraum finden. Halten Sie Diagnosemeldungen konkret und protokollieren Sie weder das Bearer-Token noch den vollständigen Authorization-Header.

Datenschutz und Bedeutung der Beiträge beachten

Ein Beitragskalender zeigt Profilaktivität, keine Liste privater Repositorys und kein vollständiges Protokoll der Arbeit einer Person. GitHubs Datenschutzeinstellungen beeinflussen, was sichtbar ist. Eine autorisierte Anwendung sollte nur Daten anfordern, die sie tatsächlich benötigt. Nennen Sie beim Teilen eines Diagramms Quelle und Zeitraum.

Behandeln Sie das Token als Zugangsdaten: Laden Sie es aus einem serverseitigen Geheimnisspeicher oder einer lokalen Umgebungsvariable, begrenzen Sie Berechtigungen, erneuern Sie offengelegte Zugangsdaten und schwärzen Sie Protokolle. Eine öffentliche Browserseite darf kein persönliches Zugriffstoken in HTML oder JavaScript einbetten.

Stellen Sie Beitragszahlen nicht als Qualitätsnote oder vollständiges Produktivitätsmaß dar. Summen zeigen weder die Tiefe von Reviews noch Wartungsarbeit oder unsichtbare private Aktivität. Kennzeichnen Sie eine Visualisierung als datierte Momentaufnahme des Beitragskalenders.