Il Google Health API è l'erede ufficiale dell'API Web Fitbit e mira all'API Salute Google v4. Lo strumento passa al nuovo framework di autenticazione OAuth 2.0 di Google. Ora esiste un'alternativa open-source chiamata ghealth che incapsula questa API per l'uso nei terminali e negli agenti IA.
Che cosa è ghealth?
Ghealth è un wrapper per l'API Salute v4 di Google. Lo strumento può essere creato partendo dal codice sorgente con il comando go build -o ghealth. È fornito come file binario autocontenuto.
Ghealth è progettato esplicitamente per essere utilizzato con agenti IA. Ogni comando restituisce un output JSON semplificato con una forma costante. Inoltre, lo strumento offre codici di uscita deterministici, una flag --dry-run per eseguire un test e una flag --raw per ottenere l'output originale dell'API.
Funzionalità per Agenti: Due Skill Fornite Gratuitamente
I repository includono due "Skill" fornite come file SKILL.md. Una Skill copre i passaggi di autenticazione, configurazione e funzionalità globali. L'altra documenta in dettaglio tutti i 40 tipi di dati e le operazioni su di essi.
Gli agenti possono installare queste Skill con il comando npx skills add. La CLI è gestita direttamente dall'organizzazione GitHub Google-Health-API, che ospita anche i repository open-source legati alla piattaforma Fitbit da anni.
Tipi di Dati Strutturali: 40 Tipi di Dati Verificati
I 40 tipi di dati coprono le principali informazioni fornite da Fitbit e Google Pixel Watch. Esempi includono steps (passi), heart-rate (frequenza cardiaca), sleep (sonno), weight (peso), oxygen-saturation (saturazione di ossigeno) e heart-rate-variability (variabilità del ritmo cardiaco).
Supporto delle Operazioni Dati
Ogni tipo di dati offre un insieme di operazioni supportate, tra cui list, rollup, daily-rollup e reconcile per tipi leggibili.
I tipi modificabili, come esercizio, dormire, peso, grasso corporeo, e altezza, aggiungono funzioni come crea, aggiorna e cancella.
La funzione reconcile consente di unire dati provenienti da più fonti per risolvere discrepanze. Questo funziona in analogia al "Reconciled Stream" dell'API versione 4.
L'analisi della funzione sleep mostra una struttura chiara. Con --detail, vengono restituiti dettagli per ogni fase (veglio, profondo, REM), utile per l'analisi settimanale.
Autenticazione e Configurazione
L'autenticazione richiede un OAuth 2.0 personalizzato. Gli utenti eseguono l'autenticazione con il comando ghealth setup. Un wizard guida l'utente nella creazione di un progetto Google Cloud e in una richiesta OAuth dal Console di Google Cloud.
Lo strumento gestisce solo token di accesso personalizzati di cui l'utente prende l'intera responsabilità. I file vengono salvati in ~/.config/ghealth/ con permessi a 0600, garantendo privacy.
Utilizzo: Esempi di Comandi
# Letture recenti di frequenza cardiacaghealth data heart-rate list --from today --limit 10# Totale passi giornalieri per una settimanaghealth data steps daily-rollup --from 2026-03-22 --to 2026-03-29# Fasi del sonno per le ultime 5 nottighealth data sleep list --limit 5 --detail
Usi Pratici con Ghealth
Gestire dati sul Sonno con Agenti IA
Selezionare diverse notti usando --detail. Inviare tale JSON ad agenti IA come Claude Code o Codex e richiederne una analisi delle tendenze del sonno profondo.
Esportare Allenamenti in CSV
Utilizzare ghealth data exercise export-tcx --id <id> --output ride.csv --as csv per ottenere CSV con dati GPS e battito cardiaco. I dati possono essere importati tramite pd.read_csv in Python per ulteriori elaborazioni.
Costruire una Visione Semplice del Ritmo Cardiaco a Riposo
Eseguire query su daily-resting-heart-rate per 30 giorni. Esempio: ghealth data daily-resting-heart-rate --format csv.
Confronto con Altri Strumenti
Riepilogo: Ghealth vs. API Raw vs. Alternative CLI
| Atributi | ghealth (CLI) | Google Health API v4 (REST diretto) | Altro CLI 1 | Altro CLI 2 |
|---|---|---|---|---|
| Installazione | Clona con git e compila in Go |
Nessuna; si chiama HTTP/gRPC | Compilazione da Go | Installazione con npm |
| Linguaggio | Go, unico binario | Qualsiasi | Go | Node.js |
| Autenticazione | OAuth personale, PKCE S256 | OAuth 2.0 di Google | OAuth personali | OAuth personali |
| Output JSON | JSON semplificato, flag SKILL | JSON grezzo / gRPC | JSON prevedibile | JSON stabile |
| Tipi di dati | 40 verificati | Intero v4 | Superficie v4 documentata | Sottoinsieme dei tipi |