Schlaffunktionen mit der Google Health API entwickeln

Die Google Health API bietet Datentypen, mit denen die Schlafmuster eines Nutzers erfasst werden, einschließlich Dauer, Qualität und physiologischer Messwerte während der Ruhe. Mithilfe dieser Messwerte können Apps Informationen zu Erholung, Schlafhygiene und langfristigen Gesundheitstrends liefern.

Physiologische Messwerte wie Herzfrequenzvariabilität (HFV), Sauerstoffsättigung (SpO2) und Atemfrequenz werden speziell während des Schlafs aufgezeichnet, da sich der Körper in einem stabilen Ruhezustand befindet. So kann die API eine Baseline für die autonome und respiratorische Gesundheit des Nutzers erfassen, ohne dass tagsüber Stressfaktoren, körperliche Aktivität oder unterschiedliche Umgebungsbedingungen die Messung beeinflussen.

Wenn Sie die Unterschiede zwischen diesen Datentypen kennen, können Sie die für Ihre Anwendung geeigneten Messwerte ermitteln.

Unterstützte Datentypen

Die API unterstützt die folgenden Datentypen zum Messen des Schlafs:

Tabelle: Google Health API-Schlafdatentypen
Datentyp Verfügbare
Vorgänge		 Bereich
Tägliche Herzfrequenzvariabilität
dataType:daily-heart-rate-variability
filter parameter:daily_heart_rate_variability
Eintragstyp : Täglich

Kompatible Geräte
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Tägliche Sauerstoffsättigung
dataType:daily-oxygen-saturation
filter parameter:daily_oxygen_saturation
Eintragstyp : Täglich

Kompatible Geräte
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Tägliche Atemfrequenz
dataType:daily-respiratory-rate
filter parameter:daily_respiratory_rate
Eintragstyp : Täglich

Kompatible Geräte
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Tägliche Ableitungen der Schlaftemperatur
dataType:daily-sleep-temperature-derivations
filter parameter:daily_sleep_temperature_derivations
Eintragstyp : Täglich

Kompatible Geräte
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Herzfrequenzvariabilität
dataType:heart-rate-variability
filter parameter:heart_rate_variability
Eintragstyp : Beispiel

Kompatible Geräte
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Sauerstoffsättigung
dataType:oxygen-saturation
filter parameter:oxygen_saturation
Eintragstyp : Beispiel

Kompatible Geräte
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Zusammenfassung der Atemfrequenz im Schlaf
dataType:respiratory-rate-sleep-summary
filter parameter:respiratory_rate_sleep_summary
Eintragstyp : Beispiel

Kompatible Geräte
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Schlaf
dataType:sleep
filter parameter:sleep
Eintragstyp : Sitzung

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

Schlafeinheiten und kurze Wachphasen

Eine Schlafeinheit (Sleep) stellt ein einzelnes Schlafereignis dar, z. B. eine einzelne Nachtruhe oder ein Nickerchen am Tag. Sie umfasst eine detaillierte Aufschlüsselung der nicht überschneidenden Schlafphasen sowie kurze Übergangsintervalle zum Wachzustand, die als kurze Wachphasen bezeichnet werden.

  • Schlafsitzung (Sleep): Stellt ein separates Schlafereignis dar (LIGHT-, DEEP-, REM- und AWAKE-Phasenintervalle), das die zusammenhängende Zeitachse der primären Ruhephase unterteilt.
  • Kurzes Erwachen (shortAwakenings): Kurze Übergänge zum Wachzustand oder Erwachen während der Ruhephase. Im Gegensatz zu Standardintervallen für SchlafphasenAWAKE, bei denen die nicht überlappenden, zusammenhängenden Schlafphasen unterteilt werden, sind kurze Wachphasen separate Segmente, die sich mit den umgebenden Schlafphasen überschneiden können. Sie bieten einen detaillierten Einblick in Unruhe und Mikro-Erwachen, ohne die primäre Struktur der Schlafphasen zu stören.
  • Nächtliches Erwachen: Das Erwachen mitten in der Nacht (z. B. zum Trinken) wird durch die Sensorfusion auf dem Gerät (Beschleunigungsmesser, Gyroskop und Schrittzahl) erkannt. In der Web-API können Anwendungen nächtliches Erwachen erkennen, indem sie nach Intervallen filtern, die mit dem Level "wake" (klassischer Schlaf) oder "awake" (Schlafphasen) gekennzeichnet sind.

