Trainingsfunktionen mit der Google Health API entwickeln

Die Google Health API erfasst Trainingseinheiten und den Trainingsverlauf von Nutzern mit dem Sitzungsdatentyp exercise. Eine Trainingseinheit fungiert als Container, der Aktivitätsmetadaten, Pausen- und Fortsetzungsereignisse, Runden oder Zwischenzeiten sowie zusammenfassende Messwerte bündelt.

Hier erfährst du, wie du Trainings in deiner Anwendung liest, schreibst und strukturierst, um deinen Nutzern die bestmögliche Erfahrung zu bieten.

Unterstützte Datentypen

Die API unterstützt den folgenden Datentyp zum Erfassen von Trainings und Aktivitätssitzungen:

Tabelle: Datentypen für Trainings in der Google Health API
Datentyp Verfügbare
-Vorgänge		 Bereich
Training
dataType: exercise
filter parameter: exercise
Eintragstyp: Sitzung

Kompatible Geräte
list, get, reconcile, create, update, batchDelete .activity_and_fitness.readonly
.activity_and_fitness.writeonly

Während Trainingseinheiten den Datentyp exercise als Container verwenden, zeichnen Wearables während einer Trainingseinheit auch detaillierte, hochfrequente Telemetriedaten auf. In der Google Health API sind diese detaillierten Intraday-Telemetriedatentypen schreibgeschützt und können nicht direkt über ihre eigenen REST-Endpunkte erstellt oder geändert werden. Wenn du eine Trainingseinheit über die REST API schreibst, übergib aggregierte Trainingsmesswerte im metricsSummary-Objekt des exercise-Datenpunkts.

In der folgenden Tabelle werden die Zusammenfassungsfelder in exercise.metricsSummary den entsprechenden schreibgeschützten Intraday-Telemetriedatentypen zugeordnet, die du für das Zeitfenster des Trainings abfragen kannst:

Zusammenfassungsfeld (metricsSummary) Name des Intraday-Telemetriedatentyps ID des API-Telemetriedatentyps (schreibgeschützt) Filterfeld (?filter=) Erforderlicher OAuth-Bereich für Lesezugriff
caloriesKcal Verbrannte Kalorien (aktiv) active-energy-burned active_energy_burned.interval.start_time activity_and_fitness.readonly
distanceMillimeters Entfernung distance distance.interval.start_time activity_and_fitness.readonly
steps Schritte steps steps.interval.start_time activity_and_fitness.readonly
averageHeartRateBeatsPerMinute Herzfrequenz heart-rate heart_rate.sample_time.physical_time health_metrics_and_measurements.readonly
activeZoneMinutes Aktivzonen­minuten active-zone-minutes active_zone_minutes.interval.start_time activity_and_fitness.readonly

Die folgenden Abschnitte enthalten technische Details zum Datentyp exercise, einschließlich Beispielen für die REST-Darstellung, der Verarbeitung von GPS-Routen und Integrationsrichtlinien.

Trainingseinheiten

Tägliche Aktivitäten oder Trainingseinheiten als exercise-Sitzungsdatenpunkte schreiben. Jeder Datenpunkt beschreibt die gesamte Trainingseinheit, enthält Details zu Ereignisintervallen (z. B. Pausen- und Fortsetzungsaktionen) und liefert zusammenfassende Messwerte (z. B. Gesamtdistanz, Schritte und durchschnittliche Herzfrequenz).

Sitzungsattribute

Achte beim Strukturieren eines Trainingsdatenpunkts auf die folgenden Kernkomponenten:

  • Sitzungszeit (interval): Die Start- und Endzeit der gesamten Trainingseinheit sowie die zu diesen Zeitpunkten aktiven Zeitzonenabweichungen.
  • Aktivitätstyp (exerciseType): Die Kategorie der ausgeführten Aktivität (z. B. RUNNING, WALKING, BIKING oder AEROBIC_WORKOUT). Gib den genauen Typ des körperlichen Trainings an.
  • Anzeigename (displayName): Ein nutzerfreundlicher Name für die Trainingseinheit. Wenn die Erstellung über die REST API erfolgt, füllt der Server den lokalisierten Anzeigenamen für die exerciseType aus, z. B. "Run" für RUNNING.
  • Aktive Dauer (activeDuration): Die tatsächliche aktive Zeit des Trainings, ohne pausierte Intervalle. Bei der Standardformatierung wird das Format Duration verwendet (z. B. "1800s"). Auf dem Server wird activeDuration aus der interval der Sitzung abzüglich aller PAUSE/RESUME- oder AUTO_PAUSE/AUTO_RESUME-Intervalle in exerciseEvents berechnet.

