Mengembangkan pengalaman tidur dengan Google Health API

Google Health API menyediakan jenis data yang melacak pola tidur pengguna, termasuk durasi, kualitas, dan metrik fisiologis selama istirahat. Metrik ini membantu aplikasi memberikan insight tentang pemulihan, kebersihan tidur, dan tren kesehatan jangka panjang.

Metrik fisiologis seperti Variabilitas Detak Jantung (HRV), Saturasi Oksigen (SpO2), dan laju pernapasan direkam secara khusus selama tidur karena tubuh berada dalam kondisi istirahat yang stabil. Hal ini memungkinkan API mencatat data dasar kesehatan otonom dan pernapasan pengguna tanpa gangguan dari pemicu stres siang hari, aktivitas fisik, atau kondisi lingkungan yang bervariasi.

Pahami perbedaan antara jenis data ini untuk menentukan metrik mana yang sesuai dengan aplikasi Anda.

Jenis data yang didukung

API ini mendukung jenis data berikut untuk mengukur tidur:

Tabel: Jenis data Tidur Google Health API
Jenis data Operasi
yang tersedia		 Cakupan
Variabilitas Detak Jantung Harian
dataType: daily-heart-rate-variability
parameter filter: daily_heart_rate_variability
Jenis data: Harian

Perangkat yang kompatibel
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Saturasi Oksigen Harian
dataType: daily-oxygen-saturation
parameter filter: daily_oxygen_saturation
Jenis data: Harian

Perangkat yang kompatibel
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Laju Pernapasan Harian
dataType: daily-respiratory-rate
parameter filter: daily_respiratory_rate
Jenis data: Harian

Perangkat yang kompatibel
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Turunan Suhu Tidur Harian
dataType: daily-sleep-temperature-derivations
parameter filter: daily_sleep_temperature_derivations
Jenis data: Harian

Perangkat yang kompatibel
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Variabilitas Detak Jantung
dataType: heart-rate-variability
parameter filter: heart_rate_variability
Jenis data: Contoh

Perangkat yang kompatibel
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Saturasi Oksigen
dataType: oxygen-saturation
parameter filter: oxygen_saturation
Jenis data: Contoh

Perangkat yang kompatibel
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Ringkasan Tidur Laju Pernapasan
dataType: respiratory-rate-sleep-summary
parameter filter: respiratory_rate_sleep_summary
Jenis data: Contoh

Perangkat yang kompatibel
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Tidur
dataType: sleep
filter parameter: sleep
Jenis data: Sesi

Perangkat yang kompatibel
list, get, reconcile, create, update, batchDelete .sleep.readonly
.sleep.writeonly

Sesi tidur dan bangun singkat

Sesi Tidur (Sleep) mewakili peristiwa tidur yang terpisah, seperti tidur malam tunggal atau tidur siang. Fitur ini mencakup perincian mendetail tentang fase tidur yang tidak tumpang-tindih bersama dengan interval transisi bangun singkat yang dikenal sebagai bangun singkat.

  • Sesi Tidur (Sleep): Merepresentasikan peristiwa tidur diskrit (interval tahap LIGHT, DEEP, REM, AWAKE) yang mempartisi linimasa berurutan istirahat utama.
  • Bangun Singkat (shortAwakenings): Transisi bangun atau bangun singkat yang terjadi selama istirahat. Tidak seperti interval fase AWAKE standar (yang membagi progres fase tidur yang berdekatan dan tidak tumpang-tindih), bangun singkat adalah segmen berbeda yang dapat tumpang-tindih dengan fase tidur di sekitarnya. Fitur ini memberikan visibilitas terperinci ke dalam kegelisahan dan bangun singkat tanpa mengganggu struktur tahap tidur utama.
  • Bangun di Malam Hari: Bangun di tengah malam (seperti bangun untuk minum air) diidentifikasi oleh penggabungan sensor di perangkat (akselerometer, giroskop, dan jumlah langkah). Di Web API, aplikasi dapat mendeteksi bangun di malam hari dengan memfilter interval yang ditandai dengan level "wake" (tidur klasik) atau "awake" (tidur berdasarkan tahap).

