Sviluppare esperienze di allenamento con l'API Google Health

L'API Google Health monitora le sessioni di allenamento e la cronologia degli esercizi degli utenti utilizzando il tipo di dati della sessione exercise. Una sessione funge da contenitore che raggruppa i metadati dell'attività, gli eventi di pausa e ripresa, i giri o gli split e le metriche di riepilogo.

Scopri come leggere, scrivere e strutturare gli allenamenti nella tua applicazione per offrire la migliore esperienza ai tuoi utenti.

Tipi di dati supportati

L'API supporta il seguente tipo di dati per il monitoraggio delle sessioni di allenamento e attività:

Tabella: tipi di dati degli allenamenti dell'API Google Health

Tipo di dati   dataType   filter parameter	Tipo di record	Operazioni disponibili	Ambito	Supporto webhook	Supporto per veri zeri
Esercizio   exercise   exercise	Sessione	list, get, reconcile, create, update, batchDelete	activity_and_fitness

Tipi di dati di telemetria correlati

Anche se le sessioni di allenamento utilizzano il tipo di dati exercise come contenitore, i tracker di allenamento tipici scrivono e leggono la telemetria dettagliata ad alta frequenza durante la sessione. Queste misurazioni (come la frequenza cardiaca o il conteggio dei passi) devono essere lette o scritte utilizzando i rispettivi tipi di dati.

La tabella seguente mappa i campi all'interno dell'oggetto metricsSummary del tipo di dati exercise ai tipi di dati di telemetria non elaborati corrispondenti dell'API Google Health:

Campo di riepilogo (metricsSummary)	Nome del tipo di dati di telemetria intraday	ID del tipo di dati di telemetria dell'API
caloriesKcal	Dispendio energetico durante l'attività fisica	active-energy-burned
distanceMillimeters	Distanza	distance
steps	Passaggi	steps
averageHeartRateBeatsPerMinute	Frequenza cardiaca	heart-rate
activeZoneMinutes	Minuti in zona attiva	active-zone-minutes

Le sezioni seguenti forniscono dettagli tecnici per il tipo di dati exercise, inclusi esempi di rappresentazione REST, gestione dei percorsi GPS e linee guida per l'integrazione.

Sessioni di allenamento

Scrivi le attività quotidiane o gli allenamenti come punti dati della sessione exercise. Ogni punto dati descrive la sessione complessiva, i dettagli degli intervalli di eventi (come le azioni di pausa e ripresa) e fornisce metriche di riepilogo (come distanza complessiva, passi e frequenza cardiaca media).

Attributi sessione

Quando strutturi un punto dati di allenamento, verifica i seguenti componenti principali:

• Ora della sessione (interval): l'ora di inizio e di fine della sessione di allenamento complessiva, insieme agli offset del fuso orario attivi in quei punti.
• Tipo di attività (exerciseType): la categoria di attività eseguita (ad esempio RUNNING, WALKING, BIKING o AEROBIC_WORKOUT). Specifica il tipo esatto di allenamento fisico.
• Nome visualizzato (displayName): un nome descrittivo per la sessione di allenamento (ad esempio "Corsa pomeridiana su sentiero").
• Durata attiva (activeDuration): il tempo attivo effettivo dell'allenamento, esclusi gli intervalli in pausa. La formattazione standard utilizza il formato Duration (ad esempio "1800s").

Metriche di riepilogo

L'oggetto nidificato metricsSummary contiene le metriche totali e medie calcolate per l'intera durata della sessione di allenamento:

• caloriesKcal: totale delle calorie attive bruciate durante l'allenamento, misurato in chilocalorie (kcal).
• distanceMillimeters: distanza totale percorsa, misurata in millimetri per mantenere un'elevata precisione tra le unità.
• steps: totale dei passi effettuati durante l'esercizio.
• averageHeartRateBeatsPerMinute: la frequenza cardiaca media dell'utente durante i minuti attivi della sessione.
• activeZoneMinutes: minuti cumulativi in zona attiva guadagnati durante l'allenamento.
• averageSpeedMillimetersPerSecond: velocità media di movimento in millimetri al secondo.
• averagePaceSecondsPerMeter: andatura media durante i minuti attivi della sessione, misurata in secondi al metro.
• elevationGainMillimeters: dislivello totale guadagnato durante la sessione.