Zusammenfassende Messwerte

Das verschachtelte Objekt metricsSummary enthält Gesamt- und Durchschnittsmesswerte, die für die gesamte Dauer der Trainingseinheit berechnet werden:

  • caloriesKcal: Gesamtzahl der während des Trainings verbrannten aktiven Kalorien, gemessen in Kilokalorien (kcal).
  • distanceMillimeters: Insgesamt zurückgelegte Distanz, gemessen in Millimetern, um eine hohe Genauigkeit über alle Einheiten hinweg zu gewährleisten.
  • steps: Gesamtzahl der Schritte, die während des Trainings zurückgelegt wurden.
  • averageHeartRateBeatsPerMinute: Die durchschnittliche Herzfrequenz des Nutzers während der aktiven Minuten der Trainingseinheit.
  • activeZoneMinutes: Kumulierte Aktivzonenminuten, die während des Trainings gesammelt wurden.
  • averageSpeedMillimetersPerSecond: Durchschnittliche Bewegungsgeschwindigkeit in Millimetern pro Sekunde.
  • averagePaceSecondsPerMeter: Durchschnittliches Tempo während der aktiven Minuten der Trainingseinheit, gemessen in Sekunden pro Meter.
  • elevationGainMillimeters: Gesamter Höhenunterschied während der Trainingseinheit.

Runden und Zwischenzeiten

Bei Trainings mit Runden (z. B. Laufen auf der Bahn oder Schwimmen im Pool), die von unterstützten Geräten synchronisiert werden, segmentiert splitSummaries die Trainingseinheit nach Runde oder Teilstrecke.

Jeder Split enthält:

  • Eine bestimmte startTime und endTime.
  • Ein activeDuration, der die tatsächliche Rundenzeit darstellt.
  • Eine metricsSummary, die nur für dieses Segment gilt.
  • Ein splitType zum Definieren der Split-Grenzen (z. B. DISTANCE, DURATION oder MANUAL).

Sport-Events

Wenn du die aktive Dauer genau berechnen möchtest, solltest du Statusübergänge (z. B. manuelle oder automatische Pausenereignisse) mit exerciseEvents erfassen.

Jedes Ereignis enthält den Zeitstempel (eventTime) und den Typ:

  • START / STOP: Gibt die Zeitstempel an, zu denen der Nutzer die Aufzeichnung explizit gestartet oder beendet hat.
  • PAUSE / RESUME: Gibt an, wann die Sitzung manuell pausiert oder fortgesetzt wurde.
  • AUTO_PAUSE / AUTO_RESUME: Gibt an, dass das Training automatisch pausiert oder fortgesetzt wird, wenn der Sensor eine entsprechende Änderung erkennt.

Trainingseinheit schreiben

Wenn du eine Trainingseinheit erstellen, aktualisieren oder importieren möchtest, schreibe einen Datenpunkt in die Datentypsammlung exercise. Verwenden Sie den create-Endpunkt dataPoints.

Beispiel für eine REST-Darstellung

Im folgenden Beispiel wird gezeigt, wie eine Trainingseinheit mit der Methode POST geschrieben wird:

Anfrage

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"
      }
    ]
  }
}

Antwort

{
  "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"
    }
  }
}

GPS-Routen und Standort-Tracking

Die API speichert grundlegende Zusammenfassungen von Trainingseinheiten direkt im Datenpunkt exercise, verarbeitet aber den detaillierten Standortverlauf und die GPS-Routen-Koordinaten als separaten Stream.

Wenn du die detaillierten Routendaten für eine Outdoor-Trainingseinheit herunterladen möchtest, rufe die benutzerdefinierte Methode exportExerciseTcx auf. Dieser Endpunkt gibt die Route im branchenüblichen Training Center XML (TCX)-Format zurück.

GPS-Route exportieren

Anfrage

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

Antwort

Eine HTTP-Nutzlast mit Content-Type: application/tcx+xml und Headern, die den Browser anweisen, die Datei zu speichern.

<?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>

Erforderliche Bereiche und Standort

Wenn du die Funktion GPS-Routen und Standortverfolgung verwenden möchtest, muss deine App die folgenden OAuth-Bereiche anfordern:

  • Lesen: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
  • Schreiben: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
  • Lesen: https://www.googleapis.com/auth/googlehealth.location.readonly

Richtlinien

Wenn du das Trainingstracking in deine App integrierst, beachte die folgenden Design- und Implementierungsrichtlinien.

Aktive Dauer im Vergleich zur Gesamtdauer

Verwende zur Berechnung von Geschwindigkeits- oder Tempomesswerten immer activeDuration und nicht die Differenz zwischen startTime und endTime. So wird verhindert, dass pausierte Intervalle Ihre Messwerte verfälschen.