Contoh

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

Membuat sesi tidur

Untuk membuat entri sesi tidur, kirim permintaan POST ke endpoint titik data sleep. Respons mencakup kolom name yang berisi data-point-id, yang dapat digunakan dalam permintaan Perbarui (Patch) atau Hapus.

Permintaan

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

Respons

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

Metrik efisiensi dan latensi tidur

Selain tahapan tidur dan metrik fisiologis, API ini menyediakan metrik utama yang mengukur kualitas tidur dan permulaan tidur. Efisiensi tidur dan latensi mulai tidur adalah metrik klinis standar yang menjelaskan seberapa efektif pengguna beristirahat dibandingkan dengan total waktu mereka di tempat tidur, sehingga memberikan insight tentang kebersihan tidur dan kualitas istirahat.

Skor efisiensi tidur

Efisiensi tidur adalah metrik standar yang ditentukan sebagai proporsi waktu yang dihabiskan untuk tidur dibandingkan dengan total waktu yang dihabiskan di tempat tidur. API menghitung efisiensi tidur menggunakan formula berikut:

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

Skor efisiensi dihitung tepat sebelum partisi tingkat tidur (tahapan). Total menit tidur yang ditampilkan dalam respons API (di kolom summary.minutesAsleep) mencerminkan hasil akhir setelah tingkat tidur dihitung.

Jika pengguna atau peneliti mengubah waktu mulai atau berakhir catatan tidur secara manual, API akan menghitung ulang skor efisiensi tidur dan menyesuaikan partisi tahap sesuai dengan data sensor yang direkam dalam batas waktu tidur dan bangun yang baru.

Latensi mulai tidur

Latensi mulai tidur mengukur waktu yang berlalu sejak pengguna berniat untuk tertidur (waktu mulai "di tempat tidur" atau "mematikan lampu") hingga mulai tertidur.

Untuk log yang dibuat secara otomatis menggunakan deteksi otomatis (auto_detect), minutesToFallAsleep secara default ditetapkan ke 0 karena tidak ada intent eksplisit untuk tertidur yang dicatat ke dalam log. Saat waktu mulai di tempat tidur dicatat atau diedit secara manual (mengonversi log ke manual), API menghitung dan mengisi minutesToFallAsleep bersama dengan minutesAfterWakeup.

Panduan untuk riset dan logging manual

Saat peserta merekam atau menyesuaikan waktu mulai dan berakhir di tempat tidur secara manual:

  1. Memperbarui batas dalam video akan mengubah interval timeInBed.
  2. Tingkat tidur dan partisi tahap akan disesuaikan secara otomatis untuk mengevaluasi data sensor dalam jangka waktu baru.
  3. Skor efisiensi tidur, minutesToFallAsleep, dan minutesAfterWakeup diturunkan ulang berdasarkan jangka waktu yang diperbarui.

Turunan suhu tidur harian

Turunan Suhu Tidur Harian mengukur variasi suhu kulit pengguna saat tidur dibandingkan dengan suhu dasarnya. Data ini biasanya dilaporkan sekali per hari setelah sesi tidur utama.

Laju pernapasan

Laju pernapasan mengukur napas pengguna per menit. Selama tidur, ini adalah metrik utama untuk memantau kualitas tidur dan potensi gangguan. API ini mendukung laju pernapasan sampel (respiratory-rate), ringkasan harian (daily-respiratory-rate), dan ringkasan tidur tingkat sesi (respiratory-rate-sleep-summary).

Variabilitas detak jantung (HRV)

HRV mengukur variasi waktu antara setiap detak jantung. HRV adalah indikator utama kondisi sistem saraf otonom; HRV yang tinggi selama tidur umumnya menandakan pemulihan dan kesiapan yang lebih baik, sedangkan HRV yang rendah dapat mengindikasikan stres atau latihan berlebihan. API ini mendukung HRV sampel (heart-rate-variability) dan ringkasan harian (daily-heart-rate-variability).

