Google Health API ile uyku deneyimleri geliştirme

Google Health API, kullanıcının uyku düzenini takip eden veri türleri sağlar. Bu türler arasında dinlenme sırasındaki süre, kalite ve fizyolojik metrikler yer alır. Bu metrikler, uygulamaların toparlanma, uyku hijyeni ve uzun vadeli sağlık trendleri hakkında analizler sunmasına yardımcı olur.

Nabız değişkenliği (HRV), oksijen doygunluğu (SpO2) ve solunum hızı gibi fizyolojik metrikler, vücut dengeli ve dinlenme durumunda olduğundan özellikle uyku sırasında kaydedilir. Bu sayede API, kullanıcının otonom ve solunum sağlığıyla ilgili temel bilgileri gündüz yaşanan stres, fiziksel aktivite veya değişen çevre koşullarının etkisini hesaba katmadan yakalayabilir.

Uygulamanıza hangi metriklerin uygun olduğunu belirlemek için bu veri türleri arasındaki farkları anlayın.

Desteklenen veri türleri

API, uyku ölçümü için aşağıdaki veri türlerini destekler:

Tablo: Google Health API uyku verisi türleri
Veri türü Kullanılabilir
işlemler		 Kapsam
Günlük Nabız Değişkenliği
dataType: daily-heart-rate-variability
filter parameter: daily_heart_rate_variability
Kayıt türü: Günlük

Uyumlu cihazlar
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Günlük Oksijen Yoğunluğu
dataType: daily-oxygen-saturation
filter parameter: daily_oxygen_saturation
Kayıt türü: Günlük

Uyumlu cihazlar
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Günlük Solunum Hızı
dataType: daily-respiratory-rate
filter parameter: daily_respiratory_rate
Kayıt türü: Günlük

Uyumlu cihazlar
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Günlük Uyku Sıcaklığı Türevleri
dataType: daily-sleep-temperature-derivations
filter parameter: daily_sleep_temperature_derivations
Kayıt türü: Günlük

Uyumlu cihazlar
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Nabız Değişkenliği
dataType: heart-rate-variability
filter parameter: heart_rate_variability
Kayıt türü: Örnek

Uyumlu cihazlar
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Oksijen Doygunluğu
dataType: oxygen-saturation
filter parameter: oxygen_saturation
Kayıt türü: Örnek

Uyumlu cihazlar
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Solunum Hızı Uyku Özeti
dataType: respiratory-rate-sleep-summary
filter parameter: respiratory_rate_sleep_summary
Kayıt türü: Örnek

Uyumlu cihazlar
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Uyku
dataType: sleep
filter parameter: sleep
Kayıt türü: Oturum

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

Uyku oturumları ve kısa uyanmalar

Uyku seansı (Sleep), tek bir gece uykusu veya gündüz uykusu gibi ayrı bir uyku etkinliğini ifade eder. Bu aşamada, kısa uyanmalar olarak bilinen kısa uyanıklık geçiş aralıklarının yanı sıra çakışmayan uyku aşamalarının ayrıntılı bir dökümü yer alır.

  • Uyku Oturumu (Sleep): Ana dinlenmenin kesintisiz zaman çizelgesini bölümlere ayıran ayrı bir uyku etkinliğini (LIGHT, DEEP, REM, AWAKE aşama aralıkları) gösterir.
  • Kısa uyanmalar (shortAwakenings): Dinlenme sırasında meydana gelen kısa uyanma geçişleri veya uyanmalar. Çakışmayan bitişik uyku aşaması ilerlemesini bölen standart AWAKE aşama aralıklarının (stage intervals) aksine, kısa uyanmalar, çevreleyen uyku aşamalarıyla çakışabilen ayrı segmentlerdir. Birincil uyku aşaması yapısını bozmadan huzursuzluk ve mikro uyanmalar hakkında ayrıntılı bilgi verir.
  • Gece Uyanmaları: Gece yarısı uyanmaları (ör. su içmek için kalkma), cihaz üzerinde sensör birleştirme (ivme ölçer, jiroskop ve adım sayısı) ile belirlenir. Web API'sinde uygulamalar, "wake" (klasik uyku) veya "awake" (uyku aşamaları) seviyesiyle işaretlenmiş aralıkları filtreleyerek gece uyanmalarını tespit edebilir.