Wenn ein Nutzer beispielsweise um 08:00 Uhr mit einem Training beginnt und es um 08:35 Uhr beendet, beträgt die Gesamtdauer des Trainings 2.100 Sekunden. Wenn der Nutzer das Training für 5 Minuten (300 Sekunden) pausiert hat und du die Ereignisse PAUSE und RESUME in exerciseEvents einbeziehst, beträgt die aktive Dauer "1800s" (2.100 – 300). Die API verwendet die aktive Dauer, um Durchschnittswerte zu berechnen. Dabei wird die Gesamtstrecke durch 1.800 Sekunden statt durch 2.100 Sekunden geteilt.

Berechnung von Geschwindigkeit und Tempo

Die Google Health API verwendet Standardformeln, um Geschwindigkeit und Tempo zu berechnen:

  • Geschwindigkeit = distance / time(hour)
  • Tempo = time(seconds) / distance

Der in der Anfrage angegebene Header Accept-Language bestimmt die Entfernungseinheit.

Standort frühzeitig anfragen

Wenn deine App Trainingsrouten aufzeichnet, fordere zusätzlich zum Aktivitäts- und Fitnessbereich die Berechtigung zur Standortermittlung und den Google Health-Bereich location an. Erkläre den Nutzern, warum deine App den Standortbereich benötigt, wenn sie GPS-Trainings überprüfen.

Wenn Ihre App den Standortbereich (https://www.googleapis.com/auth/googlehealth.location.readonly) anfordert, zeigt Google OAuth dem Nutzer eine Zustimmungsaufforderung an. Erkläre deinen Nutzern, dass diese Berechtigung erforderlich ist, um Routen-Overlays zu rendern und GPS-Track-Dateien (TCX) zu exportieren. Wenn ein Nutzer den Aktivitätsbereich gewährt, aber die Berechtigung zur Standortermittlung verweigert, gibt exportExerciseTcx einen Autorisierungsfehler zurück. Sie können aber weiterhin auf Sitzungszusammenfassungen in metricsSummary zugreifen.

Mit Webhooks synchronisieren

Abonniere den Datentyp exercise, um dein Backend über Webhooks zu benachrichtigen, wenn neue Trainingsdaten verfügbar sind. So kannst du automatisch Aktionen nach dem Training auslösen.

Wenn dein Server eine Webhook-Benachrichtigung erhält, enthält diese die healthUserId und das Zeitintervall (civilIso8601TimeInterval) des aktualisierten Trainings. Ihr Server sollte die Benachrichtigung sofort mit 204 No Content bestätigen, die Nutzlast asynchron verarbeiten und den abgeglichenen exercise-Endpunkt mit einem exercise.interval.civil_start_time-Filter abfragen. Beachten Sie, dass exercise nur das Filtern nach civil_start_time unterstützt:

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"

Weitere Informationen zum Einrichten von Abos finden Sie unter Webhook-Abos.

Konsistente Messwerte beibehalten

Wenn du ein umfassendes Trainingserlebnis bieten möchtest, solltest du beim Schreiben von exercise-Einheiten zusammenfassende Messwerte einbeziehen und die Telemetrie-Endpunkte mit Lesezugriff mit Zeitraumfiltern abfragen, wenn du Detaildiagramme renderst.

Zusammenfassende Trainingsmesswerte schreiben (Schreibpfad)

Wenn du ein abgeschlossenes Training in die Google Health API importierst oder schreibst, füge die aggregierten Telemetriemesswerte des Trainings (steps, caloriesKcal, distanceMillimeters, averageHeartRateBeatsPerMinute und averagePaceSecondsPerMeter) in das metricsSummary-Objekt des Datenpunkts exercise ein:

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

Detaillierte Daten für Diagramme abfragen (Lesepfad)

Wenn Sie Trainings-Dashboards oder -Diagramme für eine bestimmte Trainingseinheit erstellen möchten, fragen Sie die abgeglichenen Telemetrie-Endpunkte für das Zeitfenster dieses Trainings ab:

  1. Rufe die Trainingseinheit vom exercise-Endpunkt mit einem civil_start_time-Filter ab, um die interval und die metricsSummary zu erhalten:

    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. Verwenden Sie die interval.startTime und interval.endTime der Sitzung, um die Telemetrie-Endpunkte für dieses physische Zeitfenster abzufragen.

  3. Wenn exerciseMetadata.hasGps den Wert true hat, rufen Sie exportExerciseTcx auf, um die Routenkoordinaten herunterzuladen.

Zurück
Hauttemperatur
Weiter
Ernährung und Flüssigkeitszufuhr