Saturasi oksigen (SpO2)

SpO2 menunjukkan persentase hemoglobin yang tersaturasi oksigen relatif terhadap total hemoglobin dalam darah. Memantau SpO2 selama tidur sangat penting untuk mendeteksi potensi gangguan pernapasan dan memastikan pengguna mempertahankan kadar oksigen yang memadai sepanjang malam. API ini mendukung sampel SpO2 (oxygen-saturation) dan ringkasan harian (daily-oxygen-saturation).

Gambaran menyeluruh tentang kesehatan dan pemulihan tidur

Meskipun setiap metrik memberikan insight tertentu, metrik tersebut sangat saling terkait dan bersama-sama menawarkan gambaran menyeluruh tentang pemulihan pengguna. Tahapan tidur (Ringan, Nyenyak, REM) memberikan dasar struktural istirahat, sementara penanda fisiologis seperti HRV dan SpO2 menunjukkan bagaimana tubuh merespons istirahat tersebut secara fisik. Misalnya, sesi tidur berkualitas tinggi dengan Tidur lelap yang optimal sering kali berkorelasi dengan HRV yang lebih tinggi, yang menandakan pemulihan yang efektif dari sistem saraf otonom.

Dengan menggabungkannya dengan turunan laju pernapasan dan suhu tidur, aplikasi dapat mengidentifikasi potensi gangguan. Peningkatan mendadak pada laju pernapasan atau perubahan suhu saat tidur dapat memberikan konteks mengapa pengguna mungkin menghabiskan lebih sedikit waktu dalam tahap pemulihan. Dengan menganalisis jenis data ini secara bersamaan, developer dapat memberikan penilaian komprehensif tentang kebiasaan tidur dan tren kesehatan jangka panjang.

Panduan

Saat mengintegrasikan metrik tidur di aplikasi Anda, gunakan panduan berikut:

  • Detail Sesi: Untuk menampilkan tahapan tidur pengguna (Ringan, Nyenyak, REM, Terjaga) dan bangun tidur singkat, kueri jenis data sleep.
  • Bangun di Malam Hari: Untuk melacak peristiwa bangun di tengah malam tanpa aliran sensor mentah, periksa interval tahap sleep dan filter item dengan jenis tahap AWAKE (atau wake untuk log tidur klasik).
  • Latensi dan Efisiensi: Gunakan minutesToFallAsleep dan formula efisiensi tidur untuk analisis latensi tidur. Perhatikan bahwa minutesToFallAsleep diisi saat log tidur diedit secara manual atau dicatat secara eksplisit.
  • Pemantauan Fisiologis: Untuk pemantauan kesehatan tingkat lanjut, gabungkan data sesi tidur dengan metrik fisiologis dan pemulihan seperti respiratory-rate-sleep-summary, daily-sleep-temperature-derivations, daily-heart-rate-variability, dan daily-oxygen-saturation.
  • Rekonsiliasi: Gunakan operasi reconcile untuk memastikan bahwa catatan tidur yang tumpang-tindih dari perangkat yang berbeda (misalnya, perangkat wearable dan sensor kasur) digabungkan ke dalam satu catatan tidur "utama".

Menghitung total waktu dalam fase tidur lelap

Untuk menghitung total waktu yang dihabiskan pengguna dalam fase tidur dalam restoratif selama malam tertentu:

  1. Buat kueri tipe data sleep untuk rentang waktu yang ditentukan.
  2. Lakukan iterasi pada daftar tahap dan identifikasi interval saat type adalah DEEP.
  3. Hitung durasi (Waktu Berakhir - Waktu Mulai) untuk setiap interval fase tidur dalam dan jumlahkan.

Jumlah yang dihasilkan memberikan total durasi fisik tidur lelap untuk sesi tersebut.

Sebelumnya
Langkah