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 degli allenamenti e delle sessioni di 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 dispositivi indossabili registrano anche dati di telemetria dettagliati e ad alta frequenza durante una sessione. Nell'API Google Health, questi tipi di dati di telemetria granulari intraday sono di sola lettura e non possono essere creati o modificati direttamente tramite i propri endpoint REST. Quando scrivi una sessione di allenamento tramite l'API REST, passa le metriche di allenamento aggregate all'interno dell'oggetto metricsSummary del punto dati exercise.

La tabella seguente mappa i campi di riepilogo all'interno di exercise.metricsSummary ai tipi di dati di telemetria infragiornalieri di sola lettura corrispondenti su cui puoi eseguire query per la finestra temporale dell'allenamento:

Campo di riepilogo (metricsSummary) Nome del tipo di dati di telemetria infragiornalieri ID del tipo di dati di telemetria dell'API (sola lettura) Campo filtro (?filter=) Ambito OAuth di lettura obbligatorio
caloriesKcal Energia bruciata in attività active-energy-burned active_energy_burned.interval.start_time activity_and_fitness.readonly
distanceMillimeters Distanza distance distance.interval.start_time activity_and_fitness.readonly
steps Passaggi steps steps.interval.start_time activity_and_fitness.readonly
averageHeartRateBeatsPerMinute Frequenza cardiaca heart-rate heart_rate.sample_time.physical_time health_metrics_and_measurements.readonly
activeZoneMinutes Minuti in zona attiva active-zone-minutes active_zone_minutes.interval.start_time activity_and_fitness.readonly

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, fornisce dettagli sugli intervalli degli eventi (ad esempio le azioni di pausa e ripresa) e fornisce metriche di riepilogo (come distanza complessiva, passi e frequenza cardiaca media).

Attributi della 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 momenti.
  • Tipo di attività (exerciseType): la categoria di attività svolta (ad esempio RUNNING, WALKING, BIKING o AEROBIC_WORKOUT). Specifica il tipo esatto di allenamento fisico.
  • Nome visualizzato (displayName): un nome facile da usare per la sessione di allenamento. Se creato tramite l'API REST, il server compila il nome visualizzato localizzato per exerciseType, ad esempio "Run" per RUNNING.
  • Durata attività (activeDuration): il tempo di attività effettivo dell'allenamento, esclusi gli intervalli di pausa. La formattazione standard utilizza il formato Duration (ad esempio, "1800s"). Sul server, activeDuration viene calcolato dalla sessione interval meno eventuali intervalli PAUSE/RESUME o AUTO_PAUSE/AUTO_RESUME in exerciseEvents.

Metriche di riepilogo

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

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

Giri e tempi intermedi

Per gli allenamenti che prevedono giri (come la corsa su pista o il nuoto in piscina) sincronizzati da dispositivi supportati, splitSummaries segmenta la sessione per giro o tempo intermedio.

Ogni suddivisione contiene:

  • Un startTime e un endTime specifici.
  • Un activeDuration che rappresenta il tempo sul giro effettivo.
  • Un metricsSummary limitato solo 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 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 attivate dai sensori.

Scrivi 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",
    "platform": "GOOGLE_WEB_API"
  },
  "exercise": {
    "interval": {
      "startTime": "2026-04-20T08:00:00Z",
      "startUtcOffset": "0s",
      "endTime": "2026-04-20T08:35:00Z",
      "endUtcOffset": "0s"
    },
    "exerciseType": "RUNNING",
    "activeDuration": "1800s",
    "metricsSummary": {
      "caloriesKcal": 380.0,
      "distanceMillimeters": 5000000.0,
      "steps": "6200",
      "averageHeartRateBeatsPerMinute": "148",
      "averagePaceSecondsPerMeter": 0.36
    },
    "exerciseEvents": [
      {
        "eventTime": "2026-04-20T08:15:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "PAUSE"
      },
      {
        "eventTime": "2026-04-20T08:20:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "RESUME"
      }
    ]
  }
}

