Trainingsfunktionen mit der Google Health API entwickeln

Die Google Health API erfasst Trainingseinheiten und den Trainingsverlauf von Nutzern mithilfe des Sitzungsdatentyps 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.readonly
.activity_and_fitness.writeonly

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 Messungen (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 Verbrannte Kalorien bei Aktivität 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 Integrationsrichtlinien.

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. „Nachmittagslauf“).
  • Aktive Dauer (activeDuration): Die tatsächliche aktive Zeit des Trainings, ohne angehaltene Intervalle. Die Standardformatierung verwendet das Format Duration (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: Insgesamt verbrannte Kalorien bei Aktivität während des Trainings, gemessen in Kilokalorien (kcal).
  • distanceMillimeters: Zurückgelegte Gesamtentfernung, gemessen in Millimetern, um eine hohe Genauigkeit über alle Einheiten hinweg zu gewährleisten.
  • steps: Insgesamt während des Trainings zurückgelegte Schritte.
  • averageHeartRateBeatsPerMinute: Die durchschnittliche Herzfrequenz des Nutzers während der aktiven Minuten der Sitzung.
  • activeZoneMinutes: Kumulative Aktivzonenminuten, die während des Trainings erreicht wurden.
  • averageSpeedMillimetersPerSecond: Durchschnittliche Bewegungsgeschwindigkeit in Millimetern pro Sekunde.
  • averagePaceSecondsPerMeter: Durchschnittliches Tempo während der aktiven Minuten der Sitzung, gemessen in Sekunden pro Meter.
  • elevationGainMillimeters: Gesamter Höhenunterschied während der Sitzung.

Runden und Splits

Verwenden Sie für Trainingseinheiten mit Runden (z. B. Laufstrecken oder Schwimmen im Pool) splitSummaries.

Jeder Split enthält:

  • Eine bestimmte startTime und endTime.
  • Eine activeDuration, die die tatsächliche Rundenzeit darstellt.
  • Eine metricsSummary, die nur auf dieses Segment beschränkt ist.
  • Einen splitType, um die Split-Grenzen zu definieren (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 der Aufzeichnung an, die vom Nutzer explizit festgelegt wurden.
  • 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 einer POST-Methode 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 exercise-Datenpunkt, 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>

Erforderliche Bereiche und Standort

Wenn Sie die Funktion GPS-Routen und Standort-Tracking verwenden möchten, muss Ihre 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

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 Tempomesswerten immer activeDuration und nicht die Differenz zwischen startTime und endTime. So wird verhindert, dass angehaltene Intervalle 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) 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 täglichen Gesamtwerte, historischen Trends und detaillierten Diagramme des Nutzers vollständig übereinstimmen.

Telemetrie und Sitzungen synchronisieren (Schreibpfad)

Wenn Sie eine abgeschlossene Trainingseinheit in die Google Health API importieren oder schreiben, implementieren Sie ein mehrstufiges Schreibmuster:

  1. Sitzung schreiben: Erstellen 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

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.
Zurück
Kalorien und Energie
Weiter
Ernährung