Giri e split

Per gli allenamenti che prevedono giri (come le corse in pista o il nuoto in piscina), utilizza splitSummaries.

Ogni split contiene:

• Un startTime e un endTime specifici.
• Un activeDuration che rappresenta il tempo effettivo del giro.
• Un metricsSummary con ambito limitato a quel segmento.
• Un splitType per definire i confini della suddivisione (ad esempio DISTANCE, DURATION o MANUAL).

Eventi di allenamento

Per calcolare con precisione la durata attiva, monitora le transizioni di stato (come gli eventi di pausa manuale o automatica) utilizzando exerciseEvents.

Ogni evento contiene il timestamp (eventTime) e il tipo:

• START / STOP: indica i timestamp di limite di quando l'utente ha avviato o interrotto esplicitamente la registrazione.
• PAUSE / RESUME: indica quando la sessione è stata messa in pausa o ripresa manualmente.
• AUTO_PAUSE / AUTO_RESUME: indica le pause/riprese automatiche basate sui sensori.

Scrivere una sessione di allenamento

Per creare, aggiornare o importare una sessione di allenamento, scrivi un punto dati nella raccolta di tipi di dati exercise. Utilizza l'endpoint dei punti dati create.

Esempio di rappresentazione REST

L'esempio seguente mostra come scrivere una sessione di allenamento utilizzando un metodo POST:

Richiesta

POST https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Authorization: Bearer access-token
Content-Type: application/json

{
  "dataSource": {
    "recordingMethod": "ACTIVELY_MEASURED"
  },
  "exercise": {
    "interval": {
      "startTime": "2026-04-20T08:00:00Z",
      "startUtcOffset": "0s",
      "endTime": "2026-04-20T08:35:00Z",
      "endUtcOffset": "0s"
    },
    "exerciseType": "RUNNING",
    "displayName": "Morning Trail Run",
    "activeDuration": "1800s",
    "metricsSummary": {
      "caloriesKcal": 380.0,
      "distanceMillimeters": 5000000.0,
      "steps": "6200",
      "averageSpeedMillimetersPerSecond": 2777.78,
      "averagePaceSecondsPerMeter": 360.0,
      "averageHeartRateBeatsPerMinute": "148",
      "activeZoneMinutes": "30"
    },
    "exerciseMetadata": {
      "hasGps": true
    },
    "exerciseEvents": [
      {
        "eventTime": "2026-04-20T08:15:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "PAUSE"
      },
      {
        "eventTime": "2026-04-20T08:20:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "RESUME"
      }
    ],
    "splitSummaries": [
      {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:15:00Z",
        "endUtcOffset": "0s",
        "splitType": "DISTANCE",
        "metricsSummary": {
          "distanceMillimeters": 2500000.0,
          "caloriesKcal": 190.0
        }
      }
    ]
  }
}

Risposta

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.DataPoint",
    "name": "users/me/dataTypes/exercise/dataPoints/morning-trail-run-123456",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "application": {
        "packageName": "com.example.workoutapp"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "exercise": {
      "interval": {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:35:00Z",
        "endUtcOffset": "0s"
      },
      "exerciseType": "RUNNING",
      "displayName": "Morning Trail Run",
      "activeDuration": "1800s",
      "metricsSummary": {
        "caloriesKcal": 380.0,
        "distanceMillimeters": 5000000.0,
        "steps": "6200",
        "averageSpeedMillimetersPerSecond": 2777.78,
        "averagePaceSecondsPerMeter": 360.0,
        "averageHeartRateBeatsPerMinute": "148",
        "activeZoneMinutes": "30"
      },
      "exerciseMetadata": {
        "hasGps": true
      },
      "exerciseEvents": [
        {
          "eventTime": "2026-04-20T08:15:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "PAUSE"
        },
        {
          "eventTime": "2026-04-20T08:20:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "RESUME"
        }
      ],
      "splitSummaries": [
        {
          "startTime": "2026-04-20T08:00:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-04-20T08:15:00Z",
          "endUtcOffset": "0s",
          "activeDuration": "900s",
          "splitType": "DISTANCE",
          "metricsSummary": {
            "distanceMillimeters": 2500000.0,
            "caloriesKcal": 190.0
          }
        }
      ]
    }
  }
}

