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 단계 간격과 달리 짧은 각성은 주변 수면 단계와 중복될 수 있는 별도의 세그먼트입니다. 기본 수면 단계 구조를 방해하지 않고 뒤척임과 미세 각성에 대한 상세한 정보를 제공합니다.

예

{
  "name": "sleeps/12345",
  "startTime": "2026-04-20T22:30:00Z",
  "endTime": "2026-04-21T06:30:00Z",
  "sleepType": "STAGES",
  "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는 샘플 호흡수 (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 데이터 유형을 쿼리합니다.
  • 생리적 모니터링: 고급 건강 모니터링을 위해 수면 세션 데이터를 respiratory-rate-sleep-summary, daily-sleep-temperature-derivations, daily-heart-rate-variability, daily-oxygen-saturation과 같은 생리적 및 회복 측정항목과 결합합니다.
  • 조정: reconcile 작업을 사용하여 서로 다른 기기 (예: 웨어러블과 매트리스 센서)의 중복된 수면 로그가 단일 '기본' 수면 기록으로 병합되도록 합니다.

깊은 수면 총시간 계산

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

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

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

이전
단계