API GraphQL de GitHub: calendario de contribuciones y consulta

Qué devuelve la API GraphQL de contribuciones de GitHub

La API GraphQL de contribuciones de GitHub permite leer el calendario de un perfil con fechas y recuentos estructurados. Indica el login, solicita contributionsCollection para un intervalo y selecciona contributionCalendar. La respuesta contiene el total y semanas con días individuales.

Cada registro diario incluye date y contributionCount. color y weekday ayudan a reproducir el calendario; totalContributions suma el intervalo. Estos valores describen actividad del perfil, no commits de un repositorio, un historial completo ni toda actividad privada.

La documentación de GitHub indica que las contribuciones de repositorios privados e internos solo se incluyen con el permiso opcional read:user. Solicítalo únicamente si el producto lo necesita; de lo contrario, limita los permisos del token.

La solicitud es un POST GraphQL al endpoint de GitHub y requiere autenticación. Guarda el token en un servidor o variable local, limita el acceso y nunca lo incluyas en JavaScript, repositorios públicos ni consultas compartidas.

Crear una solicitud a la API GraphQL de contribuciones de GitHub

El endpoint GraphQL de GitHub es https://api.github.com/graphql. Envía un POST con un token bearer en Authorization y un cuerpo JSON con query y variables. Separarlos facilita revisar y reutilizar la llamada con otro usuario o intervalo.

El ejemplo consulta el calendario del perfil, no los commits del repositorio. Pide el total, las semanas y sus días de contribución. Si solo necesitas el total anual, solicita totalContributions y omite los campos anidados.

GraphQL devuelve una envoltura JSON. Comprueba el estado HTTP y el arreglo superior errors: puede haber datos y errores a la vez. Registra por separado el mensaje y la ruta del campo afectado.

Consulta y variables

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

Incluye la consulta y el objeto variables en el cuerpo JSON del POST. No pongas un token real en este ejemplo y revisa el esquema oficial antes de añadir campos.

Leer los campos del calendario de contribuciones

La ruta de respuesta es data.user.contributionsCollection.contributionCalendar. Trata cada nivel como opcional en tu código: el usuario puede no resolverse, un campo puede no estar disponible para la cuenta autenticada o la respuesta puede incluir errores. No accedas a propiedades anidadas antes de validar la respuesta.

totalContributions suma el intervalo. weeks agrupa el calendario y cada contributionDays representa una fecha. contributionCount es la actividad diaria; date, la fecha; weekday, el día semanal (1 es lunes); color es hexadecimal y los tonos oscuros indican más contribuciones. Conserva fecha y recuento como datos, y color como metadato visual.

La lista diaria sirve para construir una tabla accesible, un mapa de intensidad, un resumen semanal o un gráfico. Conserva también los días sin actividad: si eliminas los ceros, la secuencia puede desplazarse y asignar la actividad a fechas equivocadas.

Elegir un intervalo de fechas explícito

Pasa from y to como DateTime ISO 8601. Los límites UTC explícitos hacen reproducibles los informes y evitan desfases de un día entre zonas horarias. Decide si agruparás por la fecha de GitHub o por una zona local antes de convertir marcas de tiempo.

En informes móviles, guarda los extremos exactos. Compara periodos de igual duración y divide historiales largos en intervalos acotados; una respuesta no es un archivo ilimitado.

Prueba límites cercanos a la medianoche UTC y un periodo sin actividad visible. El total y los días deben coincidir con el intervalo solicitado. Un total cero es válido, no indica un fallo.

Normalizar la respuesta antes de dibujarla

Un modelo compacto permite usar la respuesta en gráficos, CSV o instantáneas programadas. Aplana las semanas en una lista ordenada, conserva fecha y recuento, y guarda color o weekday solo si hacen falta. Ordena por fecha, no por las claves del objeto.

Valida que cada fecha se interprete y que el recuento sea finito y no negativo. Define cómo tratar usuarios ausentes, colecciones vacías, fechas duplicadas, datos parciales y límites de uso. Muestra un estado vacío en vez de un calendario roto o ceros inventados.

El calendario del perfil responde a una pregunta distinta del historial de repositorio. Usa la guía de reglas del gráfico de contribuciones para investigar casillas ausentes y la guía del historial de commits para consultar registros de un repositorio.

Aplanar semanas en registros diarios

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

Valida el calendario antes de este paso y trata los datos ausentes expresamente. Conserva los días con recuento cero para alinear la cronología.

• Guía de reglas del gráfico de contribuciones de GitHub — Explica las reglas de recuento del perfil y las casillas ausentes.
• Guía del historial de commits de GitHub — Explica registros, archivos y rangos de un repositorio.
• Probar GitHub City — Explora como visualización 3D un patrón público después de revisar el gráfico de origen.

Solucionar errores y límites de GraphQL

Ante un fallo, revisa el estado HTTP, el JSON y errors juntos. GitHub puede rechazar una consulta inválida o devolver un usuario sin actividad para el periodo. Sé concreto y no registres el token bearer ni la cabecera Authorization.

Respetar la privacidad y el significado de las contribuciones

El calendario muestra actividad del perfil, no repositorios privados ni todo el trabajo de una persona. La privacidad de GitHub afecta los datos visibles y una aplicación debe pedir solo lo necesario. Al compartir un gráfico, explica su origen e intervalo.

Trata el token como credencial: cárgalo desde un secreto del servidor o variable local, limita permisos, rota credenciales expuestas y ocúltalas en los registros. Nunca incluyas un token personal en HTML o JavaScript públicos.

No uses los recuentos como puntuación de calidad o productividad: no reflejan revisiones, mantenimiento ni actividad privada. Etiqueta el resultado como una instantánea fechada del calendario.