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:
| Typ danych | Dostępne operacje |
Zakres |
|---|---|---|
|
Dzienna zmienność rytmu serca
dataType:
daily-heart-rate-variabilityfilter 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-saturationfilter 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-ratefilter 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-derivationsfilter parameter: daily_sleep_temperature_derivations
Typ rekordu: dzienny
Obsługa webhooków
Przewodnik po funkcjach związanych ze zdrowiem
Przewodnik po funkcjach związanych ze snem
Przewodnik po funkcjach związanych z temperaturą skóry
Zgodne urządzenia
|
lista, uzgadnianie | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Zmienność rytmu serca
dataType:
heart-rate-variabilityfilter 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-saturationfilter 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-summaryfilter 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:
sleepfilter 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 fazLIGHT,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 fazyAWAKE(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
stagespod kątem interwałów ztype: "AWAKE"(używanych zarówno w zapisach snuCLASSIC, jak iSTAGES) lub sprawdzającoutOfBedSegments.
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:
- Aktualizacja granic czasu spędzonego w łóżku zmienia
interval(isummary.minutesInSleepPeriod). - Poziomy i fazy snu są automatycznie dostosowywane, aby ocenić dane z czujnika w nowym oknie.
- Ocena efektywności snu,
summary.minutesToFallAsleepisummary.minutesAfterWakeUpsą 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
sleepi odfiltruj elementy ztype: "AWAKE"(zarówno w przypadku zapisów snuSTAGES, jak iCLASSIC) lub sprawdźoutOfBedSegments. - Czas oczekiwania i efektywność: używaj
summary.minutesToFallAsleepi wzoru na efektywność snu do analizy czasu oczekiwania na sen. Pamiętaj, że polesummary.minutesToFallAsleepjest wypełniane, gdy zapisy snu są edytowane ręcznie (metadata.manuallyEditedtotrue) 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-variabilityidaily-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:
- Wyślij zapytanie o typ danych
sleepw określonym zakresie czasu. - Przejrzyj listę etapów i znajdź interwały, w których
typetoDEEP. - 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.