GitHub GraphQL Contributions API: come interrogare un calendario dei contributi

Cosa restituisce la GitHub GraphQL Contributions API

La GitHub GraphQL Contributions API legge il calendario di un profilo come date e conteggi strutturati. Indica il login, richiedi contributionsCollection per un intervallo e seleziona contributionCalendar. La risposta contiene il totale e settimane con singoli giorni.

Ogni record giornaliero include date e contributionCount. color e weekday aiutano a riprodurre il calendario; totalContributions aggrega l’intervallo. I valori descrivono l’attività del profilo, non i commit di un repository, una cronologia completa o tutta l’attività privata.

La documentazione di GitHub specifica che i contributi da repository privati e interni sono inclusi solo con lo scope facoltativo read:user. Richiedi tale accesso solo se il prodotto ne ha bisogno; altrimenti mantieni più limitate le autorizzazioni del token.

La richiesta è un POST GraphQL all’endpoint GitHub e richiede autenticazione. Tieni il token su un server o in una variabile locale, limita gli accessi e non inserirlo mai in JavaScript, repository pubblici o query condivise.

Creare una richiesta alla GitHub GraphQL Contributions API

L’endpoint GraphQL GitHub è https://api.github.com/graphql. Invia un POST con token bearer in Authorization e corpo JSON con query e variables. Separarli facilita revisione e riuso con un altro utente o intervallo.

L’esempio richiede il calendario del profilo, non i commit del repository. Seleziona totale, settimane e giorni di contribuzione. Per il solo totale annuale, richiedi totalContributions e ometti i campi annidati.

GraphQL restituisce un involucro JSON. Controlla stato HTTP e array errors: possono esserci dati ed errori insieme. Registra separatamente messaggio e percorso del campo interessato.

Query e variabili

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

Inserisci la query e l'oggetto variables nel corpo JSON del POST. Tieni un token reale fuori da questo esempio e consulta lo schema ufficiale prima di aggiungere altri campi.

Leggere i campi del calendario dei contributi

Il percorso della risposta è data.user.contributionsCollection.contributionCalendar. Nel codice considera facoltativo ogni livello: l'utente potrebbe non essere risolto, un campo potrebbe non essere disponibile per l'account autenticato o la risposta potrebbe contenere errori. Controlla la risposta prima di accedere alle proprietà annidate.

totalContributions aggrega l’intervallo. weeks raggruppa il calendario e ogni contributionDays indica una data. contributionCount è l’attività del giorno; date è la data; weekday indica il giorno (1 è lunedì); color è esadecimale, con toni scuri per più contributi. Conserva data e conteggio come dati, color come metadato.

Usa i record giornalieri per costruire una tabella, una heatmap o un grafico. Conserva i giorni con conteggio zero: rimuoverli può spostare le date e rappresentare male l'attività.

Scegliere un intervallo di date esplicito

Passa from e to come DateTime ISO 8601. Limiti UTC espliciti rendono riproducibili i report ed evitano scarti di un giorno tra fusi orari. Decidi se usare la data del calendario GitHub o un fuso locale prima di convertire gli orari.

Per i report mobili, salva gli estremi esatti. Confronta intervalli della stessa durata e dividi cronologie lunghe in periodi limitati: una risposta non è un archivio illimitato.

Prova limiti vicini alla mezzanotte UTC e un periodo senza attività visibile. Totale ed elenco devono corrispondere alla finestra richiesta. Zero è un risultato valido, non un errore.

Normalizzare la risposta prima di creare un grafico

Un modello compatto facilita grafici, CSV o snapshot pianificati. Appiattisci le settimane in una lista ordinata, conserva data e conteggio, poi color o weekday solo se necessari. Ordina per data, non per chiavi dell’oggetto.

Verifica date interpretabili e conteggi finiti e non negativi. Definisci come gestire utenti assenti, raccolte vuote, date duplicate, dati parziali e rate limit. Mostra uno stato vuoto invece di un calendario guasto o zeri inventati.

Il calendario del profilo risponde a una domanda diversa dalla cronologia di un repository. Usa la guida alle regole del grafico dei contributi per i quadrati mancanti o la guida alla cronologia dei commit quando ti servono i record di un repository.

Appiattire le settimane in record giornalieri

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

Convalida il calendario prima di questo passaggio e gestisci esplicitamente i dati assenti. Conserva i giorni a conteggio zero per mantenere allineata la sequenza temporale.

• Guida alle regole del grafico dei contributi GitHub — Usala per le regole di conteggio del profilo e per i quadrati mancanti.
• Guida alla cronologia dei commit GitHub — Usala per i commit, la cronologia dei file e gli intervalli del repository.
• Prova GitHub City — Dopo aver controllato il grafico di origine, esplora il modello pubblico dei contributi come visualizzazione 3D.

Risolvere problemi di risposta e limiti GraphQL

In caso di errore, controlla insieme stato HTTP, JSON e errors. GitHub può rifiutare una query invalida o trovare un utente senza attività nell’intervallo. Sii preciso e non registrare il token bearer né l’intera intestazione Authorization.

Rispettare privacy e significato dei contributi

Il calendario mostra l’attività del profilo, non repository privati né tutto il lavoro di una persona. Le impostazioni GitHub influenzano ciò che è visibile; un’app deve chiedere solo il necessario. Quando condividi un grafico, indica fonte e periodo.

Tratta il token come una credenziale: caricalo da un archivio segreto server o da una variabile locale, limita i permessi, ruota le credenziali esposte e rimuovile dai log. Non inserire token personali in HTML o JavaScript pubblici.

Non usare i conteggi come voto di qualità o produttività: non mostrano revisioni, manutenzione né attività privata. Indica che la visualizzazione è uno snapshot datato del calendario.