Beispiel

{
  "name": "sleeps/12345",
  "startTime": "2026-04-20T22:30:00Z",
  "endTime": "2026-04-21T06:30:00Z",
  "sleepType": "STAGES",
  "minutesToFallAsleep": 15,
  "minutesAfterWakeup": 10,
  "sleepStages": [
    {
      "startTime": "2026-04-20T22:30:00Z",
      "endTime": "2026-04-20T23:45:00Z",
      "type": "LIGHT"
    },
    {
      "startTime": "2026-04-20T23:45:00Z",
      "endTime": "2026-04-21T01:15:00Z",
      "type": "DEEP"
    }
  ],
  "shortAwakenings": [
    {
      "startTime": "2026-04-20T23:10:00Z",
      "endTime": "2026-04-20T23:11:30Z",
      "type": "AWAKE"
    }
  ]
}

Schlafeinheit erstellen

Wenn Sie einen Eintrag für eine Schlafeinheit erstellen möchten, senden Sie eine POST-Anfrage an den Endpunkt für sleep-Datenpunkte. Die Antwort enthält das Feld name mit der data-point-id, die in einer Update (Patch)- oder Delete-Anfrage verwendet werden kann.

Anfrage

POST https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints
Authorization: Bearer access-token
Content-Type: application/json

{
  "sleep": {
    "interval": {
      "startTime": "2026-06-07T22:00:00Z",
      "startUtcOffset": "-14400s",
      "endTime": "2026-06-08T06:00:00Z",
      "endUtcOffset": "-14400s"
    },
    "type": "STAGES",
    "stages": [
      {
        "startTime": "2026-06-07T22:00:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-07T22:30:00Z",
        "endUtcOffset": "-14400s",
        "type": "LIGHT"
      },
      {
        "startTime": "2026-06-07T22:30:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-07T23:45:00Z",
        "endUtcOffset": "-14400s",
        "type": "DEEP"
      },
      {
        "startTime": "2026-06-07T23:45:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-08T02:15:00Z",
        "endUtcOffset": "-14400s",
        "type": "LIGHT"
      },
      {
        "startTime": "2026-06-08T02:15:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-08T02:45:00Z",
        "endUtcOffset": "-14400s",
        "type": "REM"
      },
      {
        "startTime": "2026-06-08T02:45:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-08T05:15:00Z",
        "endUtcOffset": "-14400s",
        "type": "LIGHT"
      },
      {
        "startTime": "2026-06-08T05:15:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-08T06:00:00Z",
        "endUtcOffset": "-14400s",
        "type": "REM"
      }
    ]
  }
}

Antwort

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/user-id/dataTypes/sleep/dataPoints/data-point-id",
    "sleep": {
      "interval": {
        "startTime": "2026-06-07T22:00:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-08T06:00:00Z",
        "endUtcOffset": "-14400s"
      },
      "type": "STAGES",
      "stages": [
        {
          "startTime": "2026-06-07T22:00:00Z",
          "startUtcOffset": "-14400s",
          "endTime": "2026-06-07T22:30:00Z",
          "endUtcOffset": "-14400s",
          "type": "LIGHT"
        },
        {
          "startTime": "2026-06-07T22:30:00Z",
          "startUtcOffset": "-14400s",
          "endTime": "2026-06-07T23:45:00Z",
          "endUtcOffset": "-14400s",
          "type": "DEEP"
        },
        {
          "startTime": "2026-06-07T23:45:00Z",
          "startUtcOffset": "-14400s",
          "endTime": "2026-06-08T02:15:00Z",
          "endUtcOffset": "-14400s",
          "type": "LIGHT"
        },
        {
          "startTime": "2026-06-08T02:15:00Z",
          "startUtcOffset": "-14400s",
          "endTime": "2026-06-08T02:45:00Z",
          "endUtcOffset": "-14400s",
          "type": "REM"
        },
        {
          "startTime": "2026-06-08T02:45:00Z",
          "startUtcOffset": "-14400s",
          "endTime": "2026-06-08T05:15:00Z",
          "endUtcOffset": "-14400s",
          "type": "LIGHT"
        },
        {
          "startTime": "2026-06-08T05:15:00Z",
          "startUtcOffset": "-14400s",
          "endTime": "2026-06-08T06:00:00Z",
          "endUtcOffset": "-14400s",
          "type": "REM"
        }
      ]
    }
  }
}

