API Documentation

Sleep

Sleep period is a nearly continuous, longish period of time spent lying down in bed. For each sleep period it detects, Oura ring performs sleep analysis and stores a set of measurement parameters that summarize the period. The ring calculates the sleep period specific parameters within four hours from the period end, but sleep analysis is always triggered when you open the application.

Example data

{
  "summary_date": "2017-11-05",
  "period_id": 0,
  "is_longest": 1,
  "timezone": 120,
  "bedtime_start": "2017-11-06T02:13:19+02:00",
  "bedtime_end": "2017-11-06T08:12:19+02:00",
  "score": 70,
  "score_total": 57,
  "score_disturbances": 83,
  "score_efficiency": 99,
  "score_latency": 88,
  "score_rem": 97,
   "score_deep": 59,
  "score_alignment": 31,
  "total": 20310,
  "duration": 21540,
  "awake": 1230,
  "light": 10260,
  "rem": 7140,
  "deep": 2910,
  "onset_latency": 480,
  "restless": 39,
  "efficiency": 94,
  "midpoint_time": 11010,
  "hr_lowest": 49,
  "hr_average": 56.375,
  "rmssd": 54
  "breath_average": 13,
  "temperature_delta": -0.06,
  "hypnogram_5min": "443432222211222333321112222222222111133333322221112233333333332232222334",
  "hr_5min": [0, 53, 51, 0, 50, 50, 49, 49, 50, 50, 51, 52, 52, 51, 53, 58, 60, 60, 59, 58, 58, 58, 58, 55, 55, 55, 55, 56, 56, 55, 53, 53, 53, 53, 53, 53, 57, 58, 60, 60, 59, 57, 59, 58, 56, 56, 56, 56, 55, 55, 56, 56, 57, 58, 55, 56, 57, 60, 58, 58, 59, 57, 54, 54, 53, 52, 52, 55, 53, 54, 56, 0],
  "rmssd_5min": [0, 0, 62, 0, 75, 52, 56, 56, 64, 57, 55, 78, 77, 83, 70, 35, 21, 25, 49, 44, 48, 48, 62, 69, 66, 64, 79, 59, 67, 66, 70, 63, 53, 57, 53, 57, 38, 26, 18, 24, 30, 35, 36, 46, 53, 59, 50, 50, 53, 53, 57, 52, 41, 37, 49, 47, 48, 35, 32, 34, 52, 57, 62, 57, 70, 81, 81, 65, 69, 72, 64, 0]
}

Fields

sleep.summary_date

  • Type: String
  • Format: YYYY-MM-DD

Date when the sleep period ended.

sleep.period_id

  • Type: Int

Index of the sleep period among sleep periods with the same summary_date, where 0 = first sleep period of the day.

sleep.timezone

  • Type: Int
  • Unit: Minutes

Timezone offset from UTC as minutes. For example, EEST (Eastern European Summer Time, +3h) is 180. PST (Pacific Standard Time, -8h) is -480. Note that timezone information is also available in the datetime values themselves, see for example.bedtime_start

sleep.bedtime_start

Local time when the sleep period started

sleep.bedtime_end

Local time when the sleep period ended.

sleep.duration

  • Type: Int
  • Unit: seconds

Total duration of the sleep period (sleep.duration = sleep.bedtime_end - sleep.bedtime_start).

sleep.total

  • Type: Int
  • Unit: seconds

Total amount of sleep registered during the sleep period (sleep.total = sleep.rem + sleep.light + sleep.deep).

sleep.awake

  • Type: Int
  • Unit: seconds

Total amount of awake time registered during the sleep period.

sleep.rem

  • Type: Int
  • Unit: seconds

Total amount of REM sleep registered during the sleep period.

sleep.light

  • Type: Int
  • Unit: seconds

Total amount of light (N1 or N2) sleep registered during the sleep period.

sleep.deep

  • Type: Int
  • Unit: seconds

Total amount of deep (N3) sleep registered during the sleep period.

sleep.hr_lowest

  • Type: Int
  • Unit: beats per minute

The lowest heart rate (5 minutes sliding average) registered during the sleep period.

sleep.hr_average

  • Type: Int
  • Unit: beats per minute

The average heart rate registered during the sleep period.

sleep.hr_5min

  • Type: Array of integers
  • Unit: beats per minute

