Tworzenie funkcji związanych ze snem za pomocą interfejsu Google Health API

Interfejs API Google Health udostępnia typy danych, które śledzą schematy snu użytkownika, w tym czas trwania, jakość i wskaźniki fizjologiczne podczas odpoczynku. Te dane pomagają aplikacjom dostarczać statystyki dotyczące regeneracji, higieny snu i długoterminowych trendów zdrowotnych.

Wskaźniki fizjologiczne, takie jak zmienność rytmu serca (HRV), nasycenie tlenem (SpO2) i częstość oddychania, są rejestrowane podczas snu, ponieważ organizm jest wtedy w stabilnym stanie spoczynku. Dzięki temu interfejs API może określić podstawowe parametry zdrowia autonomicznego i oddechowego użytkownika bez zakłóceń spowodowanych przez czynniki stresogenne w ciągu dnia, aktywność fizyczną czy zmienne warunki środowiskowe.

Poznaj różnice między tymi typami danych, aby określić, które dane są odpowiednie dla Twojej aplikacji.

Obsługiwane typy danych

Interfejs API obsługuje te typy danych do pomiaru snu:

Tabela: Typy danych o śnie w interfejsie Google Health API
Typ danych Dostępne operacje
Zakres
Dzienna zmienność rytmu serca
dataType: daily-heart-rate-variability
filter parameter: daily_heart_rate_variability
Typ rekordu: dzienny

Zgodne urządzenia

lista, uzgadnianie .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Dzienne nasycenie tlenem
dataType: daily-oxygen-saturation
filter parameter: daily_oxygen_saturation
Typ rekordu: dzienny

Zgodne urządzenia

lista, uzgadnianie .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Dzienna częstość oddychania
dataType: daily-respiratory-rate
filter parameter: daily_respiratory_rate
Typ rekordu: dzienny

Zgodne urządzenia

lista, uzgadnianie .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Dzienne odchylenia temperatury podczas snu
dataType: daily-sleep-temperature-derivations
filter parameter: daily_sleep_temperature_derivations
Typ rekordu: dzienny

Zgodne urządzenia

lista, uzgadnianie .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Zmienność rytmu serca
dataType: heart-rate-variability
filter parameter: heart_rate_variability
Typ rekordu: Przykładowy

Zgodne urządzenia

lista, uzgadnianie .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Nasycenie tlenem
dataType: oxygen-saturation
filter parameter: oxygen_saturation
Typ rekordu: Przykładowy
Rozdzielczość pamięci masowej: 1 minuta

Zgodne urządzenia

lista, uzgadnianie .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Podsumowanie dotyczące częstości oddechów podczas snu
dataType: respiratory-rate-sleep-summary
filter parameter: respiratory_rate_sleep_summary
Typ rekordu: Przykładowy

Zgodne urządzenia

lista, uzgadnianie .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Sen
dataType: sleep
filter parameter: sleep
Typ rekordu: sesja

Zgodne urządzenia

list, get, reconcile, create, update, batchDelete .sleep.readonly
.sleep.writeonly

sesje snu i krótkie przebudzenia,

Sesja snu (Sleep) reprezentuje odrębne zdarzenie związane ze snem, takie jak pojedynczy sen nocny lub drzemka w ciągu dnia. Obejmuje szczegółowe zestawienie nienakładających się faz snu oraz krótkich przerw na wybudzenie, zwanych krótkimi przebudzeniami.

  • Sesja snu (Sleep): reprezentuje pojedyncze zdarzenie związane ze snem (interwały faz LIGHT, DEEP, REM, AWAKE), które dzielą ciągłą oś czasu głównego odpoczynku.
  • Krótkie wybudzenia (shortAwakenings): krótkie przejścia do stanu czuwania lub wybudzenia, które występują podczas odpoczynku. W odróżnieniu od standardowych interwałów fazy AWAKE (które dzielą niepokrywające się, ciągłe fazy snu) krótkie przebudzenia to odrębne segmenty, które mogą nakładać się na otaczające je fazy snu. Zapewniają one szczegółowy wgląd w niepokój i mikroprzebudzenia bez zakłócania podstawowej struktury faz snu.
  • Wybudzenia w nocy: wybudzenia w nocy (np. wstawanie po wodę) są wykrywane przez połączenie czujników na urządzeniu (akcelerometru, żyroskopu i licznika kroków). Aplikacje mogą wykrywać nocne wybudzenia, filtrując stages pod kątem interwałów z type: "AWAKE" (używanych zarówno w zapisach snu CLASSIC, jak i STAGES) lub sprawdzając outOfBedSegments.

