Panel personal para ver tus estadísticas de entrenamiento de Garmin Connect: actividades, mapas, zonas de FC, fitness (CTL/ATL/TSB), récords y más.

Los datos se descargan de tu cuenta de Garmin a archivos locales en tu ordenador. La app los lee desde ahí; no hay servidor en la nube ni base de datos.

Instala estas dos cosas si no las tienes ya:

También necesitas una cuenta de Garmin Connect (la misma que usas en la app del móvil o en connect.garmin.com).

¿No tienes Node.js o Python?

• Node.js: https://nodejs.org → descarga la versión LTS.
• Python: https://python.org/downloads → en Mac/Linux suele venir instalado.

Si ya tienes la carpeta garmin-stats en tu ordenador, ábrela en la terminal:

cd ruta/donde/está/garmin-stats

(Sustituye ruta/donde/está/garmin-stats por la ruta real, por ejemplo /Users/tu-usuario/Documents/garmin-stats.)

La app necesita tu email y contraseña de Garmin Connect para descargar tus actividades. Nunca subas este archivo a internet.

1. Copia el archivo de ejemplo:

 cp .env.example .env

2. Abre .env con cualquier editor de texto y rellena tus datos:

 GARMIN_EMAIL=tu@email.com
 GARMIN_PASSWORD=tu_contraseña

Usa el mismo email y contraseña con los que entras en Garmin Connect.

Entra en la carpeta fetch e instala las librerías necesarias:

cd fetch
python3 -m pip install -r requirements.txt
cd ..

Si pip no funciona, prueba con python3 -m pip install -r requirements.txt desde la carpeta fetch.

Desde la carpeta raíz del proyecto (garmin-stats):

python3 fetch/sync.py --limit N

Qué hace este comando:

• Inicia sesión en Garmin Connect con tu .env
• Descarga la lista de actividades y los detalles de cada una
• Guarda todo en public/data/ (archivos JSON)

La primera vez puede tardar varios minutos si tienes muchas actividades. Verás el progreso en la terminal.

Opciones útiles:

# Solo las 20 actividades más recientes (para probar)
python3 fetch/sync.py --limit 20

# Solo actividades desde una fecha
python3 fetch/sync.py --since 2024-01-01

# Más rápido, sin descargar rutas GPS
python3 fetch/sync.py --no-gpx

Importante: vuelve a ejecutar python3 fetch/sync.py cuando quieras actualizar los datos con entrenamientos nuevos. Las actividades ya descargadas no se vuelven a pedir a Garmin.

En la carpeta raíz del proyecto:

npm install

Solo hace falta hacerlo una vez (o cuando cambien las dependencias del proyecto).

npm run dev

Verás algo como:

  ➜  Local:   http://localhost:5173/

Abre ese enlace en el navegador (Chrome, Firefox, Safari…).

Para cerrar la app, vuelve a la terminal y pulsa Ctrl + C.

Cada vez que quieras usar la app con datos actualizados:

# 1. Sincronizar datos nuevos de Garmin
python3 fetch/sync.py

# 2. Arrancar la app
npm run dev

Luego abre http://localhost:5173 en el navegador.

En el menú lateral, entra en Ajustes para configurar:

• FC máxima
• FTP (ciclismo)
• FC y ritmo en umbral (running)

Estos valores se guardan en tu navegador y afectan a los cálculos de zonas, TSS y fitness.

No existe el archivo .env o está vacío. Repite el paso 2.

• Comprueba que el email y la contraseña en .env son correctos.
• Si tienes verificación en dos pasos (2FA) en Garmin, puede que falle el login automático. Prueba a desactivarla temporalmente o revisa la documentación de la librería garminconnect.

Aún no has sincronizado datos. Ejecuta primero:

python3 fetch/sync.py

Instala Node.js desde nodejs.org y vuelve a abrir la terminal.

Es normal: hay una pausa entre peticiones para no saturar la API de Garmin. Para una prueba rápida usa --limit 20 o --no-gpx.

Cierra otras ventanas de terminal donde tengas npm run dev corriendo, o Vite te propondrá otro puerto (por ejemplo 5174).

garmin-stats/
├── .env                 ← Tus credenciales (no compartir)
├── fetch/
│   ├── sync.py          ← Script que descarga datos de Garmin
│   └── requirements.txt ← Dependencias de Python
├── public/data/         ← Datos descargados (JSON)
└── src/                 ← Código de la app web (React)

Estos archivos contienen datos personales o credenciales. El .gitignore ya los excluye, pero conviene conocerlos:

Datos sensibles dentro de los JSON:

• Coordenadas GPS de cada entrenamiento (pueden revelar dónde vives o entrenas)
• Ciudades en los títulos de actividades
• FC, VO2max, calorías, ritmos y patrones horarios

Seguro para publicar:

• .env.example (solo tiene placeholders)
• Todo el código en src/ y fetch/

Antes de hacer git push, comprueba que no se cuelen datos:

git status

No deberían aparecer .env ni archivos dentro de public/data/. Si alguna vez los añadiste por error:

git rm -r --cached public/data/
git rm --cached .env

Luego haz commit de la eliminación. Si ya los subiste a GitHub, cambia tu contraseña de Garmin y considera borrar el historial del repositorio.