Google Health API ile uyku deneyimleri geliştirme

Google Health API, kullanıcının uyku düzenini (ör. dinlenme sırasındaki süre, kalite ve fizyolojik metrikler) izleyen veri türleri sağlar. 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 sabit ve dinlenme durumunda olduğu için özellikle uyku sırasında kaydedilir. Bu sayede API, gündüz stres faktörleri, fiziksel aktivite veya değişen çevre koşulları gibi etkenler olmadan kullanıcının otonom ve solunum sağlığıyla ilgili temel bilgileri 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, uykuyu ölçmek 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

listeleme, mutabakat .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Günlük Oksijen Doygunluğu
dataType: daily-oxygen-saturation
filter parameter: daily_oxygen_saturation
Kayıt türü: Günlük

Uyumlu cihazlar

listeleme, mutabakat .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

listeleme, mutabakat .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Günlük Uyku Sıcaklığı Değişimleri
dataType: daily-sleep-temperature-derivations
filter parameter: daily_sleep_temperature_derivations
Kayıt türü: Günlük

Uyumlu cihazlar

listeleme, mutabakat .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

listeleme, mutabakat .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
Depolama çözünürlüğü: 1 dakika

Uyumlu cihazlar

listeleme, mutabakat .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

listeleme, mutabakat .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 seansları ve kısa uyanmalar

Uyku seansı (Sleep), tek bir gece uykusu veya gündüz uykusu gibi ayrı bir uyku etkinliğini temsil eder. Bu grafik, çakışmayan uyku aşamalarının ayrıntılı bir dökümünü ve kısa uyanmalar olarak bilinen kısa uyanma geçiş aralıklarını içerir.

  • Uyku Seansı (Sleep): Birincil dinlenmenin bitişik zaman çizelgesini bölen ayrı bir uyku etkinliğini (LIGHT, DEEP, REM, AWAKE aşama aralıkları) temsil eder.
  • Kısa Uyanmalar (shortAwakenings): Dinlenme sırasında meydana gelen kısa uyanma geçişleri veya uyanmalar. Standart AWAKE aşama aralıklarının aksine (çakışmayan bitişik uyku aşaması ilerlemesini böler), kısa uyanmalar, çevredeki uyku aşamalarıyla çakışabilen farklı segmentlerdir. Bu grafikler, birincil uyku aşaması yapısını bozmadan huzursuzluk ve mikro uyanmalar hakkında ayrıntılı görünürlük sağlar.
  • Gece uyanmaları: Gece uyanmaları (ör. su içmek için kalkma), cihaz üzerinde sensör füzyonu (ivme ölçer, jiroskop ve adım sayısı) ile belirlenir. Uygulamalar, stages değerini type: "AWAKE" (hem CLASSIC hem de STAGES uyku kayıtlarında kullanılır) içeren aralıklar için filtreleyerek veya outOfBedSegments değerini inceleyerek gece uyanmalarını algılayabilir.

Örnek

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

Uyku seansı oluşturma

Uyku seansı girişi oluşturmak için sleep veri noktaları uç noktasına POST isteği gönderin. Yanıt, data-point-id değerini içeren name alanını içerir. 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 seanslarını sorgulama ve mutabakat sağlama

Kullanıcının uyku geçmişini almak için list uç noktası yerine reconcile uç noktasını sorgulayın. Kullanıcı, uykuyu giyilebilir takip cihazı ve Health Connect gibi birden fazla kaynaktan takip ettiğinde list, çakışan her kaydı döndürür. Ham list sonuçlarını toplamak, günlük uyku süresinin iki kez sayılmasına neden olabilir. reconcile uç noktası, çakışan günlükleri tek bir akışta birleştirerek tekilleştirir ve sleep.metadata.mainSleep değerini true olarak ayarlayarak her günün birincil uyku oturumunu tanımlar. Her iki uç noktanın karşılaştırması için Liste ve mutabakat uç noktalarını karşılaştırma başlıklı makaleyi inceleyin.