Przykład

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

Tworzenie sesji snu

Aby utworzyć wpis dotyczący sesji snu, wyślij żądanie POST do punktu końcowego punktów danych sleep. Odpowiedź zawiera pole name z wartością data-point-id, której można użyć w żądaniu Update (Patch) lub Delete.

Żądanie

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

Odpowiedź

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

Dane dotyczące efektywności snu i czasu oczekiwania

Oprócz faz snu i wskaźników fizjologicznych interfejs API udostępnia kluczowe dane, które określają jakość snu i moment zasypiania. Efektywność snu i czas do zaśnięcia to standardowe wskaźniki kliniczne, które opisują, jak skutecznie użytkownik odpoczywa w stosunku do łącznego czasu spędzonego w łóżku. Pozwalają one uzyskać wgląd w higienę snu i jakość odpoczynku.

Ocena efektywności snu

Efektywność snu to standardowy wskaźnik definiowany jako stosunek czasu snu do łącznego czasu spędzonego w łóżku. Interfejs API oblicza efektywność snu za pomocą tego wzoru:

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

Ocena wydajności jest obliczana tuż przed podziałem na poziomy (fazy) snu. Łączna liczba minut snu zwracana w odpowiedzi interfejsu API (w polu summary.minutesAsleep) odzwierciedla ostateczny wynik po obliczeniu poziomów snu.

Jeśli użytkownik lub badacz ręcznie zmodyfikuje godzinę rozpoczęcia lub zakończenia zapisu snu, interfejs API ponownie obliczy wynik wydajności snu i dostosuje partycje faz zgodnie z danymi z czujnika zarejestrowanymi w nowych granicach czasu snu i pobudki.

Czas zasypiania

Czas zasypiania to czas, który upływa od momentu, gdy użytkownik zamierza zasnąć (początek czasu „w łóżku” lub „zgaszenia światła”), do momentu, gdy zasypia.

W przypadku dzienników generowanych automatycznie (metadata.manuallyEdited to false) summary.minutesToFallAsleep domyślnie ma wartość "0", ponieważ nie zarejestrowano wyraźnego zamiaru pójścia spać. Gdy godziny rozpoczęcia snu są rejestrowane lub edytowane ręcznie (metadata.manuallyEdited to true), interfejs API oblicza i wypełnia summary.minutesToFallAsleep oraz summary.minutesAfterWakeUp.

Wskazówki dotyczące badań i ręcznego zapisywania danych

Gdy uczestnicy ręcznie rejestrują lub dostosowują godziny rozpoczęcia i zakończenia snu:

  1. Aktualizacja granic czasu spędzonego w łóżku zmienia interval (i summary.minutesInSleepPeriod).
  2. Poziomy i fazy snu są automatycznie dostosowywane, aby ocenić dane z czujnika w nowym oknie.
  3. Ocena efektywności snu, summary.minutesToFallAsleep i summary.minutesAfterWakeUp są ponownie obliczane na podstawie zaktualizowanego przedziału czasu.

Dzienne odchylenia temperatury podczas snu

Dzienne odchylenia temperatury podczas snu mierzą wahania temperatury skóry użytkownika podczas snu w porównaniu z wartością bazową. Te dane są zwykle raportowane raz dziennie po głównej sesji snu.

Częstość oddychania

Częstość oddechów to liczba oddechów użytkownika na minutę. Podczas snu jest to kluczowy wskaźnik do monitorowania jakości snu i potencjalnych zaburzeń. Interfejs API obsługuje próbkowanie częstości oddychania (respiratory-rate), podsumowania dzienne (daily-respiratory-rate) i informacje o śnie na poziomie sesji (respiratory-rate-sleep-summary).

Zmienność rytmu serca (HRV)

HRV mierzy odstępy między uderzeniami serca. Jest to kluczowy wskaźnik stanu autonomicznego układu nerwowego. Wysoka zmienność rytmu serca podczas snu ogólnie oznacza lepszą regenerację i gotowość, a niska może wskazywać na stres lub przetrenowanie. Interfejs API obsługuje próbki zmienności rytmu serca (heart-rate-variability) i podsumowania dzienne (daily-heart-rate-variability).

Nasycenie tlenem

