Google Health API는 휴식 중 수면 시간, 수면의 질, 생리적 측정항목을 비롯한 사용자의 수면 패턴을 추적하는 데이터 유형을 제공합니다. 이러한 측정항목은 애플리케이션이 회복, 수면 위생, 장기적인 건강 추세에 관한 인사이트를 제공하는 데 도움이 됩니다.
심박 변이도 (HRV), 산소 포화도 (SpO2), 호흡수와 같은 생리적 측정항목은 신체가 안정된 휴식 상태에 있기 때문에 특히 수면 중에 기록됩니다. 이를 통해 API는 낮 시간의 스트레스 요인, 신체 활동 또는 다양한 환경 조건의 간섭 없이 사용자의 자율 신경 및 호흡기 건강의 기준을 포착할 수 있습니다.
이러한 데이터 유형 간의 차이점을 이해하여 애플리케이션에 적합한 측정항목을 결정하세요.
지원되는 데이터 유형
API는 수면 측정을 위해 다음과 같은 데이터 유형을 지원합니다.
| 데이터 유형 | 사용 가능한 작업 |
범위 |
|---|---|---|
|
일일 심박 변이도
dataType:
daily-heart-rate-variabilityfilter parameter: daily_heart_rate_variability
기록 유형: 일일
호환 기기
|
list, reconcile | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
일일 산소 포화도
dataType:
daily-oxygen-saturationfilter parameter: daily_oxygen_saturation
기록 유형: 일일
호환 기기
|
list, reconcile | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
일일 호흡수
dataType:
daily-respiratory-ratefilter parameter: daily_respiratory_rate
기록 유형: 일일
호환 기기
|
list, reconcile | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
일일 수면 온도 편차
dataType:
daily-sleep-temperature-derivationsfilter parameter: daily_sleep_temperature_derivations
기록 유형: 일일
호환 기기
|
list, reconcile | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
심박 변이도
dataType:
heart-rate-variabilityfilter parameter: heart_rate_variability
레코드 유형: 샘플
호환 기기
|
list, reconcile | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
산소 포화도
dataType:
oxygen-saturationfilter parameter: oxygen_saturation
레코드 유형: 샘플
스토리지 해상도: 1분
호환 기기
|
list, reconcile | .health_metrics_and_measurements.readonly.health_metrics_and_measurements.writeonly |
|
수면 중 호흡수 요약
dataType:
respiratory-rate-sleep-summaryfilter parameter: respiratory_rate_sleep_summary
레코드 유형: 샘플
호환 기기
|
list, reconcile | .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단계 간격과 달리, 짧은 각성은 주변 수면 단계와 겹칠 수 있는 별개의 세그먼트입니다. 이러한 지표는 기본 수면 단계 구조를 방해하지 않으면서 뒤척임과 미세 각성에 대한 세부적인 가시성을 제공합니다. - 야간 각성: 한밤중 각성 (예: 물을 마시기 위해 일어남)은 기기 내 센서 퓨전 (가속도계, 자이로스코프, 걸음 수)으로 식별됩니다. 애플리케이션은
type: "AWAKE"(CLASSIC및STAGES수면 기록 모두에서 사용됨)이 있는 간격에 대해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"
}
}
}
수면 세션 만들기
수면 세션 항목을 만들려면 sleep 데이터 포인트 엔드포인트에 POST 요청을 보냅니다. 응답에는 data-point-id가 포함된 name 필드가 포함되며, 이는 업데이트 (패치) 또는 삭제 요청에 사용될 수 있습니다.
요청
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"
}
]
}
}
}수면 효율 및 수면 잠복기 측정항목
이 API는 수면 단계 및 생리적 측정항목 외에도 수면의 질과 수면 시작을 정량화하는 주요 측정항목을 제공합니다. 수면 효율과 수면 시작 지연 시간은 사용자가 침대에 누워 있는 총 시간에 비해 얼마나 효과적으로 휴식을 취하는지 설명하는 표준 임상 측정항목으로, 수면 위생과 휴식에 대한 유용한 정보를 제공합니다.
수면 효율 점수
수면 효율은 침대에서 보낸 총 시간에 대한 수면 시간의 비율로 정의되는 표준 측정항목입니다. API는 다음 수식을 사용하여 수면 효율을 계산합니다.
Sleep Efficiency Score = round( (Total Minutes Asleep / Total Minutes In Bed) * 100 )
효율성 점수는 수면 수준 (단계) 분할 직전에 계산됩니다. API 응답(summary.minutesAsleep 필드)에서 반환되는 총 수면 시간(분)은 수면 수준이 계산된 후의 최종 결과를 반영합니다.
사용자 또는 연구원이 수면 기록의 시작 시간 또는 종료 시간을 수동으로 수정하면 API는 수면 효율성 점수를 다시 계산하고 새로운 취침 시간 및 기상 시간 경계 내에 기록된 센서 데이터에 따라 단계 파티션을 조정합니다.
수면 잠복기
수면 시작 지연 시간은 사용자가 잠들려고 하는 시점('취침' 또는 '소등' 시간의 시작)부터 수면이 시작될 때까지 경과한 시간을 측정합니다.
자동으로 생성된 로그 (metadata.manuallyEdited가 false)의 경우 잠들려는 명시적인 의도가 기록되지 않았으므로 summary.minutesToFallAsleep는 기본적으로 "0"입니다. 수면 시작 시간이 수동으로 기록되거나 수정되면(metadata.manuallyEdited가 true임) API는 summary.minutesToFallAsleep를 계산하고 summary.minutesAfterWakeUp와 함께 채웁니다.
조사 및 수동 로깅 가이드
참여자가 수면 시작 및 종료 시간을 수동으로 기록하거나 조정하는 경우:
- 수면 중 경계를 업데이트하면 수면
interval(및summary.minutesInSleepPeriod)이 변경됩니다. - 수면 수준 및 단계 파티션은 새 창 내에서 센서 데이터를 평가하도록 자동으로 조정됩니다.
- 수면 효율 점수,
summary.minutesToFallAsleep,summary.minutesAfterWakeUp는 업데이트된 기간을 기준으로 다시 도출됩니다.
일일 수면 온도 편차
일일 수면 온도 도출은 수면 중 사용자의 피부 온도 변화를 기준치와 비교하여 측정합니다. 이 데이터는 일반적으로 주요 수면 세션 후 하루에 한 번 보고됩니다.
호흡수
호흡수는 사용자의 분당 호흡수를 측정합니다. 수면 중에는 수면의 질과 잠재적인 수면 장애를 모니터링하는 핵심 측정항목입니다. API는 샘플 호흡수 (respiratory-rate), 일일 요약(daily-respiratory-rate), 세션 수준 수면 요약(respiratory-rate-sleep-summary)을 지원합니다.
심박 변이도 (HRV)
HRV는 심장 박동 간 시간의 변화를 측정합니다. 이는 자율 신경계 상태의 주요 지표입니다. 수면 중 HRV가 높으면 일반적으로 회복과 컨디션이 더 좋다는 의미이고, HRV가 낮으면 스트레스나 과도한 운동을 나타낼 수 있습니다. API는 샘플 HRV (heart-rate-variability) 및 일일 요약 (daily-heart-rate-variability)을 지원합니다.
산소 포화도
혈중 산소 포화도 (SpO2)는 혈액 내 총 헤모글로빈 대비 산소 포화 헤모글로빈의 비율을 나타냅니다. 수면 중 SpO2를 모니터링하면 잠재적인 호흡 장애를 감지하고 사용자가 밤새 적절한 산소 수치를 유지하는지 확인할 수 있습니다. API는 샘플 SpO2 (oxygen-saturation) 및 일일 요약(daily-oxygen-saturation)을 지원합니다.
분 수준 oxygen-saturation를 쿼리하면 Google Health API는 검증된 데이터 포인트만 반환하고 팔 움직임, 느슨한 손목 착용, 낮은 센서 신뢰도 (50% 미만)로 인한 잘못된 측정값과 움직임 노이즈에 인접한 측정값을 필터링합니다. 무효 분은 제외되므로 분 수준 적용 범위가 희소할 수 있으며 타임스탬프 간격이 발생할 수 있습니다. oxygen-saturation과 daily-oxygen-saturation은 모두 동일한 검증된 측정값에 의존합니다. 검증 기준에 관한 자세한 내용은 분 단위 SpO2 필터링 및 데이터 유효성을 참고하세요.
수면 건강 및 회복에 대한 종합적인 정보
각 측정항목은 구체적인 인사이트를 제공하지만 서로 밀접하게 관련되어 있으며 사용자의 회복 상태를 전체적으로 보여줍니다. 수면 단계 (얕은 수면, 깊은 수면, 렘수면)는 휴식의 구조적 기반을 제공하며, HRV 및 SpO2와 같은 생리적 지표는 신체가 휴식에 어떻게 물리적으로 반응하는지 나타냅니다. 예를 들어 최적의 깊은 수면을 취하는 고품질 수면 세션은 종종 높은 HRV와 관련이 있으며, 이는 자율 신경계의 효과적인 회복을 나타냅니다.
이를 호흡수 및 수면 온도 도출과 결합하면 애플리케이션에서 잠재적인 방해 요소를 식별할 수 있습니다. 호흡수가 갑자기 급증하거나 수면 온도가 달라지면 사용자가 회복 단계에서 보낸 시간이 줄어든 이유를 파악할 수 있습니다. 이러한 데이터 유형을 함께 분석하면 개발자는 수면 위생과 장기적인 건강 추세를 종합적으로 평가할 수 있습니다.
가이드라인
앱에 수면 측정항목을 통합할 때는 다음 가이드라인을 따르세요.
- 세션 세부정보: 사용자의 수면 단계 (얕은 수면, 깊은 수면, 렘 수면, 깨어 있는 상태)와 짧은 각성을 표시하려면
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와 같은 생리적 및 회복 측정항목과 결합합니다. - 조정:
reconcile작업을 사용하여 여러 기기 (예: 웨어러블 및 매트리스 센서)의 중복 수면 로그를 단일 '기본' 수면 기록으로 병합합니다.
깊은 수면 시간 계산
특정 밤에 사용자가 회복성 깊은 수면 단계에서 보낸 총 시간을 계산하려면 다음 단계를 따르세요.
- 지정된 기간의
sleep데이터 유형을 쿼리합니다. - 단계 목록을 반복하고
type가DEEP인 간격을 식별합니다. - 각 깊은 수면 간격의 지속 시간 (종료 시간 - 시작 시간)을 계산하고 합산합니다.
결과 합계는 해당 세션의 깊은 수면의 총 물리적 지속 시간을 제공합니다.