Percorsi GPS e monitoraggio della posizione

L'API salva i riepiloghi di base delle sessioni direttamente all'interno del punto dati exercise, ma gestisce la cronologia dettagliata delle posizioni e le coordinate del percorso GPS come stream separato.

Per scaricare i dati dettagliati del percorso per una sessione all'aperto, chiama il metodo personalizzato exportExerciseTcx. Questo endpoint restituisce il percorso nel formato Training Center XML (TCX) standard del settore.

Esportare il percorso GPS

Richiesta

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints/exercise-data-point-id:exportExerciseTcx?alt=media
Authorization: Bearer access-token

Risposta

Un payload HTTP con Content-Type: application/tcx+xml e intestazioni che indicano al browser di salvare il file.

<?xml version="1.0" encoding="UTF-8"?>
<TrainingCenterDatabase xmlns="http://www.garmin.com/xmlschemas/TrainingCenterDatabase/v2">
  <Activities>
    <Activity Sport="Running">
      <Id>2026-04-20T08:00:00Z</Id>
      <Lap StartTime="2026-04-20T08:00:00Z">
        <TotalTimeSeconds>1800</TotalTimeSeconds>
        <DistanceMeters>5000</DistanceMeters>
        <Calories>380</Calories>
        <Intensity>Active</Intensity>
        <TriggerMethod>Manual</TriggerMethod>
        <Track>
          <Trackpoint>
            <Time>2026-04-20T08:00:00Z</Time>
            <Position>
              <LatitudeDegrees>37.7749</LatitudeDegrees>
              <LongitudeDegrees>-122.4194</LongitudeDegrees>
            </Position>
            <AltitudeMeters>15.0</AltitudeMeters>
            <DistanceMeters>0.0</DistanceMeters>
          </Trackpoint>
        </Track>
      </Lap>
    </Activity>
  </Activities>
</TrainingCenterDatabase>

Importante: devi aggiungere `?alt=media` all'URL della richiesta per scaricare il file TCX non elaborato. In caso contrario, il server risponde con un envelope JSON standard.

Ambiti e località obbligatori

Per leggere o scrivere dati per i percorsi GPS e il monitoraggio della posizione, richiedi i seguenti ambiti OAuth nel token di accesso della tua applicazione:

• Accesso in lettura: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
• Accesso in scrittura: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
• Accesso in lettura: https://www.googleapis.com/auth/googlehealth.location.readonly

Se un ambito obbligatorio non è presente nelle intestazioni di autorizzazione, l'API Google Health restituisce un errore di autorizzazione.

Linee guida

Quando integri il monitoraggio degli allenamenti nella tua app, segui queste linee guida per la progettazione e l'implementazione.

Durata attiva rispetto alla durata totale

Per calcolare le metriche di velocità o andatura, utilizza sempre activeDuration anziché la differenza tra startTime e endTime. In questo modo, gli intervalli in pausa non distorcono le metriche.

Ad esempio, se un utente inizia un allenamento alle 08:00 e lo termina alle 08:35, la durata totale dell'allenamento è di 2100 secondi. Se l'utente ha messo in pausa l' allenamento per 5 minuti (300 secondi), imposta activeDuration su "1800s" (2100 - 300). L'API utilizza la durata attiva per calcolare le medie, dividendo la distanza totale per 1800 secondi anziché 2100.

Richiedere la posizione in anticipo

