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 dicatat secara khusus selama tidur karena tubuh berada dalam kondisi stabil dan istirahat. Hal ini memungkinkan API menangkap dasar pengukuran kesehatan otonom dan pernapasan pengguna tanpa gangguan pemicu stres di siang hari, aktivitas fisik, atau kondisi lingkungan yang bervariasi.

Pahami perbedaan antara jenis data ini untuk menentukan metrik 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
filter parameter: daily_heart_rate_variability
Jenis data: Harian

Perangkat yang kompatibel

daftar, rekonsiliasi .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Saturasi Oksigen Harian
dataType: daily-oxygen-saturation
filter parameter: daily_oxygen_saturation
Jenis data: Harian

Perangkat yang kompatibel

daftar, rekonsiliasi .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Laju Pernapasan Harian
dataType: daily-respiratory-rate
filter parameter: daily_respiratory_rate
Jenis data: Harian

Perangkat yang kompatibel

daftar, rekonsiliasi .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Deviasi Suhu Tidur Harian
dataType: daily-sleep-temperature-derivations
filter parameter: daily_sleep_temperature_derivations
Jenis data: Harian

Perangkat yang kompatibel

daftar, rekonsiliasi .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Variabilitas Detak Jantung
dataType: heart-rate-variability
filter parameter: heart_rate_variability
Jenis data: Sample

Perangkat yang kompatibel

daftar, rekonsiliasi .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Saturasi Oksigen
dataType: oxygen-saturation
filter parameter: oxygen_saturation
Jenis data: Sample
Resolusi penyimpanan: 1 menit

Perangkat yang kompatibel

daftar, rekonsiliasi .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Ringkasan data tidur laju pernapasan
dataType: respiratory-rate-sleep-summary
filter parameter: respiratory_rate_sleep_summary
Jenis data: Sample

Perangkat yang kompatibel

daftar, rekonsiliasi .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 terpisah, seperti tidur malam atau tidur siang. Data ini mencakup perincian mendetail tentang fase tidur yang tidak tumpang-tindih beserta interval transisi bangun singkat yang dikenal sebagai terbangun singkat.

  • Sesi Tidur (Sleep): Mewakili peristiwa tidur diskret (interval fase LIGHT, DEEP, REM, AWAKE) yang mempartisi linimasa istirahat utama yang berdekatan.
  • Terbangun Singkat (shortAwakenings): Transisi bangun singkat atau terbangun 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. Tahapan ini memberikan visibilitas terperinci tentang kegelisahan dan terbangun sesaat tanpa mengganggu struktur fase tidur utama.
  • Terbangun di Malam Hari: Terbangun di tengah malam (seperti bangun untuk minum air) diidentifikasi oleh fusi sensor di perangkat (akselerometer, giroskop, dan jumlah langkah). Aplikasi dapat mendeteksi terbangun di malam hari dengan memfilter stages untuk interval dengan type: "AWAKE" (digunakan dalam catatan tidur CLASSIC dan STAGES) atau dengan memeriksa outOfBedSegments.

Contoh

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

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 Update (Patch) atau Delete.

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 fase tidur dan metrik fisiologis, API ini menyediakan metrik utama yang mengukur kualitas tidur dan onset tidur. Efisiensi tidur dan latensi awal 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 didefinisikan 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 (fase) tidur. 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 fase sesuai dengan data sensor yang dicatat dalam batas waktu tidur dan waktu bangun yang baru.

Latensi awal tidur

Latensi awal tidur mengukur waktu yang berlalu sejak pengguna berniat untuk tidur (awal waktu "di tempat tidur" atau "lampu padam") hingga awal tidur terjadi.

Untuk log yang dibuat secara otomatis (metadata.manuallyEdited adalah false), summary.minutesToFallAsleep ditetapkan secara default ke "0" karena tidak ada niat eksplisit untuk tertidur yang dicatat dalam log. Saat waktu mulai di tempat tidur dicatat atau diedit secara manual (metadata.manuallyEdited adalah true), API akan menghitung dan mengisi summary.minutesToFallAsleep bersama dengan summary.minutesAfterWakeUp.

