Trainingsfunktionen mit der Google Health API entwickeln

Die Google Health API erfasst Trainingseinheiten und den Trainingsverlauf von Nutzern mit dem Sitzungsdatentyp exercise. Eine Sitzung fungiert als Container, der Aktivitätsmetadaten, Ereignisse zum Anhalten und Fortsetzen, Runden oder Splits sowie zusammenfassende Messwerte bündelt.

Hier erfahren Sie, wie Sie Trainingseinheiten in Ihrer Anwendung lesen, schreiben und strukturieren, um Ihren Nutzern das bestmögliche Erlebnis zu bieten.

Unterstützte Datentypen

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

Tabelle: Datentypen für Trainingseinheiten in der Google Health API

Datentyp   dataType   filter Parameter	Datensatztyp	Verfügbare Vorgänge	Umfang	Webhook Unterstützung	Unterstützung für „Echte Nullen“
Trainingseinheit   exercise   exercise	Sitzung	list, get, reconcile, create, update, batchDelete	activity_and_fitness

Zugehörige Telemetriedatentypen

Bei Trainingseinheiten wird der Datentyp exercise als Container verwendet. Typische Trainings-Tracker schreiben und lesen jedoch während der Sitzung detaillierte Telemetriedaten mit hoher Frequenz. Diese Messwerte (z. B. Herzfrequenz oder Schrittzahl) müssen mit den entsprechenden Datentypen gelesen oder geschrieben werden.

In der folgenden Tabelle werden die Felder im metricsSummary-Objekt des Datentyps exercise den entsprechenden Telemetriedatentypen der Google Health API zugeordnet:

Zusammenfassungsfeld (metricsSummary)	Name des Telemetriedatentyps für den Tag	ID des Telemetriedatentyps der API
caloriesKcal	Durch Aktivität verbrauchte Kalorien	active-energy-burned
distanceMillimeters	Entfernung	distance
steps	Schritte	steps
averageHeartRateBeatsPerMinute	Herzfrequenz	heart-rate
activeZoneMinutes	Aktivzonen­minuten	active-zone-minutes

In den folgenden Abschnitten finden Sie technische Details zum Datentyp exercise, einschließlich Beispielen für die REST-Darstellung, der Verarbeitung von GPS-Routen und Richtlinien zur Integration.

Trainingseinheiten

Schreiben Sie tägliche Aktivitäten oder Trainingseinheiten als exercise-Sitzungsdatenpunkte. Jeder Datenpunkt beschreibt die gesamte Sitzung, enthält Details zu Ereignisintervallen (z. B. Aktionen zum Anhalten und Fortsetzen) und liefert zusammenfassende Messwerte (z. B. Gesamtentfernung, Schritte und durchschnittliche Herzfrequenz).

Sitzungsattribute

Überprüfen Sie beim Strukturieren eines Trainingsdatenpunkts die folgenden Kernkomponenten:

• Sitzungszeit (interval): Die Start- und Endzeit der gesamten Trainingseinheit sowie die Zeitzonen-Offsets, die zu diesen Zeitpunkten aktiv sind.
• Aktivitätsart (exerciseType): Die Kategorie der ausgeführten Aktivität (z. B. RUNNING, WALKING, BIKING oder AEROBIC_WORKOUT). Geben Sie die genaue Art des körperlichen Trainings an.
• Anzeigename (displayName): Ein nutzerfreundlicher Name für die Trainingseinheit (z. B. „Trailrun am Nachmittag“).
• Aktive Dauer (activeDuration): Die tatsächliche aktive Zeit des Trainings, ohne Pausenintervalle. Bei der Standardformatierung wird das Format Duration verwendet (z. B. "1800s").

Zusammenfassende Messwerte

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

