API Google Health cung cấp các loại dữ liệu theo dõi thói quen ngủ của người dùng, bao gồm cả thời lượng, chất lượng và các chỉ số sinh lý trong khi nghỉ ngơi. Các chỉ số này giúp ứng dụng cung cấp thông tin chi tiết về quá trình hồi phục, thói quen ngủ và xu hướng sức khoẻ lâu dài.
Các chỉ số sinh lý như Sự thay đổi tần số tim (HRV), Độ bão hoà oxy (SpO2) và nhịp thở được ghi lại cụ thể trong khi ngủ vì cơ thể đang ở trạng thái nghỉ ngơi ổn định. Điều này cho phép API thu thập dữ liệu cơ sở về sức khoẻ hô hấp và hệ thần kinh tự chủ của người dùng mà không bị ảnh hưởng bởi các yếu tố gây căng thẳng vào ban ngày, hoạt động thể chất hoặc điều kiện môi trường khác nhau.
Hãy tìm hiểu sự khác biệt giữa các loại dữ liệu này để xác định chỉ số nào phù hợp với ứng dụng của bạn.
Các loại dữ liệu được hỗ trợ
API này hỗ trợ các loại dữ liệu sau để đo lường giấc ngủ:
| Loại dữ liệu | Các thao tác có thể thực hiện |
Phạm vi |
|---|---|---|
|
Sự thay đổi tần số tim hằng ngày
dataType:
daily-heart-rate-variabilityfilter parameter: daily_heart_rate_variability
Loại bản ghi: Hằng ngày
Thiết bị tương thích
|
danh sách, đối chiếu | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Độ bão hòa oxy hằng ngày
dataType:
daily-oxygen-saturationfilter parameter: daily_oxygen_saturation
Loại bản ghi: Hằng ngày
Thiết bị tương thích
|
danh sách, đối chiếu | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Nhịp thở hằng ngày
dataType:
daily-respiratory-ratefilter parameter: daily_respiratory_rate
Loại bản ghi: Hằng ngày
Thiết bị tương thích
|
danh sách, đối chiếu | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Độ lệch nhiệt độ khi ngủ hằng ngày
dataType:
daily-sleep-temperature-derivationsfilter parameter: daily_sleep_temperature_derivations
Loại bản ghi: Hằng ngày
Thiết bị tương thích
|
danh sách, đối chiếu | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Sự thay đổi tần số tim
dataType:
heart-rate-variabilityfilter parameter: heart_rate_variability
Loại bản ghi: Mẫu
Thiết bị tương thích
|
danh sách, đối chiếu | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Độ bão hoà oxy
dataType:
oxygen-saturationfilter parameter: oxygen_saturation
Loại bản ghi: Mẫu
Độ phân giải của bộ nhớ: 1 phút
Thiết bị tương thích
|
danh sách, đối chiếu | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Bản tóm tắt về nhịp thở khi ngủ
dataType:
respiratory-rate-sleep-summaryfilter parameter: respiratory_rate_sleep_summary
Loại bản ghi: Mẫu
Thiết bị tương thích
|
danh sách, đối chiếu | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
Ngủ
dataType:
sleepfilter parameter: sleep
Loại bản ghi: Phiên
Thiết bị tương thích
|
list, get, reconcile, create, update, batchDelete | .sleep.readonly.sleep.writeonly |
Phiên ngủ và những lần thức giấc ngắn
Phiên ngủ (Sleep) đại diện cho một sự kiện ngủ riêng biệt, chẳng hạn như một giấc ngủ đêm hoặc giấc ngủ trưa. Dữ liệu này bao gồm thông tin chi tiết về các giai đoạn ngủ không trùng lặp, cùng với các khoảng thời gian chuyển đổi ngắn sang trạng thái thức, được gọi là những lần thức giấc ngắn.
- Phiên ngủ (
Sleep): Biểu thị một sự kiện ngủ riêng biệt (khoảng thời gian của giai đoạnLIGHT,DEEP,REM,AWAKE) phân chia dòng thời gian liền kề của giấc ngủ chính. - Thức giấc trong thời gian ngắn (
shortAwakenings): Những lần chuyển sang trạng thái thức giấc hoặc thức giấc trong thời gian ngắn khi đang nghỉ ngơi. Không giống như các khoảng thời gian giai đoạnAWAKEtiêu chuẩn (chia tiến trình giai đoạn ngủ liền kề không chồng chéo), các lần thức giấc ngắn là các phân đoạn riêng biệt có thể chồng chéo với các giai đoạn ngủ xung quanh. Các sự kiện này cung cấp thông tin chi tiết về tình trạng bồn chồn và thức giấc trong thời gian ngắn mà không làm gián đoạn cấu trúc các giai đoạn ngủ chính. - Thức giấc giữa đêm: Việc thức giấc giữa đêm (chẳng hạn như thức dậy để uống nước) được xác định bằng cách kết hợp các cảm biến trên thiết bị (gia tốc kế, con quay hồi chuyển và số bước). Ứng dụng có thể phát hiện tình trạng thức giấc vào ban đêm bằng cách lọc
stagescho các khoảng thời gian cótype: "AWAKE"(được dùng trong cả nhật ký giấc ngủCLASSICvàSTAGES) hoặc bằng cách kiểm traoutOfBedSegments.
Ví dụ
{
"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"
}
}
}
Tạo phiên ngủ
Để tạo một mục phiên ngủ, hãy gửi yêu cầu POST đến điểm cuối của điểm dữ liệu sleep. Phản hồi bao gồm trường name chứa data-point-id, có thể được dùng trong yêu cầu Cập nhật (Bản vá) hoặc Xoá.
Yêu cầu
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"
}
]
}
}Phản hồi
{
"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"
}
]
}
}
}Truy vấn và điều chỉnh phiên ngủ
Để truy xuất nhật ký giấc ngủ của người dùng, hãy truy vấn điểm cuối reconcile thay vì điểm cuối list. Khi người dùng theo dõi giấc ngủ trên nhiều nguồn, chẳng hạn như thiết bị theo dõi đeo được và Health Connect, list sẽ trả về mọi bản ghi trùng lặp. Việc cộng tổng kết quả list thô có thể khiến thời lượng ngủ hằng ngày bị tính hai lần. Điểm cuối reconcile loại bỏ các nhật ký trùng lặp thành một luồng duy nhất và xác định phiên ngủ chính của mỗi ngày bằng cách đặt sleep.metadata.mainSleep thành true. Để so sánh cả hai điểm cuối, hãy xem phần So sánh điểm cuối list và reconcile.
Khi truy vấn sleep bằng list hoặc reconcile, hãy lưu ý các quy tắc ràng buộc sau đây về việc lọc và phân trang:
- Chỉ lọc các truy vấn
sleeptheo thời gian kết thúc của phiên bằng cách sử dụngsleep.interval.end_time(thời gian thực tế theo giờ UTC) hoặcsleep.interval.civil_end_time(giờ dân sự địa phương). Kết hợp ranh giới dưới và trên bằng cách sử dụng toán tử so sánh>=và<vớiAND. - Đừng lọc các truy vấn
sleeptheo thời gian bắt đầu hoặc bằngOR. Việc lọc theosleep.interval.start_timehoặcsleep.interval.civil_start_timesẽ trả về lỗi400 Bad Request(INVALID_ARGUMENT) kèm theo lý doINVALID_DATA_POINT_FILTER_DATA_TYPE_MEMBER. Việc sử dụngORsẽ trả về lỗi400 Bad Request(INVALID_ARGUMENT) kèm theo lý doINVALID_DATA_POINT_FILTER_EXPRESSION_STRUCTURE. Để biết thông tin chi tiết về cú pháp, hãy xem Hướng dẫn lọc dữ liệu. - Cả
listvàreconcileđều thực thipageSizemặc định và tối đa là25chosleep. Nếu bạn truyền mộtpageSizelớn hơn25, API sẽ giới hạn giá trị ở mức25và trả về lỗi400 Bad Requestnếu giá trị là số âm. Để đồng bộ hoá nhật ký giấc ngủ của nhiều tuần, hãy phân trang bằngnextPageTokencho đến khi mã thông báo trống. Để biết thông tin chi tiết, hãy xem phần Truy vấn dữ liệu trong quá khứ.
Ví dụ: yêu cầu sau đây truy vấn các phiên ngủ đã điều chỉnh kết thúc trong phạm vi ngày dân sự hai tuần:
Yêu cầu
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
Phản hồi
{
"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"
}Chỉ số về hiệu quả giấc ngủ và độ trễ giấc ngủ
Ngoài các giai đoạn ngủ và chỉ số sinh lý, API này còn cung cấp các chỉ số chính giúp định lượng chất lượng giấc ngủ và thời điểm bắt đầu ngủ. Hiệu quả giấc ngủ và độ trễ khi bắt đầu ngủ là các chỉ số lâm sàng tiêu chuẩn mô tả mức độ hiệu quả của việc nghỉ ngơi của người dùng so với tổng thời gian họ nằm trên giường, cung cấp thông tin chi tiết về vệ sinh giấc ngủ và sự thư giãn.
Điểm hiệu quả giấc ngủ
Hiệu quả giấc ngủ là một chỉ số tiêu chuẩn được định nghĩa là tỷ lệ thời gian ngủ so với tổng thời gian nằm trên giường. API này tính toán hiệu quả giấc ngủ bằng công thức sau:
Sleep Efficiency Score = round( (Total Minutes Asleep / Total Minutes In Bed) * 100 )
Điểm hiệu quả được tính ngay trước khi phân vùng mức độ (giai đoạn) giấc ngủ. Tổng số phút ngủ được trả về trong phản hồi của API (trong trường summary.minutesAsleep) phản ánh kết quả cuối cùng sau khi tính toán các mức độ ngủ.
Nếu người dùng hoặc nhà nghiên cứu sửa đổi thủ công thời gian bắt đầu hoặc kết thúc của nhật ký giấc ngủ, thì API sẽ tính toán lại điểm hiệu quả giấc ngủ và điều chỉnh các phân vùng giai đoạn theo dữ liệu cảm biến được ghi lại trong ranh giới thời gian đi ngủ và thời gian thức dậy mới.
Độ trễ khi bắt đầu ngủ
Độ trễ khi bắt đầu ngủ đo lường thời gian trôi qua từ khi người dùng có ý định đi ngủ (bắt đầu thời gian "trên giường" hoặc "tắt đèn") cho đến khi bắt đầu ngủ.
Đối với nhật ký được tạo tự động (metadata.manuallyEdited là false),
summary.minutesToFallAsleep mặc định là "0" vì không có ý định rõ ràng nào về việc
ngủ được ghi lại. Khi thời gian bắt đầu trên giường được ghi lại hoặc chỉnh sửa theo cách thủ công (metadata.manuallyEdited là true), API sẽ tính toán và điền summary.minutesToFallAsleep cùng với summary.minutesAfterWakeUp.
Hướng dẫn nghiên cứu và ghi nhật ký thủ công
Khi người tham gia ghi lại hoặc điều chỉnh thời gian bắt đầu và kết thúc giấc ngủ theo cách thủ công:
- Việc cập nhật ranh giới thời gian trên giường sẽ thay đổi
interval(vàsummary.minutesInSleepPeriod) của giấc ngủ. - Mức độ ngủ và phân vùng giai đoạn sẽ tự động điều chỉnh để đánh giá dữ liệu cảm biến trong khoảng thời gian mới.
- Điểm hiệu quả giấc ngủ,
summary.minutesToFallAsleepvàsummary.minutesAfterWakeUpđược tính lại dựa trên khung thời gian mới.
Độ lệch nhiệt độ khi ngủ hằng ngày
Độ lệch nhiệt độ khi ngủ hằng ngày đo lường sự thay đổi về nhiệt độ trên da của người dùng trong khi ngủ so với mức cơ sở. Dữ liệu này thường được báo cáo mỗi ngày một lần sau một phiên ngủ chính.
Nhịp thở
Nhịp thở đo số lần thở của người dùng mỗi phút. Trong khi ngủ, đây là chỉ số quan trọng để theo dõi chất lượng giấc ngủ và các yếu tố có thể gây gián đoạn giấc ngủ. API này hỗ trợ nhịp thở (respiratory-rate), thông tin tóm tắt hằng ngày (daily-respiratory-rate) và bản tóm tắt về giấc ngủ theo phiên (respiratory-rate-sleep-summary).
Sự thay đổi tần số tim (HRV)
HRV đo lường sự thay đổi về khoảng thời gian giữa mỗi nhịp tim. Đây là một chỉ báo quan trọng về trạng thái của hệ thần kinh tự chủ; HRV cao trong khi ngủ thường cho thấy khả năng hồi phục và chỉ số sẵn sàng tốt hơn, trong khi HRV thấp có thể cho biết tình trạng căng thẳng hoặc tập luyện quá sức. API này hỗ trợ HRV mẫu (heart-rate-variability) và thông tin tóm tắt hằng ngày (daily-heart-rate-variability).
Độ bão hoà oxy
Độ bão hoà oxy trong máu (SpO2) thể hiện tỷ lệ phần trăm hemoglobin bão hoà oxy so với tổng lượng hemoglobin trong máu. Việc theo dõi SpO2 trong khi ngủ giúp phát hiện các vấn đề tiềm ẩn về hô hấp và xác nhận xem người dùng có duy trì mức oxy thích hợp suốt đêm hay không. API này hỗ trợ
mẫu SpO2 (oxygen-saturation) và thông tin tóm tắt hằng ngày
(daily-oxygen-saturation).
Khi bạn truy vấn oxygen-saturation ở cấp độ phút, API Google Health chỉ trả về các điểm dữ liệu đã xác thực và lọc ra các kết quả đo không hợp lệ do chuyển động của cánh tay, cổ tay không vừa hoặc độ tin cậy của cảm biến thấp (dưới 50%), cũng như các kết quả đo gần với tiếng ồn chuyển động. Vì số phút không hợp lệ bị loại trừ, nên mức độ phù hợp theo phút có thể thưa thớt và có thể có khoảng trống về dấu thời gian. Cả oxygen-saturation và daily-oxygen-saturation đều dựa vào cùng một kết quả đo lường đã xác thực. Để biết thông tin chi tiết về tiêu chí xác thực, hãy xem phần Lọc SpO2 theo phút và tính hợp lệ của dữ liệu.
Thông tin tổng quan về chất lượng giấc ngủ và khả năng hồi phục
Mặc dù mỗi chỉ số cung cấp thông tin chi tiết cụ thể, nhưng chúng có mối liên hệ sâu sắc và cùng nhau cung cấp thông tin tổng quan về quá trình hồi phục của người dùng. Các giai đoạn ngủ (ngủ nông, ngủ sâu, ngủ REM) là nền tảng của giấc ngủ, còn các chỉ số sinh lý như HRV và SpO2 cho biết cơ thể phản ứng như thế nào về mặt thể chất đối với giấc ngủ đó. Ví dụ: một phiên ngủ chất lượng cao với thời gian ngủ sâu tối ưu thường tương quan với HRV cao hơn, cho thấy hệ thần kinh tự chủ đang phục hồi hiệu quả.
Khi kết hợp các chỉ số này với nhịp thở và nhiệt độ khi ngủ, ứng dụng có thể xác định các yếu tố có thể gây gián đoạn. Tần suất hô hấp tăng đột ngột hoặc nhiệt độ khi ngủ thay đổi có thể giải thích lý do người dùng có thể đã dành ít thời gian hơn cho các giai đoạn phục hồi. Bằng cách phân tích đồng thời các loại dữ liệu này, nhà phát triển có thể đưa ra đánh giá toàn diện về thói quen ngủ và xu hướng sức khoẻ dài hạn.
Nguyên tắc
Khi tích hợp chỉ số về giấc ngủ vào ứng dụng, hãy làm theo các nguyên tắc sau:
- Chi tiết về phiên: Để cho biết các giai đoạn ngủ của người dùng (Ngủ nông, Ngủ sâu, Ngủ REM, Thức) và những lần thức giấc ngắn, hãy truy vấn loại dữ liệu
sleep. - Thức giấc vào ban đêm: Để theo dõi các sự kiện thức giấc vào giữa đêm mà không có luồng cảm biến thô, hãy kiểm tra các khoảng thời gian của giai đoạn
sleepvà lọc các mục cótype: "AWAKE"(cho cả nhật ký giấc ngủSTAGESvàCLASSIC) hoặc kiểm traoutOfBedSegments. - Độ trễ và hiệu quả: Sử dụng
summary.minutesToFallAsleepvà công thức hiệu quả giấc ngủ để phân tích độ trễ giấc ngủ. Xin lưu ý rằngsummary.minutesToFallAsleepđược điền sẵn khi nhật ký giấc ngủ được chỉnh sửa theo cách thủ công (metadata.manuallyEditedlàtrue) hoặc được ghi lại một cách rõ ràng. - Theo dõi sinh lý: Để theo dõi sức khoẻ nâng cao, hãy kết hợp dữ liệu phiên ngủ với các chỉ số sinh lý và phục hồi như
respiratory-rate-sleep-summary,daily-sleep-temperature-derivations,daily-heart-rate-variabilityvàdaily-oxygen-saturation.
Tính tổng thời gian ngủ sâu
Cách tính tổng thời gian người dùng ngủ sâu để phục hồi sức khoẻ trong một đêm cụ thể:
- Truy vấn loại dữ liệu
sleepcho phạm vi thời gian đã chỉ định. - Lặp lại danh sách giai đoạn và xác định các khoảng thời gian mà
typelàDEEP. - Tính thời lượng (Thời gian kết thúc – Thời gian bắt đầu) cho mỗi khoảng thời gian ngủ sâu và tính tổng các khoảng thời gian đó.
Tổng thu được là tổng thời lượng thực tế của giấc ngủ sâu trong phiên đó.