Panduan untuk riset dan pencatatan manual

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

  1. Memperbarui batas di tempat tidur akan mengubah interval (dan summary.minutesInSleepPeriod) tidur.
  2. Level tidur dan partisi fase tidur otomatis disesuaikan untuk mengevaluasi data sensor dalam jendela baru.
  3. Skor efisiensi tidur, summary.minutesToFallAsleep, dan summary.minutesAfterWakeUp diperoleh kembali berdasarkan rentang waktu yang diperbarui.

Deviasi suhu tidur harian

Derivasi Suhu Tidur Harian mengukur variasi suhu kulit pengguna selama tidur dibandingkan dengan nilai dasar mereka. Data ini biasanya dilaporkan sekali per hari setelah sesi tidur utama.

Laju pernapasan

Laju pernapasan mengukur napas pengguna per menit. Selama tidur, detak jantung adalah metrik utama untuk memantau kualitas tidur dan potensi gangguan. API ini mendukung sampel laju pernapasan (respiratory-rate), ringkasan harian (daily-respiratory-rate), dan ringkasan data 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

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

Saat Anda mengkueri oxygen-saturation tingkat menit, Google Health API hanya menampilkan titik data yang divalidasi dan memfilter pengukuran yang tidak valid yang disebabkan oleh gerakan lengan, pemasangan yang longgar di pergelangan tangan, atau keyakinan sensor yang rendah (di bawah 50%), serta pembacaan yang berdekatan dengan derau gerakan. Karena menit yang tidak valid dikecualikan, cakupan tingkat menit dapat menjadi jarang dan kesenjangan stempel waktu dapat terjadi. oxygen-saturation dan daily-oxygen-saturation mengandalkan pembacaan tervalidasi yang sama. Untuk mengetahui detail tentang kriteria validasi, lihat Pemfilteran dan validitas data SpO2 tingkat menit.

Gambaran menyeluruh tentang kesehatan dan pemulihan tidur

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

Menggabungkan hal ini dengan turunan laju pernapasan dan suhu tidur memungkinkan aplikasi mengidentifikasi potensi gangguan. Lonjakan laju pernapasan yang tiba-tiba atau penyimpangan suhu tidur dapat memberikan konteks mengapa pengguna mungkin menghabiskan lebih sedikit waktu dalam tahap restoratif. Dengan menganalisis jenis data ini secara bersamaan, developer dapat memberikan penilaian komprehensif tentang kebersihan tidur dan tren kesehatan jangka panjang.

Panduan

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

  • Detail Sesi: Untuk menampilkan fase tidur pengguna (Ringan, Dalam, REM, Bangun) dan terbangun singkat, buat kueri jenis data sleep.
  • Terbangun di Malam Hari: Untuk melacak peristiwa terbangun di tengah malam tanpa aliran data sensor mentah, periksa interval fase sleep dan filter item dengan type: "AWAKE" (untuk catatan tidur STAGES dan CLASSIC) atau periksa outOfBedSegments.
  • Latensi dan Efisiensi: Gunakan summary.minutesToFallAsleep dan formula efisiensi tidur untuk analisis latensi tidur. Perhatikan bahwa summary.minutesToFallAsleep diisi saat catatan tidur diedit secara manual (metadata.manuallyEdited adalah true) 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 berbagai perangkat (misalnya, perangkat wearable dan sensor kasur) digabungkan menjadi satu catatan tidur "utama".

Menghitung total waktu dalam tidur nyenyak

Untuk menghitung total waktu yang dihabiskan pengguna dalam tahap tidur nyenyak restoratif untuk malam tertentu:

  1. Membuat kueri jenis data sleep untuk rentang waktu yang ditentukan.
  2. Lakukan iterasi melalui daftar tahap dan identifikasi interval saat type adalah DEEP.
  3. Hitung durasi (Waktu Berakhir - Waktu Mulai) untuk setiap interval tidur nyenyak dan jumlahkan.

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