• caloriesKcal: Die insgesamt während des Trainings verbrauchten aktiven Kalorien in Kilokalorien (kcal).
• distanceMillimeters: Die zurückgelegte Gesamtentfernung in Millimetern, um eine hohe Genauigkeit über alle Einheiten hinweg zu gewährleisten.
• steps: Die insgesamt während des Trainings zurückgelegten Schritte.
• averageHeartRateBeatsPerMinute: Die durchschnittliche Herzfrequenz des Nutzers während der aktiven Minuten der Sitzung.
• activeZoneMinutes: Die kumulative Anzahl der Aktivzonenminuten, die während des Trainings erreicht wurden.
• averageSpeedMillimetersPerSecond: Die durchschnittliche Bewegungsgeschwindigkeit in Millimetern pro Sekunde.
• averagePaceSecondsPerMeter: Das durchschnittliche Tempo während der aktiven Minuten der Sitzung in Sekunden pro Meter.
• elevationGainMillimeters: Der gesamte Höhenunterschied während der Sitzung.

Runden und Splits

Verwenden Sie für Trainingseinheiten mit Runden (z. B. Läufe auf der Laufbahn oder Schwimmen im Pool) splitSummaries.

Jeder Split enthält Folgendes:

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

Trainingsereignisse

Um die aktive Dauer genau zu berechnen, erfassen Sie Zustandsübergänge (z. B. manuelle oder automatische Pausenereignisse) mit exerciseEvents.

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

• START / STOP: Gibt die Zeitstempel für den Beginn und das Ende an, wenn der Nutzer die Aufzeichnung explizit gestartet oder beendet hat.
• PAUSE / RESUME: Gibt an, wann die Sitzung manuell angehalten oder fortgesetzt wurde.
• AUTO_PAUSE / AUTO_RESUME: Gibt sensorbasierte automatische Pausen/Fortsetzungen an.

Trainingseinheit schreiben

Wenn Sie eine Trainingseinheit erstellen, aktualisieren oder importieren möchten, schreiben Sie einen Datenpunkt in die Sammlung des Datentyps exercise. Verwenden Sie den Endpunkt create für Datenpunkte.

Beispiel für die REST-Darstellung

Das folgende Beispiel zeigt, wie Sie eine Trainingseinheit mit der Methode POST schreiben:

Anfrage

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

Antwort

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

GPS-Routen und Standort-Tracking

Die API speichert grundlegende Sitzungszusammenfassungen direkt im Datenpunkt exercise, verarbeitet aber den detaillierten Standortverlauf und die GPS-Routenkoordinaten als separaten Stream.

Wenn Sie die detaillierten Routendaten für eine Outdoor-Sitzung herunterladen möchten, rufen Sie die benutzerdefinierte Methode exportExerciseTcx auf. Dieser Endpunkt gibt die Route im Industriestandard Training Center XML (TCX) 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>

Wichtig: Sie müssen `?alt=media` an die Anfrage-URL anhängen, um die unformatierte TCX-Datei herunterzuladen. Andernfalls antwortet der Server mit einem Standard-JSON Umschlag.

Erforderliche Bereiche und Standort

Wenn Sie Daten für GPS-Routen und Standort-Tracking lesen oder schreiben möchten, fordern Sie die folgenden OAuth-Bereiche im Zugriffstoken Ihrer Anwendung an:

• Lesezugriff:https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
• Schreibzugriff:https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
• Lesezugriff:https://www.googleapis.com/auth/googlehealth.location.readonly

Wenn in den Autorisierungsheadern ein erforderlicher Bereich fehlt, gibt die Google Health API einen Autorisierungsfehler zurück.

Richtlinien

Beachten Sie bei der Integration des Trainings-Trackings in Ihre App die folgenden Richtlinien für Design und Implementierung.

Aktive vs. Gesamtdauer

Verwenden Sie zum Berechnen von Geschwindigkeits- oder Tempowerten immer activeDuration und nicht die Differenz zwischen startTime und endTime. So wird verhindert, dass Pausenintervalle Ihre Messwerte verzerren.

Wenn ein Nutzer beispielsweise um 8:00 Uhr mit dem Training beginnt und um 8:35 Uhr aufhört, beträgt die Gesamtdauer des Trainings 2.100 Sekunden. Wenn der Nutzer das Training 5 Minuten (300 Sekunden) lang angehalten hat, legen Sie activeDuration auf "1800s" (2.100 – 300) fest. Die API verwendet die aktive Dauer, um Durchschnittswerte zu berechnen, indem die Gesamtentfernung durch 1.800 Sekunden anstelle von 2.100 Sekunden geteilt wird.

