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

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

Wskaźniki fizjologiczne, takie jak zmienność rytmu serca (HRV), nasycenie krwi tlenem (SpO2) i częstość oddychania, są rejestrowane w trakcie snu, ponieważ organizm znajduje się wtedy w stabilnym stanie spoczynku. Dzięki temu interfejs API może rejestrować podstawowe dane dotyczące autonomicznego układu nerwowego i zdrowia układu oddechowego użytkownika bez zakłóceń spowodowanych przez czynniki stresogenne w ciągu dnia, aktywność fizyczną lub zmienne warunki środowiskowe.

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

Obsługiwane typy danych

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

Tabela. Typy danych snu 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
Codzienne 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ść oddechów
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
Codzienne wyliczenia 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: Próbka

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: Próbka

Zgodne urządzenia
lista, uzgadnianie .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Podsumowanie snu na podstawie częstości oddechów
dataType: respiratory-rate-sleep-summary
filter parameter: respiratory_rate_sleep_summary
Typ rekordu: Próbka

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) to pojedyncze zdarzenie związane ze snem, np. sen w nocy lub drzemka w ciągu dnia. Obejmuje szczegółowe zestawienie niepokrywających się faz snu oraz krótkich okresów przejściowych do stanu czuwania, zwanych krótkimi przebudzeniami.

  • Sesja snu (Sleep): reprezentuje odrębne zdarzenie snu (LIGHT, DEEP, REM, AWAKE – przedziały czasowe poszczególnych faz), które dzielą ciągłą oś czasu głównego odpoczynku.
  • Krótkie przebudzenia (shortAwakenings): krótkie przejścia do stanu czuwania lub przebudzenia, które występują podczas odpoczynku. W przeciwieństwie do standardowych AWAKEprzedziałów faz snu (które dzielą niepokrywające się, ciągłe fazy snu) krótkie przebudzenia to odrębne segmenty, które mogą się pokrywać z otaczającymi je fazami snu. Zapewniają szczegółowy wgląd w niepokój i mikroprzebudzenia bez zakłócania podstawowej struktury faz snu.
  • Przebudzenia w nocy: przebudzenia w nocy (np. wstawanie po wodę) są identyfikowane przez połączenie danych z czujników na urządzeniu (akcelerometru, żyroskopu i licznika kroków). W interfejsie Web API aplikacje mogą wykrywać nocne przebudzenia, filtrując interwały oznaczone poziomem "wake" (klasyczny sen) lub "awake" (sen w fazach).

Przykład

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

Tworzenie sesji snu

Aby utworzyć wpis sesji snu, wyślij żądanie POST do punktu końcowego sleep data points. 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 i czasu oczekiwania snu

Oprócz faz snu i danych fizjologicznych interfejs API udostępnia kluczowe dane, które określają jakość snu i czas zasypiania. Efektywność snu i latencja zasypiania to standardowe wskaźniki kliniczne, które opisują, jak skutecznie użytkownik odpoczywa w stosunku do całkowitego czasu spędzonego w łóżku. Dostarczają one informacji o higienie snu i jakości odpoczynku.

Ocena efektywności snu

Efektywność snu to standardowa wartość zdefiniowana jako odsetek czasu spędzonego na śnie w stosunku do całkowitego 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 efektywności jest obliczana tuż przed podziałem na poziomy snu (fazy). Łączna liczba minut snu zwrócona 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 dziennika snu, interfejs API ponownie obliczy wynik efektywności snu i dostosuje podział na fazy snu na podstawie danych z czujników zarejestrowanych w nowych godzinach snu i pobudki.

Latencja zasypiania

Latencja zasypiania to czas, który upływa od momentu, w którym użytkownik zamierza zasnąć (początek czasu „w łóżku” lub „zgaszone światło”), do momentu zaśnięcia.

W przypadku dzienników generowanych automatycznie za pomocą automatycznego wykrywania (auto_detect) wartość minutesToFallAsleep jest domyślnie ustawiona na 0, ponieważ nie zarejestrowano intencji bezpośredniej zaśnięcia. Gdy czas rozpoczęcia snu jest rejestrowany lub edytowany ręcznie (przekształcany w manual), interfejs API oblicza i wypełnia pole minutesToFallAsleep wraz z minutesAfterWakeup.

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

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

  1. Aktualizacja granic w ramach reklamy zmienia interwał timeInBed.
  2. Poziomy snu i podział na fazy snu automatycznie dostosowują się do oceny danych z czujnika w nowym oknie.
  3. Ocena efektywności snu, minutesToFallAsleep i minutesAfterWakeup są ponownie obliczane na podstawie zaktualizowanego przedziału czasu.