list veya reconcile ile sleep sorgusu yaparken aşağıdaki filtreleme ve sayfalama kısıtlamalarını göz önünde bulundurun:

  1. sleep sorgularını yalnızca oturumun bitiş zamanına göre filtrelemek için sleep.interval.end_time (UTC cinsinden fiziksel zaman) veya sleep.interval.civil_end_time (yerel sivil zaman) kullanın. AND ile >= ve < karşılaştırma operatörlerini kullanarak alt ve üst sınırları birleştirin.
  2. sleep sorgularını başlangıç zamanına göre veya OR ile filtrelemeyin. sleep.interval.start_time veya sleep.interval.civil_start_time için filtreleme yapıldığında INVALID_DATA_POINT_FILTER_DATA_TYPE_MEMBER nedeniyle 400 Bad Request (INVALID_ARGUMENT) hatası döndürülür. OR kullanımı, INVALID_DATA_POINT_FILTER_EXPRESSION_STRUCTURE nedeniyle 400 Bad Request (INVALID_ARGUMENT) hatası döndürür. Söz dizimi ayrıntıları için Verileri filtreleme kılavuzu'na bakın.
  3. Hem list hem de reconcile, sleep için varsayılan ve maksimum pageSize değerini 25 olarak zorunlu kılar. 25 değerinden büyük bir pageSize iletirseniz API, değeri 25 olarak sabitler ve değer negatifse 400 Bad Request hatası döndürür. Birden fazla haftanın uyku geçmişini senkronize etmek için jeton boşalana kadar nextPageToken kullanarak sayfalandırın. Ayrıntılı bilgi için Geçmiş verileri sorgulama başlıklı makaleyi inceleyin.

Örneğin, aşağıdaki istek, iki haftalık bir sivil tarih aralığında sona eren mutabık kalınan uyku seanslarını sorgular:

İstek

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

Yanıt

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

Uyku verimliliği ve gecikme metrikleri

API, uyku aşamaları ve fizyolojik metriklerin yanı sıra uyku kalitesini ve uyku başlangıcını ölçen temel metrikler 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 durumu hakkında bilgi verir.

Uyku verimliliği puanı

Uyku verimliliği, yatakta geçirilen toplam süreye kıyasla uykuda geçirilen sürenin oranı olarak tanımlanan standart bir metriktir. API, uyku verimliliğini hesaplamak için şu formülü kullanır:

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 kaydının başlangıç ya da bitiş zamanını manuel olarak değiştirirse API, uyku verimliliği puanını yeniden hesaplar ve yeni uyku vakti ile uyanma vakti 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 uyumaya niyetlendiği andan ("yatağa girme" veya "ışıkları kapatma" zamanının başlangıcı) uykuya daldığı ana kadar geçen süreyi ölçer.

Otomatik olarak oluşturulan günlüklerde (metadata.manuallyEdited, false ise) uykuya dalma niyeti açıkça kaydedilmediğinden summary.minutesToFallAsleep varsayılan olarak "0" değerine ayarlanır. Yatakta başlangıç zamanları manuel olarak kaydedildiğinde veya düzenlendiğinde (metadata.manuallyEdited, true olduğunda) API, summary.minutesToFallAsleep ve summary.minutesAfterWakeUp değerlerini hesaplayıp doldurur.

Araştırma ve manuel günlük kaydı için rehberlik

Katılımcılar yatakta geçirilen sürenin başlangıç ve bitiş zamanlarını manuel olarak kaydettiğinde veya ayarladığında:

  1. Yatakta geçirilen süre sınırlarını güncellemek, uyku interval (ve summary.minutesInSleepPeriod) değerini 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ı, summary.minutesToFallAsleep ve summary.minutesAfterWakeUp, güncellenen zaman aralığına göre yeniden hesaplanır.

Günlük uyku sıcaklığı değişimleri

Günlük Uyku Sıcaklığı Değişimleri, kullanıcının uyku sırasındaki deri sıcaklığının referans değerine kıyasla değişimini ölçer. Bu veriler genellikle ana uyku seansından sonra günde bir kez raporlanır.

