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 container che raggruppa i metadati dell'attività, gli eventi di pausa e ripresa, i giri o i tempi intermedi 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 Operazioni
disponibili		 Ambito
Allenamento
dataType: exercise
filter parameter: exercise
Tipo di record: Sessione

Dispositivi compatibili
list, get, reconcile, create, update, batchDelete .activity_and_fitness.readonly
.activity_and_fitness.writeonly

Sebbene le sessioni di allenamento utilizzino il tipo di dati exercise come container, i tracker di allenamento tipici scrivono e leggono la telemetria dettagliata e 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 sul 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 su sentiero pomeridiana").
  • 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'allenamento.
  • averageHeartRateBeatsPerMinute: 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 tempi intermedi

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

Ogni tempo intermedio 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 create dataPoints.

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 un flusso 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>

Ambiti e posizione obbligatori

Per utilizzare la funzionalità Percorsi GPS e monitoraggio della posizione, la tua app deve richiedere i seguenti ambiti OAuth:

  • Lettura: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
  • Scrittura: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
  • Lettura: https://www.googleapis.com/auth/googlehealth.location.readonly

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 trascorsa 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.

Calcolo di velocità e andatura

L'API Google Health utilizza formule standard per calcolare la velocità e l'andatura:

  • Velocità = distance / time(hour)
  • Andatura = time(seconds) / distance

L'intestazione Accept-Language specificata nella richiesta determina l'unità di distanza.

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 forma fisica. Spiega agli utenti perché la tua app richiede l'ambito di accesso alla posizione quando esamina gli allenamenti 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 ricevere 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, questa contiene healthUserId e l'intervallo di tempo fisico specifico dell'allenamento. Il server deve elaborare la notifica in modo asincrono e quindi 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

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 una 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 del grafico: 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.
Indietro
Parametri vitali
Avanti
Alimentazione