Messwerte zur Schlafeffizienz und Latenz

Zusätzlich zu Schlafphasen und physiologischen Messwerten bietet die API wichtige Messwerte, die die Schlafqualität und den Beginn des Schlafs quantifizieren. Die Schlafeffizienz und die Einschlaflatenz sind klinische Standardmesswerte, die beschreiben, wie effektiv sich ein Nutzer im Verhältnis zur Gesamtzeit im Bett erholt. Sie geben Aufschluss über die Schlafhygiene und die Erholsamkeit des Schlafs.

Schlafeffizienzindex

Die Schlafeffizienz ist ein Standardmesswert, der als Anteil der Schlafzeit an der insgesamt im Bett verbrachten Zeit definiert wird. Die API berechnet die Schlafeffizienz mit der folgenden Formel:

Sleep Efficiency Score = round( (Total Minutes Asleep / Total Minutes In Bed) * 100 )

Der Effizienzindex wird kurz vor der Aufteilung in Schlafphasen berechnet. Die in der API-Antwort zurückgegebenen Gesamtzahl der Schlafminuten (im Feld summary.minutesAsleep) entspricht dem Endergebnis nach der Berechnung der Schlafphasen.

Wenn ein Nutzer oder ein Forscher die Start- oder Endzeit eines Schlafprotokolls manuell ändert, berechnet die API den Schlaf-Effizienz-Wert neu und passt die Schlafphasen entsprechend den Sensordaten an, die innerhalb der neuen Schlafenszeit und Aufwachzeit aufgezeichnet wurden.

Einschlaflatenz

Die Einschlaflatenz ist die Zeit, die vom Zeitpunkt, an dem ein Nutzer einschlafen möchte (Beginn der Zeit „Im Bett“ oder „Licht aus“), bis zum Einschlafen vergeht.

Bei automatisch generierten Logs, die auf der automatischen Erkennung (auto_detect) basieren, ist minutesToFallAsleep standardmäßig 0, da kein expliziter Intent zum Einschlafen protokolliert wurde. Wenn die Startzeiten im Bett manuell aufgezeichnet oder bearbeitet werden (Umwandlung des Logs in manual), berechnet und füllt die API minutesToFallAsleep zusammen mit minutesAfterWakeup aus.

Anleitung für Recherche und manuelle Protokollierung

Wenn Teilnehmer die Start- und Endzeiten im Bett manuell aufzeichnen oder anpassen:

  1. Wenn du die Grenzen im Bett aktualisierst, ändert sich das Intervall timeInBed.
  2. Die Schlafphasen und ‑abschnitte werden automatisch angepasst, um Sensordaten im neuen Zeitraum auszuwerten.
  3. Der Schlafeffizienzindex, minutesToFallAsleep und minutesAfterWakeup werden basierend auf dem aktualisierten Zeitfenster neu berechnet.

Tägliche Ableitungen der Schlaftemperatur

Bei den täglichen Ableitungen der Schlaftemperatur wird die Schwankung der Hauttemperatur eines Nutzers während des Schlafs im Vergleich zu seiner Baseline gemessen. Diese Daten werden in der Regel einmal täglich nach einer längeren Schlafeinheit gemeldet.

Atemfrequenz

Die Atemfrequenz gibt die Anzahl der Atemzüge des Nutzers pro Minute an. Während des Schlafs ist sie ein wichtiger Messwert zur Überwachung der Schlafqualität und potenzieller Störungen. Die API unterstützt die Erfassung der Atemfrequenz (respiratory-rate), tägliche Analysen (daily-respiratory-rate) und Schlafanalysen auf Sitzungsebene (respiratory-rate-sleep-summary).

Herzfrequenzvariabilität (HFV)

Die Herzfrequenzvariabilität (HFV) misst die Unterschiede im Zeitintervall zwischen zwei Herzschlägen. Sie ist ein wichtiger Indikator für den Zustand des autonomen Nervensystems. Eine hohe HFV während des Schlafs deutet in der Regel auf eine bessere Erholung und Tagesform hin, während eine niedrige HFV auf Stress oder Übertraining hindeuten kann. Die API unterstützt HFV-Stichproben (heart-rate-variability) und Tageszusammenfassungen (daily-heart-rate-variability).

