Google Health API انواع دادههایی را ارائه میدهد که الگوهای خواب کاربر را ردیابی میکنند، ازجمله مدت، کیفیت، و سنجههای فیزیولوژیکی درطول استراحت. این سنجهها به برنامهها کمک میکنند تا اطلاعات آماری درباره ریکاوری، بهداشت خواب، و روندهای سلامتی بلندمدت ارائه دهند.
سنجههای فیزیولوژیکی مانند «نوسان ضربان قلب» (HRV)، «اشباع اکسیژن» (SpO2)، و نرخ تنفس بهطور خاص درطول خواب ثبت میشوند زیرا بدن در حالت پایدار و استراحت قرار دارد. این کار به API اجازه میدهد تا خط مبنایی از سلامت خودمختار و تنفسی کاربر را بدون تداخل عوامل استرسزای روزانه، فعالیت بدنی، یا شرایط محیطی متغیر ثبت کند.
تفاوتهای بین این انواع داده را درک کنید تا تعیین کنید کدام سنجهها برای برنامه شما مناسب هستند.
انواع دادههای پشتیبانیشده
این میانای برنامهسازی کاربردی از انواع دادههای زیر برای اندازهگیری خواب پشتیبانی میکند:
| نوع داده | عملیات دردسترس |
حوزه |
|---|---|---|
|
تغییرپذیری ضربان قلب روزانه
dataType:
daily-heart-rate-variabilityfilter parameter: daily_heart_rate_variability
نوع گزارش: روزانه
دستگاههای سازگار
|
فهرست، تطبیق دادن | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
اشباع اکسیژن روزانه
dataType:
daily-oxygen-saturationfilter parameter: daily_oxygen_saturation
نوع گزارش: روزانه
دستگاههای سازگار
|
فهرست، تطبیق دادن | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
سرعت تنفس روزانه
dataType:
daily-respiratory-ratefilter parameter: daily_respiratory_rate
نوع گزارش: روزانه
دستگاههای سازگار
|
فهرست، تطبیق دادن | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
انحرافهای دمای روزانه هنگام خواب
dataType:
daily-sleep-temperature-derivationsfilter parameter: daily_sleep_temperature_derivations
نوع گزارش: روزانه
دستگاههای سازگار
|
فهرست، تطبیق دادن | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
تغییرپذیری ضربان قلب
dataType:
heart-rate-variabilityfilter parameter: heart_rate_variability
نوع گزارش: نمونه
دستگاههای سازگار
|
فهرست، تطبیق دادن | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
اشباع اکسیژن
dataType:
oxygen-saturationfilter parameter: oxygen_saturation
نوع گزارش: نمونه
وضوح ذخیرهسازی: ۱ دقیقه
دستگاههای سازگار
|
فهرست، تطبیق دادن | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
خلاصه سرعت تنفس در خواب
dataType:
respiratory-rate-sleep-summaryfilter parameter: respiratory_rate_sleep_summary
نوع گزارش: نمونه
دستگاههای سازگار
|
فهرست، تطبیق دادن | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
خواب
dataType:
sleepfilter parameter: sleep
نوع ضبط: جلسه
دستگاههای سازگار
|
list, get, reconcile, create, update, batchDelete | .sleep.readonly.sleep.writeonly |
جلسههای خواب و بیداریهای کوتاه
«جلسه خواب» (Sleep) نشاندهنده یک رویداد خواب مجزا است، مانند یک خواب شبانه یا چرت روزانه. این شامل تفکیک دقیق مراحل خواب غیرهمپوشان در کنار فواصل کوتاه انتقال بیداری است که بهعنوان بیداریهای کوتاه شناخته میشوند.
- جلسه خواب (
Sleep): نشاندهنده رویداد خواب مجزا (LIGHT،DEEP،REM،AWAKEفواصل مرحله) است که خط زمان پیوسته استراحت اولیه را تقسیم میکند. - بیداریهای کوتاه (
shortAwakenings): گذارهای کوتاه به بیداری یا بیداریهایی که درطول استراحت رخ میدهد. برخلاف فواصل استاندارد مرحلهAWAKE(که پیشرفت مرحله خواب پیوسته غیرهمپوشان را تقسیم میکند)، بیداریهای کوتاه بخشهای متمایزی هستند که میتوانند با مراحل خواب اطراف همپوشانی داشته باشند. این حسگرها دیدی دقیق از بیقراری و بیداریهای جزئی ارائه میدهند، بدون اینکه ساختار اصلی مراحل خواب را مختل کنند. - بیداریهای شبانه: بیداریهای نیمهشب (مانند بلند شدن برای آب خوردن) با تلفیق حسگرهای روی دستگاه (شتابسنج، ژیروسکوپ، و تعداد قدمها) شناسایی میشوند. برنامهها میتوانند بیداریهای شبانه را با فیلتر کردن
stagesبرای فاصلههای زمانی باtype: "AWAKE"(استفادهشده در هر دو گزارش خوابCLASSICوSTAGES) یا با بررسیoutOfBedSegmentsتشخیص دهند.
مثال
{
"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"
}
}
}
ایجاد جلسه خواب
برای ایجاد ورودی جلسه خواب، درخواست POST را به نقطه پایانی نقاط داده sleep ارسال کنید. پاسخ شامل فیلد name است که حاوی
data-point-id است، که میتواند در درخواست
بهروزرسانی (وصله) یا
حذف استفاده شود.
درخواست
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"
}
]
}
}پاسخ
{
"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"
}
]
}
}
}پرسوجو و تطبیق جلسههای خواب
برای بازیابی سابقه خواب کاربر،
نقطه پایانی reconcile
را پُرسمان کنید نه
نقطه پایانی list. وقتی
کاربر خواب را ازطریق منابع مختلفی مثل ردیاب پوشیدنی و
Health Connect ردیابی میکند، list همه سوابق همپوشان را برمیگرداند. جمع کردن نتایج خام list
میتواند باعث دوبارشماری مدت خواب روزانه شود. نقطه پایانی reconcile
گزارشهای همپوشان را در یک جریان واحد ادغام میکند و با تنظیم sleep.metadata.mainSleep روی true،
جلسه خواب اصلی هر روز را شناسایی میکند. برای
مقایسه هر دو نقطه پایانی، به
مقایسه فهرست و تطبیق نقاط پایانی مراجعه کنید.
هنگام پرسمان sleep با list یا reconcile، محدودیتهای فیلتر کردن و صفحهبندی زیر را بهخاطر داشته باشید:
- پرسوجوهای
sleepرا فقط براساس زمان پایان جلسه بااستفاده ازsleep.interval.end_time(زمان فیزیکی در ساعت هماهنگ جهانی) یاsleep.interval.civil_end_time(زمان مدنی محلی) فیلتر کنید. بااستفاده از عملگرهای مقایسهای>=و<باAND، مرزهای پایین و بالا را ترکیب کنید. - پرسوجوهای
sleepرا براساس زمان شروع یا باORفیلتر نکنید. فیلتر کردن براساسsleep.interval.start_timeیاsleep.interval.civil_start_timeخطای400 Bad Request(INVALID_ARGUMENT) را با دلیلINVALID_DATA_POINT_FILTER_DATA_TYPE_MEMBERبرمیگرداند. استفاده ازORخطای400 Bad Request(INVALID_ARGUMENT) را با دلیلINVALID_DATA_POINT_FILTER_EXPRESSION_STRUCTUREبرمیگرداند. برای جزئیات نحو، به راهنمای فیلتر کردن دادهها مراجعه کنید. -
listوreconcileهر دوpageSizeپیشفرض و حداکثر25را برایsleepاعمال میکنند. اگرpageSizeبزرگتر از25را ارسال کنید، API مقدار را به25محدود میکند و اگر مقدار منفی باشد، خطای400 Bad Requestبرمیگرداند. برای همگامسازی سابقه خواب چند هفته، بااستفاده ازnextPageTokenصفحهبندی کنید تا زمانی که توکن خالی شود. برای جزئیات، به اجرای پُرسمان روی دادههای گذشته مراجعه کنید.
برای مثال، درخواست زیر جلسههای خواب تطبیقدادهشده را که در محدوده تاریخ مدنی دو هفتهای بهپایان میرسند پُرسمان میکند:
درخواست
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
پاسخ
{
"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"
}سنجههای کارایی و تأخیر خواب
علاوهبر مراحل خواب و سنجههای فیزیولوژیکی، این API سنجههای کلیدیای ارائه میدهد که کیفیت خواب و شروع خواب را کمیسازی میکنند. بازده خواب و تأخیر شروع خواب سنجههای بالینی استانداردی هستند که توصیف میکنند کاربر چقدر بهطور مؤثر نسبتبه کل زمان حضور در تخت استراحت میکند و بینشی درباره بهداشت خواب و آرامش ارائه میدهند.
امتیاز بازده خواب
بازده خواب سنجهای استاندارد است که بهصورت نسبت زمان خواب به کل زمان سپریشده در تختخواب تعریف میشود. میانای برنامهسازی کاربردی بازده خواب را بااستفاده از فرمول زیر محاسبه میکند:
Sleep Efficiency Score = round( (Total Minutes Asleep / Total Minutes In Bed) * 100 )
امتیاز کارایی درست قبلاز تقسیمبندی سطح (مراحل) خواب محاسبه میشود. مجموع دقایق خواب که در پاسخ میانای برنامهسازی کاربردی (در فیلد
summary.minutesAsleep) برگردانده میشود، نتیجه نهایی را پساز محاسبه سطوح خواب
نشان میدهد.
اگر کاربر یا پژوهشگر زمان شروع یا پایان گزارش خواب را بهصورت دستی اصلاح کند، میانای برنامهسازی کاربردی امتیاز کارایی خواب را دوباره محاسبه میکند و بخشهای مرحله را براساس دادههای حسگر ثبتشده در محدوده جدید زمان خواب و زمان بیداری تنظیم میکند.
تأخیر شروع خواب
تأخیر شروع خواب مدت زمان سپریشده از وقتی که کاربر قصد خوابیدن دارد (شروع زمان «در تخت» یا «خاموشی») تا شروع خواب را اندازهگیری میکند.
برای گزارشهایی که بهطور خودکار تولید میشوند (metadata.manuallyEdited برابر با false است)،
summary.minutesToFallAsleep بهطور پیشفرض روی "0" تنظیم میشود زیرا هیچ قصد صریحی برای
بهخواب رفتن ثبت نشده است. وقتی زمانهای شروع در رختخواب بهصورت دستی ثبت یا ویرایش میشوند
(metadata.manuallyEdited برابر با true است)، API
summary.minutesToFallAsleep را بههمراه summary.minutesAfterWakeUp محاسبه و تکمیل میکند.
راهنمایی برای پژوهش و ثبت دستی
وقتی شرکتکنندگان زمان شروع و پایان خواب را بهصورت دستی ضبط یا اصلاح میکنند:
- بهروزرسانی مرزهای در رختخواب بودن،
interval(وsummary.minutesInSleepPeriod) خواب را تغییر میدهد. - سطوح خواب و بخشهای مرحله بهطور خودکار تنظیم میشوند تا دادههای حسگر را در پنجره جدید ارزیابی کنند.
- امتیاز کارایی خواب،
summary.minutesToFallAsleep، وsummary.minutesAfterWakeUpبراساس پنجره زمانی بهروزشده دوباره مشتق میشوند.
انحرافهای دمای روزانه هنگام خواب
«انحرافهای دمای روزانه هنگام خواب» تغییرات دمای پوست کاربر را درطول خواب درمقایسه با خط مبنای او اندازهگیری میکند. این دادهها معمولاً یک بار در روز پساز جلسه خواب اصلی گزارش میشود.
سرعت تنفس
سرعت تنفس تعداد نفسهای کاربر در دقیقه را اندازهگیری میکند. درطول خواب، این سنجهای کلیدی برای نظارت بر کیفیت خواب و اختلالات احتمالی است. این میانای برنامهسازی کاربردی
از نمونه سرعت تنفس (respiratory-rate)، خلاصههای روزانه
(daily-respiratory-rate)، و خلاصههای خواب در سطح جلسه
(respiratory-rate-sleep-summary) پشتیبانی میکند.
تغییرپذیری ضربان قلب (HRV)
HRV تغییرات زمانی بین هر ضربان قلب را اندازهگیری میکند. این شاخص کلیدی وضعیت سیستم عصبی خودمختار است؛ «تغییرپذیری ضربان قلب» بالا درطول خواب معمولاً نشاندهنده بازیابی و آمادگی بهتر است، درحالیکه «تغییرپذیری ضربان قلب» پایین میتواند نشاندهنده استرس یا تمرین بیشازحد باشد. این API از نمونه HRV (heart-rate-variability)
و خلاصههای روزانه (daily-heart-rate-variability) پشتیبانی میکند.
اشباع اکسیژن
سیرش اکسیژن خون (SpO2) نشاندهنده درصد هموگلوبین اشباعشده با اکسیژن نسبتبه کل هموگلوبین خون است. پایش SpO2 درطول خواب به تشخیص اختلالات تنفسی احتمالی کمک میکند و تأیید میکند که آیا کاربر سطح اکسیژن کافی را درطول شب حفظ میکند یا نه. این میانای برنامهسازی کاربردی از
نمونه سیرش اکسیژن خون (oxygen-saturation) و خلاصههای روزانه
(daily-oxygen-saturation) پشتیبانی میکند.
وقتی oxygen-saturation را در سطح دقیقه جستجو میکنید، Google Health API فقط نقاط داده معتبر را برمیگرداند و اندازهگیریهای نامعتبر ناشی از حرکت بازو، شل بودن مچبند، یا اطمینان پایین حسگر (زیر ۵۰٪)، و همچنین خوانشهای مجاور نویز حرکتی را فیلتر میکند. چون دقیقههای نامعتبر مستثنی میشوند،
پوشش در سطح دقیقه میتواند پراکنده باشد و انتظار میرود که در مُهر زمان فاصله وجود داشته باشد. هر دو
oxygen-saturation و daily-oxygen-saturation به خوانشهای معتبر یکسانی
متکی هستند. برای جزئیات مربوط به معیارهای اعتبارسنجی، به فیلتر کردن SpO2 در سطح دقیقه و اعتبار دادهها مراجعه کنید.
نمای همهجانبه از سلامت خواب و بازیابی
اگرچه هر سنجه اطلاعات آماری خاصی ارائه میدهد، اما این سنجهها عمیقاً با یکدیگر مرتبط هستند و باهم دیدی جامع از بهبودی کاربر ارائه میدهند. مراحل خواب (سبک، عمیق، REM) پایه ساختاری استراحت را فراهم میکنند، درحالیکه نشانگرهای فیزیولوژیکی مانند HRV و SpO2 نشان میدهند که بدن چگونه بهطور فیزیکی به آن استراحت پاسخ میدهد. برای مثال، یک جلسه خواب باکیفیت با خواب «عمیق» بهینه اغلب با «تغییرپذیری ضربان قلب» بالاتر مرتبط است که نشاندهنده بازیابی مؤثر سیستم عصبی خودمختار است.
ترکیب این موارد با مشتقات نرخ تنفس و دمای خواب به برنامهها امکان میدهد اختلالات احتمالی را شناسایی کنند. افزایش ناگهانی نرخ تنفس یا انحراف در دمای خواب میتواند توضیح دهد که چرا کاربر ممکن است زمان کمتری را در مراحل ترمیمی گذرانده باشد. توسعهدهندگان با تجزیهوتحلیل این نوع دادهها بهصورت همزمان میتوانند ارزیابی جامعی از بهداشت خواب و روندهای سلامتی بلندمدت ارائه دهند.
رهنمودها
هنگام ادغام سنجههای خواب در برنامهتان، از این دستورالعملها استفاده کنید:
- جزئیات جلسه: برای نشان دادن مراحل خواب کاربر (سبک، عمیق، REM، بیدار)
و بیداریهای کوتاه، نوع داده
sleepرا پُرسمان کنید. - بیداریهای شبانه: برای ردیابی رویدادهای بیداری نیمهشب بدون جریانهای حسگر خام، فاصلههای مرحله
sleepرا بررسی کنید و موارد دارایtype: "AWAKE"(برای هر دو گزارش خوابSTAGESوCLASSIC) را فیلتر کنید یاoutOfBedSegmentsرا بررسی کنید. - تأخیر و کارایی: از
summary.minutesToFallAsleepو فرمول کارایی خواب برای تحلیل تأخیر خواب استفاده کنید. توجه داشته باشید کهsummary.minutesToFallAsleepزمانی پر میشود که گزارشهای خواب بهصورت دستی ویرایش شده باشند (metadata.manuallyEditedبرابر باtrueاست) یا بهطور صریح ثبت شده باشند. - پایش فیزیولوژیکی: برای پایش پیشرفته سلامتی، دادههای جلسه خواب را با سنجههای فیزیولوژیکی و بازیابی مثل
respiratory-rate-sleep-summary،daily-sleep-temperature-derivations،daily-heart-rate-variability، وdaily-oxygen-saturationترکیب کنید.
محاسبه کل زمان خواب عمیق
برای محاسبه کل زمانی که کاربر در مرحله خواب عمیق ترمیمی برای یک شب خاص سپری کرده است:
- نوع داده
sleepرا برای محدوده زمانی مشخصشده جستجو کنید. - در فهرست مراحل تکرار کنید و فاصلههایی را که
typeDEEPاست شناسایی کنید. - مدت زمان (زمان پایان - زمان شروع) را برای هر بازه خواب عمیق محاسبه کنید و آنها را جمع کنید.
مجموع حاصل، کل مدت فیزیکی خواب عمیق را برای آن جلسه ارائه میدهد.