Saturacja krwi (SpO2) to procent hemoglobiny nasyconej tlenem w stosunku do całkowitej ilości hemoglobiny we krwi. Monitorowanie SpO2 podczas snu pomaga wykrywać potencjalne zaburzenia oddychania i potwierdza, czy użytkownik utrzymuje odpowiedni poziom tlenu przez całą noc. Interfejs API obsługuje próbki SpO2 (oxygen-saturation) i podsumowania dzienne (daily-oxygen-saturation).

Gdy wysyłasz zapytanie o oxygen-saturation na poziomie minut, interfejs Google Health API zwraca tylko zweryfikowane punkty danych i odfiltrowuje nieprawidłowe pomiary spowodowane ruchem ramienia, luźnym dopasowaniem do nadgarstka lub niską wiarygodnością czujnika (poniżej 50%), a także odczyty sąsiadujące z szumem ruchu. Ponieważ nieprawidłowe minuty są wykluczane, dane na poziomie minut mogą być rozproszone i mogą występować luki w sygnaturach czasowych. Zarówno oxygen-saturation, jak i daily-oxygen-saturation korzystają z tych samych zweryfikowanych odczytów. Szczegółowe informacje o kryteriach weryfikacji znajdziesz w sekcji Filtrowanie i prawidłowość danych SpO2 na poziomie minutowym.

Kompleksowy obraz zdrowia i regeneracji podczas snu

Każdy wskaźnik dostarcza konkretnych informacji, ale są one ze sobą ściśle powiązane i razem dają pełny obraz regeneracji użytkownika. Fazy snu (płytki, głęboki, REM) stanowią podstawę odpoczynku, a wskaźniki fizjologiczne, takie jak HRV i SpO2, pokazują, jak organizm reaguje na ten odpoczynek. Na przykład wysokiej jakości sesja snu z optymalną fazą snu głębokiego często koreluje z wyższą zmiennością rytmu serca, co oznacza skuteczną regenerację autonomicznego układu nerwowego.

Połączenie tych danych z częstością oddychania i temperaturą podczas snu pozwala aplikacjom identyfikować potencjalne zaburzenia. Nagły wzrost częstości oddechów lub odchylenie temperatury podczas snu mogą wyjaśnić, dlaczego użytkownik spędził mniej czasu w fazach snu regeneracyjnego. Analizując te typy danych razem, deweloperzy mogą kompleksowo ocenić higienę snu i długoterminowe trendy zdrowotne.

Wytyczne

Podczas integrowania danych o śnie z aplikacją postępuj zgodnie z tymi wskazówkami:

  • Szczegóły sesji: aby wyświetlić fazy snu użytkownika (płytki, głęboki, REM, czuwanie) i krótkie przebudzenia, prześlij zapytanie o typ danych sleep.
  • Wybudzenia nocne: aby śledzić wybudzenia w nocy bez nieprzetworzonych strumieni danych z czujników, sprawdź interwały fazy sleep i odfiltruj elementy z type: "AWAKE" (zarówno w przypadku zapisów snu STAGES, jak i CLASSIC) lub sprawdź outOfBedSegments.
  • Czas oczekiwania i efektywność: używaj summary.minutesToFallAsleep i wzoru na efektywność snu do analizy czasu oczekiwania na sen. Pamiętaj, że pole summary.minutesToFallAsleep jest wypełniane, gdy zapisy snu są edytowane ręcznie (metadata.manuallyEdited to true) lub wyraźnie zapisywane.
  • Monitorowanie parametrów fizjologicznych: aby uzyskać zaawansowane monitorowanie stanu zdrowia, połącz dane z sesji snu ze wskaźnikami fizjologicznymi i dotyczącymi regeneracji, takimi jak respiratory-rate-sleep-summary, daily-sleep-temperature-derivations, daily-heart-rate-variability i daily-oxygen-saturation.
  • Uzgodnienie: użyj operacji reconcile, aby upewnić się, że pokrywające się zapisy snu z różnych urządzeń (np. z urządzenia do noszenia i czujnika w materacu) są scalane w jeden „główny” zapis snu.

obliczyć łączny czas snu głębokiego,

Aby obliczyć łączny czas, jaki użytkownik spędził w fazie głębokiego snu, który zapewnia wypoczynek, w ciągu danej nocy:

  1. Wyślij zapytanie o typ danych sleep w określonym zakresie czasu.
  2. Przejrzyj listę etapów i znajdź interwały, w których type to DEEP.
  3. Oblicz czas trwania (czas zakończenia – czas rozpoczęcia) każdego interwału snu głębokiego i zsumuj je.

Wynikowa suma to łączny czas trwania snu głębokiego podczas danej sesji.