Solunum hızı

Solunum hızı, kullanıcının dakikadaki nefes sayısını ölçer. Uyku sırasında ise 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)

ND, her kalp atışı arasındaki sürenin değişimini ölçer. Otonom sinir sisteminin durumunun önemli bir göstergesidir. Uyku sırasında yüksek HRV genellikle daha iyi toparlanma ve hazır olma durumunu gösterirken düşük HRV, stres veya aşırı antrenman yapıldığını gösterebilir. API, örnek ND (heart-rate-variability) ve günlük özetleri (daily-heart-rate-variability) destekler.

Oksijen doygunluğu

Kandaki oksijen doygunluğu (SpO2), kandaki toplam hemoglobine kıyasla oksijenle doymuş hemoglobin yüzdesini gösterir. Uyku sırasında SpO2'nin izlenmesi, olası solunum bozukluklarının tespit edilmesine yardımcı olur ve kullanıcının gece boyunca yeterli oksijen seviyesini koruyup korumadığını doğrular. API, örnek SpO2 (oxygen-saturation) ve günlük özetleri (daily-oxygen-saturation) destekler.

Dakika düzeyinde oxygen-saturation sorgusu yaptığınızda Google Health API, yalnızca doğrulanmış veri noktalarını döndürür ve kol hareketi, bileğe tam oturmayan cihaz veya düşük sensör güvenilirliği (yüzde 50'nin altında) nedeniyle oluşan geçersiz ölçümlerin yanı sıra hareket gürültüsüne bitişik ölçümleri filtreler. Geçersiz dakikalar hariç tutulduğu için dakika düzeyindeki kapsam seyrek olabilir ve zaman damgası boşlukları beklenebilir. Hem oxygen-saturation hem de daily-oxygen-saturation aynı doğrulanmış ölçümleri kullanır. Doğrulama ölçütleriyle ilgili ayrıntılar için Dakika düzeyinde SpO2 filtreleme ve veri geçerliliği başlıklı makaleyi inceleyin.

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

Her metrik belirli analizler sunsa da bunlar birbiriyle yakından ilişkilidir ve birlikte kullanıcının iyileşme sürecine dair bütünsel bir görünüm sunar. Uyku aşamaları (hafif, derin, REM) dinlenmenin yapısal temelini oluştururken HRV ve SpO2 gibi fizyolojik göstergeler, vücudun bu dinlenmeye fiziksel olarak nasıl tepki verdiğini gösterir. Örneğin, ideal derin uyku süresine sahip 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 bir artış veya uyku sıcaklığındaki bir sapma, kullanıcının dinlendirici aşamalarda neden daha az zaman geçirmiş olabileceğini açıklayabilir. 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ı: Bir kullanıcının uyku aşamalarını (Hafif, Derin, REM, Uyanık) ve kısa uyanmalarını göstermek için sleep veri türünü sorgulayın.
  • Gece Uyanmaları: Ham sensör akışları olmadan gece uyanma etkinliklerini izlemek için sleep aşama aralıklarını inceleyin ve type: "AWAKE" (hem STAGES hem de CLASSIC uyku kayıtları için) içeren öğeleri filtreleyin veya outOfBedSegments öğesini inceleyin.
  • Gecikme ve Verimlilik: Uyku gecikmesi analizi için summary.minutesToFallAsleep ve uyku verimliliği formülünü kullanın. summary.minutesToFallAsleep, uyku kayıtları manuel olarak düzenlendiğinde (metadata.manuallyEdited, true olduğunda) veya açıkça kaydedildiğinde doldurulur.
  • Fizyolojik İzleme: Gelişmiş sağlık izleme 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.

Derin uykuda geçirilen toplam süreyi hesaplama

Bir kullanıcının belirli bir gecede dinlendirici 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şama listesini inceleyin ve type değerinin DEEP olduğu 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, ilgili oturumdaki derin uykunun toplam fiziksel süresini verir.