Schlaffunktionen mit der Google Health API entwickeln

Die Google Health API bietet Datentypen, mit denen der Schlafrhythmus eines Nutzers erfasst werden kann, einschließlich Dauer, Qualität und physiologischer Messwerte während der Ruhephasen. Anhand dieser Messwerte können Anwendungen Informationen zur 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 dann in einem stabilen Ruhezustand befindet. So kann die API einen Referenzwert für die autonome und respiratorische Gesundheit des Nutzers erfassen, ohne dass dieser durch Stressfaktoren am Tag, körperliche Aktivität oder wechselnde Umgebungsbedingungen beeinflusst wird.

Machen Sie sich mit den Unterschieden zwischen diesen Datentypen vertraut, um zu entscheiden, welche Messwerte für Ihre Anwendung geeignet sind.

Unterstützte Datentypen

Die API unterstützt die folgenden Datentypen für die Schlafmessung:

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 Abweichungen der Temperatur beim Schlafen
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
Speicherauflösung: 1 Minute

Kompatible Geräte

list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Analyse 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. einen Nachtschlaf oder ein Nickerchen am Tag. Sie enthält eine detaillierte Aufschlüsselung der sich nicht überschneidenden Schlafphasen sowie kurze Übergangsintervalle, die als kurze Wachphasen bezeichnet werden.

  • Schlafeinheit (Sleep): Stellt ein einzelnes Schlafereignis dar (LIGHT, DEEP, REM, AWAKE-Phasenintervalle), das die zusammenhängende Zeitachse der primären Ruhephase unterteilt.
  • Kurzes Aufwachen (shortAwakenings): Kurze Wachphasen oder Aufwachen während der Ruhephase. Im Gegensatz zu Standard-AWAKE-Phasenintervallen (die den nicht überlappenden, zusammenhängenden Schlafphasenverlauf unterteilen) sind kurze Aufwachphasen separate Segmente, die sich mit den umgebenden Schlafphasen überschneiden können. Sie bieten detaillierte Einblicke in Unruhe und Mikroaufwachphasen, ohne die primäre Struktur der Schlafphasen zu stören.
  • Nächtliches Aufwachen: Nächtliches Aufwachen (z. B. um etwas zu trinken) wird durch die Sensorfusion auf dem Gerät (Beschleunigungsmesser, Gyroskop und Schrittzahl) erkannt. Anwendungen können nächtliches Erwachen erkennen, indem sie stages nach Intervallen mit type: "AWAKE" filtern (wird sowohl in CLASSIC- als auch in STAGES-Schlafprotokollen verwendet) oder outOfBedSegments prüfen.

Beispiel

{
  "name": "users/user-id/dataTypes/sleep/dataPoints/data-point-id",
  "sleep": {
    "interval": {
      "startTime": "2026-04-20T22:30:00Z",
      "startUtcOffset": "-14400s",
      "endTime": "2026-04-21T06:30:00Z",
      "endUtcOffset": "-14400s"
    },
    "type": "STAGES",
    "stages": [
      {
        "startTime": "2026-04-20T22:30:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-04-20T23:45:00Z",
        "endUtcOffset": "-14400s",
        "type": "LIGHT"
      },
      {
        "startTime": "2026-04-20T23:45:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-04-21T01:15:00Z",
        "endUtcOffset": "-14400s",
        "type": "DEEP"
      }
    ],
    "shortAwakenings": [
      {
        "startTime": "2026-04-20T23:10:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-04-20T23:11:30Z",
        "endUtcOffset": "-14400s",
        "type": "AWAKE"
      }
    ],
    "summary": {
      "minutesInSleepPeriod": "480",
      "minutesAsleep": "455",
      "minutesAwake": "25",
      "minutesToFallAsleep": "15",
      "minutesAfterWakeUp": "10"
    }
  }
}

Schlafeinheit erstellen

Wenn du einen Eintrag für eine Schlafeinheit erstellen möchtest, sende eine POST-Anfrage an den Datenpunkt-Endpunkt sleep. Die Antwort enthält das Feld name mit dem data-point-id, das in einer Update- (Patch-) oder Löschanfrage 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"
        }
      ]
    }
  }
}