Sauerstoffsättigung (SpO2)

Die SpO2 gibt den Prozentsatz des sauerstoffgesättigten Hämoglobins im Verhältnis zur Gesamtmenge des Hämoglobins im Blut an. Die Überwachung der Sauerstoffsättigung während des Schlafs ist wichtig, um potenzielle Atemstörungen zu erkennen und sicherzustellen, dass der Nutzer die ganze Nacht über einen angemessenen Sauerstoffgehalt aufrechterhält. Die API unterstützt SpO2-Stichproben (oxygen-saturation) und Tageszusammenfassungen (daily-oxygen-saturation).

Ganzheitliche Sicht auf Schlaf und Erholung

Jeder Messwert liefert spezifische Informationen, sie sind jedoch eng miteinander verbunden und bieten zusammen einen ganzheitlichen Überblick über die Erholung eines Nutzers. Schlafphasen (Leicht-, Tief- und REM-Schlaf) bilden die strukturelle Grundlage für die Erholung, während physiologische Marker wie HFV und SpO2 angeben, wie der Körper physisch auf diese Erholung reagiert. Ein hochwertiger Schlaf mit optimalem Tiefschlaf korreliert oft mit einer höheren HFV, was auf eine effektive Erholung des autonomen Nervensystems hinweist.

In Kombination mit der Atemfrequenz und den abgeleiteten Schlaftemperaturwerten können Anwendungen potenzielle Störungen erkennen. Ein plötzlicher Anstieg der Atemfrequenz oder eine Abweichung der Schlaftemperatur kann Aufschluss darüber geben, warum ein Nutzer möglicherweise weniger Zeit in erholsamen Schlafphasen verbracht hat. Durch die gleichzeitige Analyse dieser Datentypen können Entwickler eine umfassende Bewertung der Schlafhygiene und langfristiger Gesundheitstrends ermöglichen.

Richtlinien

Beachten Sie bei der Einbindung von Schlafmesswerten in Ihre App die folgenden Richtlinien:

  • Sitzungsdetails: Wenn du die Schlafphasen eines Nutzers (Leicht-, Tief-, REM-Schlaf, Wach) und kurze Wachphasen anzeigen möchtest, frage den Datentyp sleep ab.
  • Nächtliches Erwachen: Wenn du nächtliche Wachereignisse ohne Rohsensordaten erfassen möchtest, sieh dir die sleep-Phasenintervalle an und filtere nach Elementen mit dem Phasentyp AWAKE (oder wake für klassische Schlafprotokolle).
  • Latenz und Effizienz: Verwende minutesToFallAsleep und die Formel für die Schlafeffizienz zur Analyse der Schlaflatenz. minutesToFallAsleep wird ausgefüllt, wenn Schlafprotokolle manuell bearbeitet oder explizit protokolliert werden.
  • Physiologisches Monitoring: Für ein erweitertes Gesundheitsmonitoring kannst du die Daten der Schlafeinheit mit physiologischen Messwerten und Messwerten zur Regeneration wie respiratory-rate-sleep-summary, daily-sleep-temperature-derivations, daily-heart-rate-variability und daily-oxygen-saturation kombinieren.
  • Abstimmung: Verwende den Vorgang reconcile, um dafür zu sorgen, dass sich überschneidende Schlaf-Logs von verschiedenen Geräten (z. B. einem Wearable und einem Matratzensensor) in einem einzigen „Haupt“-Schlafdatensatz zusammengeführt werden.

Gesamtdauer des Tiefschlafs berechnen

So berechnest du die Gesamtzeit, die ein Nutzer in einer bestimmten Nacht im erholsamen Tiefschlaf verbracht hat:

  1. Fragen Sie den Datentyp sleep für den angegebenen Zeitraum ab.
  2. Iterieren Sie die Liste der Phasen und ermitteln Sie Intervalle, in denen type gleich DEEP ist.
  3. Berechne die Dauer (Ende – Start) für jedes Intervall im Tiefschlaf und addiere sie.

Die resultierende Summe ergibt die gesamte physische Dauer des Tiefschlafs für diese Sitzung.

Zurück
Schritte