Google Health API로 수면 환경 개발

Google Health API는 휴식 중 수면 시간, 수면의 질, 생리적 측정항목 등 사용자의 수면 패턴을 추적하는 데이터 유형을 제공합니다. 이러한 측정항목은 애플리케이션이 회복, 수면 위생, 장기 건강 추이에 관한 인사이트를 제공하는 데 도움이 됩니다.

심박 변이도 (HRV), 산소 포화도 (SpO2), 호흡수와 같은 생리적 수치는 신체가 안정적인 휴식 상태에 있기 때문에 수면 중에만 기록됩니다. 이를 통해 API는 낮 동안의 스트레스 요인, 신체 활동 또는 다양한 환경 조건의 간섭 없이 사용자의 자율 신경계 및 호흡기 건강의 기준을 포착할 수 있습니다.

이러한 데이터 유형 간의 차이점을 이해하여 애플리케이션에 적합한 측정항목을 확인하세요.

지원되는 데이터 유형

API는 수면 측정을 위해 다음 데이터 유형을 지원합니다.

표: Google Health API 수면 데이터 유형
데이터 유형 사용 가능한
작업		 범위
일일 심박 변이도
dataType: daily-heart-rate-variability
filter parameter: daily_heart_rate_variability
기록 유형: 일일

호환 기기
목록, 조정 .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
일일 산소 포화도
dataType: daily-oxygen-saturation
filter parameter: daily_oxygen_saturation
기록 유형: 일일

호환 기기
목록, 조정 .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
일일 호흡수
dataType: daily-respiratory-rate
filter parameter: daily_respiratory_rate
기록 유형: 일일

호환 기기
목록, 조정 .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
일일 수면 온도 파생
dataType: daily-sleep-temperature-derivations
filter parameter: daily_sleep_temperature_derivations
기록 유형: 일일

호환 기기
목록, 조정 .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
심박 변이도
dataType: heart-rate-variability
filter parameter: heart_rate_variability
레코드 유형: 샘플

호환 기기
목록, 조정 .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
산소 포화도
dataType: oxygen-saturation
filter parameter: oxygen_saturation
레코드 유형: 샘플

호환 기기
목록, 조정 .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
호흡수 수면 요약
dataType: respiratory-rate-sleep-summary
filter parameter: respiratory_rate_sleep_summary
레코드 유형: 샘플

호환 기기
목록, 조정 .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
절전 모드
dataType: sleep
filter parameter: sleep
레코드 유형: 세션

호환 기기
list, get, reconcile, create, update, batchDelete .sleep.readonly
.sleep.writeonly

수면 세션 및 짧은 각성

수면 세션 (Sleep)은 밤에 잠을 자거나 낮에 낮잠을 자는 것과 같은 개별 수면 이벤트를 나타냅니다. 여기에는 짧은 각성이라고 하는 간략한 각성 전환 간격과 함께 중복되지 않는 수면 단계의 자세한 분석이 포함됩니다.

  • 수면 세션 (Sleep): 기본 휴식의 연속 타임라인을 파티셔닝하는 개별 수면 이벤트(LIGHT, DEEP, REM, AWAKE 단계 간격)를 나타냅니다.
  • 짧은 각성 (shortAwakenings): 휴식 중에 발생하는 짧은 절전 모드 전환 또는 각성입니다. 중복되지 않는 연속적인 수면 단계 진행을 나누는 표준 AWAKE 단계 간격과 달리 짧은 각성은 주변 수면 단계와 중복될 수 있는 별도의 세그먼트입니다. 기본 수면 단계 구조를 방해하지 않고 뒤척임과 미세 각성에 대한 상세한 정보를 제공합니다.
  • 야간 각성: 한밤중 각성 (예: 물을 마시기 위해 일어남)은 온디바이스 센서 융합 (가속도계, 자이로스코프, 걸음 수)으로 식별됩니다. Web API에서 애플리케이션은 수준 "wake" (클래식 수면) 또는 "awake" (단계 수면)으로 표시된 간격을 필터링하여 야간 각성을 감지할 수 있습니다.

예

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

수면 세션 만들기

수면 세션 항목을 만들려면 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에서 수면 효율 점수를 다시 계산하고 새 취침 시간과 기상 시간 경계 내에 기록된 센서 데이터에 따라 단계 파티션을 조정합니다.

수면 시작 지연 시간

수면 시작 대기 시간은 사용자가 잠들려고 하는 시점('침대에 있음' 또는 '소등' 시간의 시작)부터 수면이 시작될 때까지 경과된 시간을 측정합니다.

자동 감지 (auto_detect)를 사용하여 자동으로 생성된 로그의 경우 잠들려는 명시적 인텐트가 로깅되지 않았으므로 minutesToFallAsleep은 기본적으로 0입니다. 수면 중 시작 시간이 수동으로 기록되거나 수정되면 (로그를 manual로 변환) API가 minutesToFallAsleep을 minutesAfterWakeup와 함께 계산하여 채웁니다.

연구 및 수동 로깅을 위한 안내