Schlafeinheiten abfragen und abgleichen

Wenn du den Schlafverlauf eines Nutzers abrufen möchtest, frage den reconcile-Endpunkt und nicht den list-Endpunkt ab. Wenn ein Nutzer den Schlaf über mehrere Quellen aufzeichnet, z. B. über einen Wearable-Tracker und Health Connect, gibt list alle sich überschneidenden Datensätze zurück. Wenn du die Rohdaten für list addierst, kann es sein, dass die tägliche Schlafdauer doppelt gezählt wird. Der Endpunkt reconcile dedupliziert sich überschneidende Protokolle in einen einzigen Stream und identifiziert die primäre Schlafeinheit jedes Tages, indem sleep.metadata.mainSleep auf true gesetzt wird. Einen Vergleich der beiden Endpunkte finden Sie unter Endpunkte „list“ und „reconcile“ vergleichen.

Beachten Sie beim Abfragen von sleep mit list oder reconcile die folgenden Einschränkungen für Filter und Paginierung:

  1. Filtern Sie sleep-Abfragen nur nach der Endzeit der Sitzung mit sleep.interval.end_time (physische Zeit in UTC) oder sleep.interval.civil_end_time (lokale bürgerliche Zeit). Kombinieren Sie die Unter- und Obergrenze mit den Vergleichsoperatoren >= und < mit AND.
  2. Filtern Sie sleep-Abfragen nicht nach Startzeit oder mit OR. Wenn Sie nach sleep.interval.start_time oder sleep.interval.civil_start_time filtern, wird der Fehler 400 Bad Request (INVALID_ARGUMENT) mit dem Grund INVALID_DATA_POINT_FILTER_DATA_TYPE_MEMBER zurückgegeben. Die Verwendung von OR gibt den Fehler 400 Bad Request (INVALID_ARGUMENT) mit der Ursache INVALID_DATA_POINT_FILTER_EXPRESSION_STRUCTURE zurück. Informationen zur Syntax finden Sie im Leitfaden zum Filtern von Daten.
  3. Sowohl list als auch reconcile erzwingen einen Standard- und Höchstwert für pageSize von 25 für sleep. Wenn Sie einen pageSize-Wert übergeben, der größer als 25 ist, wird der Wert von der API auf 25 begrenzt. Wenn der Wert negativ ist, wird der Fehler 400 Bad Request zurückgegeben. Wenn du den Schlafverlauf mehrerer Wochen synchronisieren möchtest, verwende nextPageToken, bis das Token leer ist. Weitere Informationen finden Sie unter Verlaufsdaten abfragen.

Mit der folgenden Anfrage werden beispielsweise abgeglichene Schlafeinheiten abgefragt, die innerhalb eines zweiwöchigen Zeitraums enden:

Anfrage

GET https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints:reconcile
  ?filter=sleep.interval.civil_end_time >= "2026-03-01"
  AND sleep.interval.civil_end_time < "2026-03-15"
  &pageSize=25
Authorization: Bearer access-token
Accept: application/json

Antwort

{
  "dataPoints": [
    {
      "dataPointName": "users/user-id/dataTypes/sleep/dataPoints/data-point-id",
      "sleep": {
        "interval": {
          "startTime": "2026-03-03T20:57:30Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T04:41:30Z",
          "endUtcOffset": "0s"
        },
        "type": "STAGES",
        "stages": [
          {
            "startTime": "2026-03-03T20:57:30Z",
            "startUtcOffset": "0s",
            "endTime": "2026-03-03T20:59:30Z",
            "endUtcOffset": "0s",
            "type": "AWAKE"
          },
          {
            "startTime": "2026-03-04T04:07:30Z",
            "startUtcOffset": "0s",
            "endTime": "2026-03-04T04:41:30Z",
            "endUtcOffset": "0s",
            "type": "AWAKE"
          }
        ],
        "metadata": {
          "stagesStatus": "SUCCEEDED",
          "processed": true,
          "mainSleep": true
        },
        "summary": {
          "minutesInSleepPeriod": "464",
          "minutesAfterWakeUp": "0",
          "minutesToFallAsleep": "0",
          "minutesAsleep": "407",
          "minutesAwake": "57",
          "stagesSummary": [
            {
              "type": "AWAKE",
              "minutes": "56",
              "count": "12"
            },
            {
              "type": "LIGHT",
              "minutes": "198",
              "count": "19"
            },
            {
              "type": "DEEP",
              "minutes": "114",
              "count": "10"
            },
            {
              "type": "REM",
              "minutes": "94",
              "count": "4"
            }
          ]
        }
      }
    }
  ],
  "nextPageToken": "Xm5h-6L0viZxIlRuWjx5bmvy98zj85uG34tuMn16mu2pntsnZI32iqhq"
}