Se la tua app mappa i percorsi di allenamento, richiedi le autorizzazioni di accesso alla posizione e l'ambito location di Google Health, oltre all'ambito di attività e fitness. Spiega agli utenti perché la tua app richiede l'ambito di accesso alla posizione quando esamina gli esercizi con GPS.

Quando la tua app richiede l'ambito di accesso alla posizione (https://www.googleapis.com/auth/googlehealth.location.readonly), Google OAuth mostra all'utente una richiesta di consenso. Spiega agli utenti che questa autorizzazione è necessaria per eseguire il rendering delle sovrapposizioni dei percorsi ed esportare i file di tracciamento GPS (TCX). Se un utente concede l'ambito di attività, ma nega l'autorizzazione di accesso alla posizione, exportExerciseTcx restituisce un errore di autorizzazione, anche se puoi comunque accedere agli aggregati delle sessioni in metricsSummary.

Sincronizzazione in tempo reale tramite webhook

Abbonati al tipo di dati exercise per inviare una notifica al tuo backend tramite webhook quando diventano disponibili nuovi dati di allenamento. In questo modo puoi attivare le esperienze post-allenamento in tempo reale.

Quando il server riceve una notifica webhook, contiene healthUserId e l'intervallo di tempo fisico specifico dell'allenamento. Il server deve elaborare la notifica in modo asincrono e poi richiedere il nuovo exercise punto dati dall'/users/me/dataTypes/exercise/dataPoints endpoint. Per informazioni dettagliate su come configurare gli abbonamenti, consulta Abbonamenti webhook.

Mantenere la coerenza delle metriche

Per offrire un'esperienza di allenamento completa, la tua app deve sincronizzare i punti dati di telemetria ad alta frequenza insieme alla sessione exercise complessiva. In questo modo, i totali giornalieri, le tendenze storiche e i grafici dettagliati dell'utente rimangono completamente allineati.

Sincronizzare la telemetria e le sessioni (percorso di scrittura)

Quando importi o scrivi un allenamento completato nell'API Google Health, implementa un pattern di scrittura in più passaggi:

1. Scrivi la session a: registra l'evento di riepilogo pubblicando un punto dati in POST /users/me/dataTypes/exercise/dataPoints.
2. Scrivi gli intervalli delle serie temporali: scrivi contemporaneamente i punti dati granulari registrati durante l'allenamento (ad esempio, i passi al minuto o gli intervalli di dispendio calorico) nelle rispettive raccolte:
   • POST /users/me/dataTypes/steps/dataPoints
   • POST /users/me/dataTypes/active-energy-burned/dataPoints
   • POST /users/me/dataTypes/heart-rate/dataPoints

Nota: la scrittura delle metriche all'interno dei punti dati della sessione di allenamento non compila automaticamente i rollup aggregati dell'attività giornaliera dell'utente (ad esempio, i conteggi dei passi giornalieri complessivi o i grafici delle calorie). Per mantenere la coerenza di queste statistiche di riepilogo, scrivi esplicitamente i punti dati non elaborati.

Eseguire query sui dati dettagliati per i grafici (percorso di lettura)

Quando esegui il rendering delle dashboard degli allenamenti storici o dei grafici del rendimento per una sessione di allenamento specifica, esegui una query sulla telemetria granulare utilizzando la finestra temporale della sessione:

1. Esegui query sui riepiloghi delle sessioni: chiama /users/me/dataTypes/exercise/dataPoints per recuperare i dettagli complessivi dell'allenamento e il metricsSummary finale.
2. Recupera le metriche dei grafici: esamina interval.startTime e interval.endTime dell'allenamento. Esegui chiamate GET secondarie alle raccolte di telemetria per quella finestra temporale specifica:
   • GET /users/me/dataTypes/heart-rate/dataPoints?startTime=2026-04-20T08:00:00Z&endTime=2026-04-20T08:35:00Z
3. Recupera i percorsi GPS: se i metadati della sessione indicano che sono presenti dati GPS (exerciseMetadata.hasGps è true), richiama il metodo helper exportExerciseTcx per scaricare le coordinate del percorso.