참여자가 수동으로 녹화하거나 취침 시작 및 종료 시간을 조정하는 경우:

  1. 침대 내 경계를 업데이트하면 timeInBed 간격이 변경됩니다.
  2. 수면 수준과 단계 파티션이 자동으로 조정되어 새 창 내에서 센서 데이터를 평가합니다.
  3. 수면 효율 점수, minutesToFallAsleep, minutesAfterWakeup은 업데이트된 기간을 기반으로 다시 파생됩니다.

일일 수면 온도 파생

일일 수면 온도 파생 변수는 수면 중 사용자의 피부 온도를 기준치와 비교하여 변화를 측정합니다. 이 데이터는 일반적으로 주요 수면 세션이 끝난 후 하루에 한 번 보고됩니다.

호흡수

호흡수는 분당 호흡수를 측정합니다. 수면 중에는 수면의 질과 잠재적인 방해 요소를 모니터링하는 데 중요한 측정항목입니다. 이 API는 샘플 호흡수 (respiratory-rate), 일일 요약(daily-respiratory-rate), 세션 수준 수면 요약(respiratory-rate-sleep-summary)을 지원합니다.

심박 변이도 (HRV)

HRV는 심장 박동 간 시간의 변화를 측정합니다. 수면 중 HRV는 자율 신경계의 상태를 나타내는 주요 지표입니다. 일반적으로 수면 중 HRV가 높을수록 회복과 컨디션이 더 좋다는 의미이며, HRV가 낮을수록 스트레스나 과도한 훈련을 나타낼 수 있습니다. 이 API는 샘플 HRV (heart-rate-variability)와 일일 요약 (daily-heart-rate-variability)을 지원합니다.

혈중 산소 포화도(SpO2)

SpO2는 혈액 내 총 헤모글로빈 대비 산소 포화 헤모글로빈의 비율을 나타냅니다. 수면 중 SpO2를 모니터링하는 것은 잠재적인 호흡 장애를 감지하고 사용자가 밤새 적절한 산소 수준을 유지하도록 하는 데 매우 중요합니다. 이 API는 샘플 SpO2(oxygen-saturation)와 일일 요약 (daily-oxygen-saturation)을 지원합니다.

수면 건강 및 회복에 대한 종합적인 정보

각 측정항목은 구체적인 통계를 제공하지만 서로 깊이 관련되어 있으며 함께 사용자의 회복에 대한 전체적인 관점을 제공합니다. 수면 단계 (얕은 수면, 깊은 수면, 렘수면)는 휴식의 구조적 기반을 제공하고, HRV 및 SpO2와 같은 생리적 지표는 신체가 휴식에 어떻게 신체적으로 반응하는지 나타냅니다. 예를 들어 최적의 깊은 수면을 취한 고품질 수면 세션은 자율 신경계의 효과적인 회복을 나타내는 높은 HRV와 관련이 있는 경우가 많습니다.

이를 호흡수 및 수면 온도 파생과 결합하면 애플리케이션에서 잠재적인 방해 요소를 식별할 수 있습니다. 호흡수 급증 또는 수면 온도 편차는 사용자가 회복 단계에 더 적은 시간을 보낸 이유를 파악하는 데 도움이 될 수 있습니다. 개발자는 이러한 데이터 유형을 함께 분석하여 수면 위생 및 장기적인 건강 추이를 종합적으로 평가할 수 있습니다.

가이드라인

앱에 수면 측정항목을 통합할 때는 다음 가이드라인을 사용하세요.

  • 세션 세부정보: 사용자의 수면 단계 (얕은 수면, 깊은 수면, 렘 수면, 깨어 있음)와 짧은 각성을 표시하려면 sleep 데이터 유형을 쿼리합니다.
  • 야간 각성: 원시 센서 스트림 없이 한밤중 각성 이벤트를 추적하려면 sleep 단계 간격을 검사하고 단계 유형이 AWAKE (또는 클래식 수면 로그의 경우 wake)인 항목을 필터링합니다.
  • 지연 시간 및 효율성: minutesToFallAsleep 및 수면 효율 공식으로 수면 지연 시간을 분석합니다. 수면 로그를 수동으로 수정하거나 명시적으로 기록하면 minutesToFallAsleep가 채워집니다.
  • 생리적 모니터링: 고급 건강 모니터링을 위해 수면 세션 데이터를 respiratory-rate-sleep-summary, daily-sleep-temperature-derivations, daily-heart-rate-variability, daily-oxygen-saturation과 같은 생리적 및 회복 측정항목과 결합합니다.
  • 조정: reconcile 작업을 사용하여 서로 다른 기기 (예: 웨어러블과 매트리스 센서)의 중복된 수면 로그가 단일 '기본' 수면 기록으로 병합되도록 합니다.

깊은 수면 총시간 계산

특정 밤에 사용자가 회복성 깊은 수면 단계에서 보낸 총 시간을 계산하려면 다음 단계를 따르세요.

  1. 지정된 기간의 sleep 데이터 유형을 쿼리합니다.
  2. 단계 목록을 반복하여 type가 DEEP인 간격을 식별합니다.
  3. 각 깊은 수면 간격의 지속 시간 (종료 시간 - 시작 시간)을 계산하고 합산합니다.

결과 합계는 해당 세션의 총 실제 깊은 수면 시간을 제공합니다.

이전
단계