Codzienne wyliczanie temperatury podczas snu

Codzienne dane dotyczące temperatury podczas snu mierzą wahania temperatury skóry użytkownika podczas snu w porównaniu z wartością bazową. Dane te są zwykle raportowane raz dziennie po dłuższej sesji snu.

Częstość oddychania

Częstość oddechów to liczba oddechów użytkownika na minutę. Podczas snu jest to kluczowy wskaźnik 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 podsumowania snu na poziomie sesji (respiratory-rate-sleep-summary).

Zmienność rytmu serca (HRV)

HRV to miara odstępów między uderzeniami serca. Jest to kluczowy wskaźnik stanu autonomicznego układu nerwowego. Wysoka zmienność rytmu serca podczas snu zwykle oznacza lepszą regenerację i gotowość, a niska zmienność rytmu serca 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 (SpO2)

SpO2 to procent hemoglobiny wysyconej tlenem w stosunku do całkowitej ilości hemoglobiny we krwi. Monitorowanie SpO2 podczas snu ma kluczowe znaczenie dla wykrywania potencjalnych zaburzeń oddychania i zapewnienia odpowiedniego poziomu tlenu przez całą noc. Interfejs API obsługuje próbki SpO2 (oxygen-saturation) i dzienne podsumowania (daily-oxygen-saturation).

Holistyczny widok zdrowia snu i regeneracji

Każdy z tych wskaźników 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 markery fizjologiczne, takie jak HRV i SpO2, wskazują, jak organizm reaguje na ten odpoczynek. Na przykład wysokiej jakości sen z optymalną fazą snu głębokiego często wiąże się z wyższym poziomem HRV, co oznacza efektywną regenerację autonomicznego układu nerwowego.

Połączenie tych danych z częstością oddychania i temperaturą podczas snu pozwala aplikacjom wykrywać potencjalne zaburzenia. Nagły wzrost częstotliwości oddechu lub odchylenie temperatury ciała podczas snu mogą wyjaśniać, dlaczego użytkownik spędził mniej czasu w fazach regeneracyjnych. Analizując te typy danych jednocześnie, deweloperzy mogą zapewnić kompleksową ocenę higieny snu i długoterminowych trendów zdrowotnych.

Wytyczne

Podczas integrowania danych snu w aplikacji postępuj zgodnie z tymi wskazówkami:

  • Szczegóły sesji: aby wyświetlić fazy snu użytkownika (płytki, głęboki, REM, przebudzenie) i krótkie przebudzenia, wyślij zapytanie o typ danych sleep.
  • Nocne przebudzenia: aby śledzić przebudzenia w nocy bez surowych strumieni danych z czujników, sprawdź przedziały etapów sleep i odfiltruj elementy z typem etapu AWAKE (lub wake w przypadku klasycznych dzienników snu).
  • Opóźnienie i efektywność: użyj minutesToFallAsleep i wzoru na efektywność snu do analizy opóźnienia snu. Pamiętaj, że pole minutesToFallAsleep jest wypełniane, gdy dzienniki snu są edytowane ręcznie lub rejestrowane w sposób jawny.
  • Monitorowanie fizjologiczne: aby uzyskać zaawansowane monitorowanie zdrowia, połącz dane sesji snu z danymi fizjologicznymi i danymi 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 mieć pewność, że nakładające się na siebie logi snu z różnych urządzeń (np. urządzenia do noszenia i czujnika na materacu) zostaną połączone w jeden „główny” rekord snu.

Obliczanie łącznego czasu snu głębokiego

Aby obliczyć łączny czas, jaki użytkownik spędził w fazie regenerującego snu głębokiego w konkretną noc:

  1. Wyszukaj typ danych sleep w określonym zakresie czasu.
  2. Przejdź przez listę etapów i zidentyfikuj przedziały, w których type jest DEEP.
  3. Oblicz czas trwania (czas zakończenia – czas rozpoczęcia) każdego przedziału snu głębokiego i zsumuj je.

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

Wstecz
Etapy