Risposta

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/999298779973222220/dataTypes/exercise/dataPoints/3054085373369111216",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "application": {
        "googleWebClientId": "438076457939-example.apps.googleusercontent.com"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "exercise": {
      "interval": {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:35:00Z",
        "endUtcOffset": "0s"
      },
      "exerciseType": "RUNNING",
      "metricsSummary": {
        "caloriesKcal": 380,
        "distanceMillimeters": 5000000,
        "steps": "6200",
        "averagePaceSecondsPerMeter": 0.36,
        "averageHeartRateBeatsPerMinute": "148"
      },
      "exerciseMetadata": {},
      "displayName": "Run",
      "activeDuration": "1800s",
      "exerciseEvents": [
        {
          "eventTime": "2026-04-20T08:15:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "PAUSE"
        },
        {
          "eventTime": "2026-04-20T08:20:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "RESUME"
        }
      ],
      "updateTime": "2026-04-20T08:35:10.123456Z",
      "createTime": "2026-04-20T08:35:10.123456Z"
    }
  }
}

Percorsi GPS e monitoraggio della posizione

L'API salva i riepiloghi di base delle sessioni direttamente nel punto dati exercise, ma gestisce la cronologia delle posizioni dettagliata 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 standard di settore Training Center XML (TCX).

Esporta 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 località 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 dell'allenamento nella tua app, segui queste linee guida per la progettazione e l'implementazione.

Durata attiva e 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 alterano le metriche.

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

Calcolo della velocità e dell'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.

Richiedi la posizione in anticipo

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

Quando la tua app richiede l'ambito della 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 visualizzare gli overlay dei percorsi ed esportare i file di localizzazione GPS (TCX). Se un utente concede l'ambito dell'attività, ma nega l'autorizzazione di accesso alla posizione, exportExerciseTcx restituisce un errore di autorizzazione, anche se puoi comunque accedere alle aggregazioni delle sessioni in metricsSummary.

Sincronizzazione in tempo reale tramite webhook

Iscriviti al tipo di dati exercise per inviare notifiche al tuo backend utilizzando i webhook quando diventano disponibili nuovi dati sull'allenamento. In questo modo puoi attivare esperienze post-allenamento in tempo reale.

Quando il tuo server riceve una notifica webhook, questa contiene l'healthUserId e l'intervallo di tempo civile (civilIso8601TimeInterval) dell'allenamento aggiornato. Il tuo server deve confermare immediatamente la notifica con 204 No Content, elaborare il payload in modo asincrono ed eseguire query sull'endpoint exercise riconciliato utilizzando un filtro exercise.interval.civil_start_time (tieni presente che exercise supporta solo il filtro per civil_start_time):

GET https://health.googleapis.com/v4/users/healthUserId/dataTypes/exercise/dataPoints:reconcile?filter=exercise.interval.civil_start_time >= "2026-04-20T08:00:00" AND exercise.interval.civil_start_time < "2026-04-20T10:00:00"

Per maggiori dettagli su come configurare le sottoscrizioni, consulta Sottoscrizioni webhook.

Mantieni metriche coerenti

Per offrire un'esperienza di allenamento completa, includi le metriche di riepilogo quando scrivi le sessioni exercise ed esegui query sugli endpoint di telemetria di sola lettura utilizzando i filtri per intervallo di tempo durante il rendering dei grafici dei dettagli.

Scrittura delle metriche di riepilogo dell'allenamento (percorso di scrittura)

Quando importi o scrivi un allenamento completato nell'API Google Health, includi le metriche di telemetria aggregate dell'allenamento (steps, caloriesKcal, distanceMillimeters, averageHeartRateBeatsPerMinute e averagePaceSecondsPerMeter) all'interno dell'oggetto metricsSummary del punto dati exercise:

  • POST https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints

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

Per creare dashboard o grafici di allenamento per una sessione specifica, esegui una query sugli endpoint di telemetria riconciliati per la finestra temporale dell'allenamento:

  1. Recupera la sessione di allenamento dall'endpoint exercise utilizzando un filtro civil_start_time per ottenere interval e metricsSummary:

    GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints:reconcile?filter=exercise.interval.civil_start_time >= "2026-04-20T00:00:00" AND exercise.interval.civil_start_time < "2026-04-21T00:00:00"

  2. Utilizza interval.startTime e interval.endTime della sessione per eseguire query sugli endpoint di telemetria per quella finestra temporale fisica.

  3. Se exerciseMetadata.hasGps è true, chiama exportExerciseTcx per scaricare le coordinate del percorso.

Indietro
Temperatura cutanea
Avanti
Alimentazione e idratazione