Standort frühzeitig anfordern

Wenn Ihre App Trainingsrouten auf einer Karte darstellt, fordern Sie zusätzlich zum Bereich für Aktivitäten und Fitness auch Standortberechtigungen und den Google Health-Bereich location an. Erklären Sie den Nutzern, warum Ihre App den Standortbereich benötigt, wenn sie GPS-Trainingseinheiten überprüft.

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

Echtzeitsynchronisierung mit Webhooks

Abonnieren Sie den Datentyp exercise, um Ihr Back-End mit Webhooks zu benachrichtigen, wenn neue Trainingsdaten verfügbar sind. So können Sie nach dem Training in Echtzeit Aktionen auslösen.

Wenn Ihr Server eine Webhook-Benachrichtigung erhält, enthält sie die healthUserId und das spezifische physische Zeitintervall des Trainings. Ihr Server sollte die Benachrichtigung asynchron verarbeiten und dann den neuen exercise Datenpunkt vom /users/me/dataTypes/exercise/dataPoints Endpunkt anfordern. Weitere Informationen zum Einrichten von Abos finden Sie unter Webhook-Abos.

Einheitliche Messwerte beibehalten

Um ein vollständiges Trainingserlebnis zu bieten, muss Ihre App Telemetriedatenpunkte mit hoher Frequenz zusammen mit der gesamten exercise-Sitzung synchronisieren. So wird sichergestellt, dass die Tagesgesamtwerte, historischen Trends und detaillierten Diagramme des Nutzers vollständig übereinstimmen.

Telemetrie und Sitzungen synchronisieren (Schreibpfad)

Wenn Sie ein abgeschlossenes Training in die Google Health API importieren oder schreiben, implementieren Sie ein mehrstufiges Schreibmuster:

1. Sitzung schreiben: Erfassen Sie das Zusammenfassungsereignis, indem Sie einen Datenpunkt an POST /users/me/dataTypes/exercise/dataPoints senden.
2. Zeitreihenintervalle schreiben: Schreiben Sie gleichzeitig die detaillierten Daten punkte, die während des Trainings protokolliert wurden (z. B. Schritte pro Minute oder Intervalle für den Kalorienverbrauch), in die entsprechenden Sammlungen:
   • POST /users/me/dataTypes/steps/dataPoints
   • POST /users/me/dataTypes/active-energy-burned/dataPoints
   • POST /users/me/dataTypes/heart-rate/dataPoints

Hinweis: Wenn Sie Messwerte in Datenpunkte für Trainingseinheiten schreiben, werden die aggregierten Tageswerte des Nutzers (z. B. die Gesamtzahl der Schritte pro Tag oder Kaloriendiagramme) nicht automatisch ausgefüllt. Um diese zusammenfassenden Statistiken konsistent zu halten, schreiben Sie die Rohdatenpunkte explizit.

Detaillierte Daten für Diagramme abfragen (Lesepfad)

Wenn Sie Dashboards mit dem Trainingsverlauf oder Leistungsdiagramme für eine bestimmte Trainingseinheit rendern, fragen Sie die detaillierten Telemetriedaten mit dem Zeitfenster der Sitzung ab:

1. Sitzungszusammenfassungen abfragen: Rufen Sie /users/me/dataTypes/exercise/dataPoints auf, um die allgemeinen Trainings details und die endgültige metricsSummary abzurufen.
2. Diagrammmesswerte abrufen: Prüfen Sie interval.startTime und interval.endTime des Trainings. Führen Sie sekundäre GET-Aufrufe für die Telemetriesammlungen für dieses bestimmte Zeitfenster aus:
   • GET /users/me/dataTypes/heart-rate/dataPoints?startTime=2026-04-20T08:00:00Z&endTime=2026-04-20T08:35:00Z
3. GPS-Routen abrufen: Wenn die Metadaten der Sitzung angeben, dass GPS-Daten vorhanden sind (exerciseMetadata.hasGps ist true), rufen Sie die exportExerciseTcx Hilfsmethode auf, um Routenkoordinaten herunterzuladen.