Messwerte zur Schlafeffizienz und ‑latenz

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

Schlafeffizienzindex

Die Schlafeffizienz ist ein Standardmesswert, der als der Anteil der Zeit definiert ist, die du im Verhältnis zur Gesamtzeit im Bett schläfst. 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 der Schlafphasen berechnet. Die in der API-Antwort zurückgegebene Gesamtzahl der Schlafminuten (im Feld summary.minutesAsleep) spiegelt das Endergebnis nach der Berechnung der Schlafphasen wider.

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

Einschlaflatenz

Die Einschlaflatenz misst die Zeit, die vergeht, bis ein Nutzer einschläft, nachdem er sich vorgenommen hat, einzuschlafen (Beginn der Zeit im Bett oder „Licht aus“).

Bei automatisch generierten Protokollen (metadata.manuallyEdited ist false) wird summary.minutesToFallAsleep standardmäßig auf "0" gesetzt, da keine explizite Absicht, einzuschlafen, protokolliert wurde. Wenn die Startzeiten im Bett manuell aufgezeichnet oder bearbeitet werden (metadata.manuallyEdited ist true), berechnet die API summary.minutesToFallAsleep und füllt es zusammen mit summary.minutesAfterWakeUp aus.

Anleitung für Recherche und manuelles Logging

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

  1. Wenn du die Bettgeh- und Aufstehzeiten änderst, werden auch die Schlaf-interval (und summary.minutesInSleepPeriod) aktualisiert.
  2. Die Schlafphasen und ‑stufen werden automatisch angepasst, um die Sensordaten innerhalb des neuen Zeitfensters auszuwerten.
  3. Der Schlafeffizienz-Score, summary.minutesToFallAsleep und summary.minutesAfterWakeUp werden anhand des aktualisierten Zeitfensters neu berechnet.

Tägliche Abweichungen der Temperatur beim Schlafen

Die täglichen Abweichungen der Temperatur beim Schlafen messen die Schwankungen der Hauttemperatur eines Nutzers während des Schlafs im Vergleich zu seinem Referenzwert. Diese Daten werden in der Regel einmal täglich nach einer längeren Schlafeinheit gemeldet.

Atemfrequenz

Die Atemfrequenz gibt die Anzahl der Atemzüge pro Minute an. Während des Schlafs ist sie ein wichtiger Messwert für die Schlafqualität und mögliche Störungen. Die API unterstützt die Atemfrequenz-Stichprobe (respiratory-rate), tägliche Zusammenfassungen (daily-respiratory-rate) und Schlafanalyse auf Sitzungsebene (respiratory-rate-sleep-summary).

Herzfrequenzvariabilität (HFV)

Die 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 im Schlaf bedeutet im Allgemeinen eine bessere Erholung und Tagesform, während eine niedrige HFV auf Stress oder Übertraining hinweisen kann. Die API unterstützt HFV-Stichproben (heart-rate-variability) und tägliche Zusammenfassungen (daily-heart-rate-variability).

Sauerstoffsättigung

Die Sauerstoffsättigung (SpO2) gibt den Prozentsatz des sauerstoffgesättigten Hämoglobins im Verhältnis zur Gesamtmenge des Hämoglobins im Blut an. Die Überwachung der SpO2 während des Schlafs hilft, potenzielle Atemstörungen zu erkennen und zu bestätigen, ob der Nutzer die ganze Nacht über einen ausreichenden Sauerstoffgehalt hat. Die API unterstützt SpO2-Stichproben (oxygen-saturation) und tägliche Zusammenfassungen (daily-oxygen-saturation).