Average heart rate for each beginning 5 minutes of the sleep period, the first period starting from sleep.bedtime_start.

sleep.efficiency

  • Type: Int
  • Range: 0-100%

Sleep efficiency is the percentage of the sleep period spent asleep (100% * sleep.total / sleep.duration).

sleep.onset_latency

  • Type: Int
  • Unit: seconds

Detected latency from bedtime_start to the beginning of the first five minutes of persistent sleep.

sleep.midpoint_time

  • Type: Int
  • Unit: seconds

The time in seconds from the start of sleep to the midpoint of sleep. The midpoint ignores awake periods.

sleep.restless

  • Type: Integer
  • Unit: %

Restlessness of the sleep time, i.e. percentage of sleep time when the user was moving.

sleep.temperature_delta

  • Type: Float
  • Unit: Celsius

Skin temperature deviation from the long-term temperature average.

sleep.breath_average

  • Type: Float
  • Unit: breaths per minute

Average respiratory rate.

sleep.score

  • Type: Int
  • Range: 1-100, or 0 if not available.

Sleep score represents overall sleep quality during the sleep period. It is calculated as a weighted average of sleep score contributors that represent one aspect of sleep quality each. The sleep score contributor values are also available as separate parameters.

sleep.score_total

  • Type: Int
  • Range: 1-100, or 0 if not available.

Represents total sleep time's (see sleep.total) contribution for sleep quality. The value depends on age of the user - the younger, the more sleep is needed for good score. The weight of sleep.score_total in sleep score calculation is 0.35.

sleep.score_rem

  • Type: Int
  • Range: 1-100, or 0 if not available.

Represents REM sleep time's (see sleep.rem) contribution for sleep quality. The value depends on age of the user - the younger, the more sleep REM is needed for good score. The weight of sleep.score_rem in sleep score calculation is 0.10.

sleep.score_deep

  • Type: Int
  • Range: 1-100, or 0 if not available.

Represents deep (N3) sleep time's (see sleep.deep) contribution for sleep quality. The value depends on age of the user - the younger, the more sleep is needed for good score. The weight of sleep.score_deep in sleep score calculation is 0.10.

sleep.score_efficiency

  • Type: Int
  • Range: 1-100, or 0 if not available.

Represents sleep efficiency's (see sleep.efficiency) contribution for sleep quality. The higher efficiency, the higher score. The weight of sleep.score_efficiency in sleep score calculation is 0.10.

sleep.score_latency

  • Type: Int
  • Range: 1-100, or 0 if not available.

Represents sleep onset latency's (see sleep.onset_latency) contribution for sleep quality. A latency of about 15 minutes gives best score. Latency longer than that many indicate problems falling asleep, whereas a very short latency may be a sign of sleep debt. The weight of sleep.score_latency in sleep score calculation is 0.10.

sleep.score_disturbances

  • Type: Int
  • Range: 1-100, or 0 if not available.

Represents sleep disturbances' contribution for sleep quality. Three separate measurements are used to calculate this contributor value:

  1. Wake-up count - the more wake-ups, the lower the score.
  2. Got-up count - the more got-ups, the lower the score.
  3. Restless sleep (sleep.restless) - the more motion detected during sleep, the lower the score.

Each of these three values has weight 0.05 in sleep score calculation, giving sleep.score_disturbances total weight of 0.15.

sleep.score_alignment

  • Type: Int
  • Range: 1-100, or 0 if not available.

Represents circadian alignment's contribution for sleep score. Sleep midpoint time (sleep.midpoint_time) between 12PM and 3AM gives highest score. The more the midpoint time deviates from that range, the lower the score. The weigh of sleep.score_alignment in sleep score calculation is 0.10.

sleep.hypnogram_5min

  • Type: String

A string that contains one character for each starting five minutes of the sleep period, so that the first period starts from sleep.bedtime.start: - '1' = deep (N3) sleep - '2' = light (N1 or N2) sleep - '3' = REM sleep - '4' = awake

sleep.rmssd

  • Type: Int
  • Unit: milliseconds

The average HRV calculated with rMSSD method.

sleep.rmssd_5min

  • Type: Array of integers
  • Unit: beats per minute

The average HRV (calculated using rMSSD method) for each beginning 5 minutes of the sleep period, the first period starting from sleep.bedtime_start.