Örnek

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

Uyku seansı oluşturma

Uyku seansı girişi oluşturmak için sleep veri noktaları uç noktasına POST isteği gönderin. Yanıtta, name alanını içeren data-point-id bulunur. Bu alan, Güncelleme (Yama) veya Silme isteğinde kullanılabilir.

İstek

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

Yanıt

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

Uyku verimliliği ve gecikme metrikleri

API, uyku aşamaları ve fizyolojik metriklerin yanı sıra uyku kalitesini ve uykuya dalma süresini ölçen temel metrikler de sağlar. Uyku verimliliği ve uykuya dalma süresi, kullanıcının yatakta geçirdiği toplam süreye kıyasla ne kadar etkili bir şekilde dinlendiğini açıklayan standart klinik metriklerdir. Bu metrikler, uyku hijyeni ve dinlenme hakkında bilgi verir.

Uyku verimliliği puanı

Uyku verimliliği, yatakta geçirilen toplam süreye kıyasla uyuyarak geçirilen sürenin oranı olarak tanımlanan standart bir metriktir. API, uyku verimliliğini aşağıdaki formülü kullanarak hesaplar:

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

Verimlilik puanı, uyku seviyesi (aşamaları) bölümlemesinden hemen önce hesaplanır. API yanıtında (summary.minutesAsleep alanında) döndürülen toplam uyku süresi, uyku seviyeleri hesaplandıktan sonraki nihai sonucu yansıtır.

Bir kullanıcı veya araştırmacı, uyku günlüğünün başlangıç ya da bitiş zamanını manuel olarak değiştirirse API, uyku verimliliği puanını yeniden hesaplar ve yeni uykuya dalma ve uyanma zamanı sınırları içinde kaydedilen sensör verilerine göre aşama bölümlerini ayarlar.

Uykuya dalma süresi

Uykuya dalma süresi, kullanıcının uykuya dalmak istediği andan ("yatağa girme" veya "ışıkların kapatılması" zamanının başlangıcı) uykuya dalma gerçekleşene kadar geçen süreyi ölçer.