Wenn du oxygen-saturation-Daten auf Minutenebene abfragst, gibt die Google Health API nur validierte Datenpunkte zurück und filtert ungültige Messungen heraus, die durch Armbewegungen, einen lockeren Sitz am Handgelenk oder eine geringe Sensorzuverlässigkeit (unter 50 %) verursacht wurden, sowie Messwerte, die durch Bewegungsrauschen beeinträchtigt wurden. Da ungültige Minuten ausgeschlossen werden, kann die Abdeckung auf Minutenebene dünn sein und es sind Zeitstempellücken zu erwarten. Sowohl oxygen-saturation als auch daily-oxygen-saturation basieren auf denselben validierten Messwerten. Weitere Informationen zu den Validierungskriterien findest du unter SpO2-Filterung und Datengültigkeit auf Minutenebene.

Ganzheitlicher Überblick über Schlaf und Erholung

Jeder Messwert liefert zwar spezifische Informationen, sie sind jedoch eng miteinander verknüpft und bieten zusammen einen ganzheitlichen Überblick über die Erholung eines Nutzers. Die Schlafphasen (Leicht-, Tief- und REM-Schlaf) bilden die strukturelle Grundlage der Erholung, während physiologische Marker wie die HFV und die SpO2 anzeigen, wie der Körper physisch auf diese Erholung reagiert. Beispielsweise korreliert eine Schlafeinheit mit hoher Qualität und optimalem Tiefschlaf oft mit einer höheren HFV, was auf eine effektive Erholung des autonomen Nervensystems hindeutet.

In Kombination mit der Atemfrequenz und der Schlaftemperatur können Anwendungen so potenzielle Störungen erkennen. Ein plötzlicher Anstieg der Atemfrequenz oder eine Abweichung der Schlaftemperatur können erklären, warum ein Nutzer möglicherweise weniger Zeit in erholsamen Schlafphasen verbracht hat. Durch die gemeinsame Analyse dieser Datentypen können Entwickler eine umfassende Bewertung der Schlafhygiene und langfristiger Gesundheitstrends vornehmen.

Richtlinien

Beachte die folgenden Richtlinien, wenn du Schlafstatistiken in deine App einbindest:

  • Sitzungsdetails: Wenn du die Schlafphasen eines Nutzers (Leicht, Tief, REM, Wach) und kurze Aufwachphasen anzeigen möchtest, frage den Datentyp sleep ab.
  • Nächtliches Aufwachen: Wenn du nächtliche Aufwachereignisse ohne Rohsensordatenströme erfassen möchtest, prüfe die sleep-Phasenintervalle und filtere nach Elementen mit type: "AWAKE" (sowohl für STAGES- als auch für CLASSIC-Schlafprotokolle) oder prüfe outOfBedSegments.
  • Latenz und Effizienz: Verwenden Sie summary.minutesToFallAsleep und die Formel für die Schlafeffizienz, um die Schlaflatenz zu analysieren. Beachte, dass summary.minutesToFallAsleep ausgefüllt wird, wenn Schlafprotokolle manuell bearbeitet (metadata.manuallyEdited ist true) oder explizit protokolliert werden.
  • Physiologisches Monitoring: Für ein erweitertes Gesundheitsmonitoring können die Daten der Schlafeinheit mit physiologischen und Erholungsmesswerten wie respiratory-rate-sleep-summary, daily-sleep-temperature-derivations, daily-heart-rate-variability und daily-oxygen-saturation kombiniert werden.

Gesamtzeit im Tiefschlaf berechnen

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

  1. Fragt den Datentyp sleep für den angegebenen Zeitraum ab.
  2. Iterieren Sie durch die Liste der Phasen und identifizieren Sie Intervalle, in denen der type DEEP ist.
  3. Berechne die Dauer (Endzeit – Startzeit) für jedes Tiefschlafintervall und addiere sie.

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