Otomatik algılama (auto_detect) kullanılarak otomatik olarak oluşturulan günlüklerde, uykuya dalma gibi belirgin intent kaydedilmediği için minutesToFallAsleep varsayılan olarak 0 olur. Yataktaki başlangıç zamanları manuel olarak kaydedildiğinde veya düzenlendiğinde (günlüğü manual'ya dönüştürme), API, minutesAfterWakeup ile birlikte minutesToFallAsleep değerini hesaplar ve doldurur.

Araştırma ve manuel günlük kaydı ile ilgili kılavuz

Katılımcılar, yatakta başlangıç ve bitiş zamanlarını manuel olarak kaydettiğinde veya ayarladığında:

  1. Yatak içi sınırların güncellenmesi timeInBed aralığını değiştirir.
  2. Uyku seviyeleri ve aşama bölümleri, yeni penceredeki sensör verilerini değerlendirmek için otomatik olarak ayarlanır.
  3. Uyku verimliliği puanı, minutesToFallAsleep ve minutesAfterWakeup, güncellenen zaman aralığına göre yeniden hesaplanır.

Günlük uyku sıcaklığı türevleri

Günlük uyku sıcaklığı türevleri, kullanıcının uyku sırasındaki deri sıcaklığında temel değerine kıyasla oluşan değişimi ölçer. Bu veriler genellikle büyük bir uyku seansından sonra günde bir kez bildirilir.

Solunum hızı

Solunum hızı, kullanıcının dakikadaki nefes sayısını ölçer. Uyku sırasında, uyku kalitesini ve olası rahatsızlıkları izlemek için önemli bir metriktir. API; örnek solunum hızı (respiratory-rate), günlük özetler (daily-respiratory-rate) ve oturum düzeyinde uyku özetlerini (respiratory-rate-sleep-summary) destekler.

Nabız değişkenliği (HRV)

HRV, her kalp atışı arasındaki sürenin değişkenliğini ölçer. Bu, otonom sinir sisteminin durumunun önemli bir göstergesidir. Uyku sırasında yüksek ND, genellikle daha iyi bir toparlanma ve hazırlık anlamına gelirken düşük ND, stres veya aşırı antrenman anlamına gelebilir. API, örnek HRV (heart-rate-variability) ve günlük özetleri (daily-heart-rate-variability) destekler.

Oksijen doygunluğu (SpO2)

SpO2, kandaki toplam hemoglobine kıyasla oksijenle doygun hemoglobinin yüzdesini ifade eder. Uyku sırasında SpO2'yi izlemek, olası solunum bozukluklarını tespit etmek ve kullanıcının gece boyunca yeterli oksijen seviyesini korumasını sağlamak için çok önemlidir. API, örnek SpO2 (oxygen-saturation) ve günlük özetleri (daily-oxygen-saturation) destekler.

Uyku sağlığı ve toparlanma ile ilgili bütüncül görünüm

Her metrik belirli bilgiler sağlasa da bunlar birbiriyle yakından ilişkilidir ve birlikte kullanıcının toparlanma sürecine dair bütünsel bir görünüm sunar. Uyku aşamaları (hafif, derin, REM) dinlenmenin yapısal temelini oluştururken kalp atış hızı değişkenliği ve SpO2 gibi fizyolojik işaretler vücudun bu dinlenmeye fiziksel olarak nasıl tepki verdiğini gösterir. Örneğin, optimal derin uyku içeren yüksek kaliteli bir uyku seansı genellikle daha yüksek ND ile ilişkilidir. Bu da otonom sinir sisteminin etkili bir şekilde toparlandığını gösterir.

Bunları solunum hızı ve uyku sıcaklığı türevleriyle birleştirmek, uygulamaların olası rahatsızlıkları belirlemesine olanak tanır. Solunum hızındaki ani artış veya uyku sıcaklığındaki sapma, kullanıcının neden yenileyici aşamalarda daha az zaman geçirdiğini bağlamsallaştırabilir. Geliştiriciler, bu veri türlerini birlikte analiz ederek uyku hijyeni ve uzun vadeli sağlık trendleri hakkında kapsamlı bir değerlendirme sunabilir.

Yönergeler

Uyku metriklerini uygulamanıza entegre ederken aşağıdaki yönergeleri kullanın:

  • Oturum Ayrıntısı: Kullanıcının uyku aşamalarını (hafif, derin, REM, uyanık) ve kısa uyanmaları göstermek için sleep veri türünü sorgulayın.
  • Gece Uyanmaları: Ham sensör akışları olmadan gece yarısı uyanma etkinliklerini izlemek için sleep aşama aralıklarını inceleyin ve aşama türü AWAKE olan öğeleri (veya klasik uyku günlükleri için wake) filtreleyin.
  • Gecikme ve Verimlilik: Uykuya dalma süresi analizinde minutesToFallAsleep ve uyku verimliliği formülünü kullanın. minutesToFallAsleep değerinin, uyku günlükleri manuel olarak düzenlendiğinde veya açıkça kaydedildiğinde doldurulduğunu unutmayın.
  • Fizyolojik İzleme: Gelişmiş sağlık takibi için uyku seansı verilerini respiratory-rate-sleep-summary, daily-sleep-temperature-derivations, daily-heart-rate-variability ve daily-oxygen-saturation gibi fizyolojik ve toparlanma metrikleriyle birleştirin.
  • Mutabakat: Farklı cihazlardan (ör. giyilebilir cihaz ve yatak sensörü) gelen çakışan uyku günlüklerinin tek bir "ana" uyku kaydında birleştirildiğinden emin olmak için reconcile işlemini kullanın.

Toplam derin uyku süresini hesaplama

Bir kullanıcının belirli bir gecede onarıcı derin uyku aşamasında geçirdiği toplam süreyi hesaplamak için:

  1. Belirtilen zaman aralığı için sleep veri türünü sorgulayın.
  2. Aşamalar listesinde yineleme yapın ve type olduğuDEEP aralıkları belirleyin.
  3. Her derin uyku aralığının süresini (bitiş zamanı - başlangıç zamanı) hesaplayın ve bunları toplayın.

Elde edilen toplam, o oturumdaki derin uykunun toplam fiziksel süresini gösterir.

Önceki
Adımlar