API v2
...
Metrics
API Version 2 (V2)
Sleep
You can retrieve user sleep data by user_id and filter by date range
Get a sleep data by user_id
GET
Request
Query Parameters
user_id
String
required
User ID returned by add integration request. This key should be stored in your database against the user and used for all interactions with the Spike API.
start_date
String
required
Date from in YYYY-MM-DD format
end_date
String
required
Date to in YYYY-MM-DD format
Header Parameters
authorizationtoken
String
optional
Client access token (deprecated)
x-spike-auth
String
required
Client access token
Python
Node.js
Ruby
Java
Curl
1import requests
2
3url = "https://api.spikeapi.com/v2/metrics/sleep/?user_id=fa1e3803-6068-4ea7-9788-eccce210d30c&start_date=2020-05-01&end_date=2020-05-01"
4headers = {}
5headers['x-spike-auth'] = 'fa0b3803-1111-2222-9788-eccce210d41b'
6response = requests.request("GET", url, headers=headers)
7
8print(response.text)
Responses
200
1{
2 "user_id": "fa1e3803-6068-4ea7-9788-eccce210d30c",
3 "start_date": "2024-10-23",
4 "end_date": "2024-10-24",
5 "type": "sleep",
6 "source": [
7 {
8 "name": "oura",
9 "status": "ok"
10 }
11 ],
12 "data": [{
13 "date": "2024-10-24",
14 "bedtime_start": "2024-10-23T23:26:02",
15 "bedtime_end": "2024-10-24T08:13:37",
16 "timezone_offset": 7200,
17 "bedtime_duration": 33360,
18 "total_sleep": 30420,
19 "awake": 2940,
20 "light": 8190,
21 "rem": 6780,
22 "deep": 15450,
23 "hr_lowest": 56,
24 "hr_average": 61,
25 "efficiency": 0.91,
26 "latency": 900,
27 "temperature_delta": -0.04,
28 "average_hrv": 44,
29 "respiratory_rate": 14.875,
30 "standardized_sleep_score": 10,
31 "source_specific_sleep_score": 88,
32 "source": "oura",
33 "levels": [
34 {
35 "date_time": "2024-10-23T23:26:02",
36 "level": "awake",
37 "seconds": 300
38 }, {
39 "date_time": "2024-10-23T23:31:02",
40 "level": "awake",
41 "seconds": 300
42 }, {
43 ...EDITED...
44 }, {
45 "date_time": "2024-10-23T23:41:02",
46 "level": "light",
47 "seconds": 300
48 }, {
49 "date_time": "2024-10-23T23:46:02",
50 "level": "light",
51 "seconds": 300
52 }, {
53 "date_time": "2024-10-23T23:51:02",
54 "level": "deep",
55 "seconds": 300
56 }, {
57 "date_time": "2024-10-23T23:56:02",
58 "level": "deep",
59 "seconds": 300
60 }, {
61 ...EDITED...
62 }, {
63 "date_time": "2024-10-24T00:36:02",
64 "level": "rem",
65 "seconds": 300
66 },
67 ...EDITED...
68 ]
69 },
70 ]
71}
On older Apple devices that don't support sleep phases, unknown phase appears. It returns "inBed" or "asleepUnspecified" status.
1<style>
2@import url('https://fonts.googleapis.com/css2?family=Poppins:wght@300&display=swap');
3
4.h2, .h3, .list, .description{
5 font-family: 'Poppins', sans-serif;
6 font-weight: 500;
7}
8
9.h2 {
10 margin-top: -20px;
11 margin-bottom: 20px;
12
13 font-size: 30px;
14}
15
16.h3 {
17 font-size: 22px;
18 margin-top: -20px;
19}
20
21.list-wrapper {
22 white-space: normal;
23 margin-top: -10px;
24}
25
26.list, .description {
27 font-size: 14px;
28}
29
30</style>
31<h2 class="h2">Fields</h2>
32<h3 class="h3">Sleep.date</h3>
33<ul class="list-wrapper">
34 <li class="list">Type: String</li>
35 <li class="list">Format: YYYY-MM-DD</li>
36 <li class="list">Example: 2021-05-01</li>
37</ul><p class="description">The date when the sleep period ended</p>
38
39<h3 class="h3">Sleep.bedtime_start</h3>
40<ul class="list-wrapper">
41 <li class="list">Type: String</li>
42 <li class="list">Format: Date time, YYYY-MM-DDThh:mm:ss</li>
43 <li class="list">Example: 2021-05-01T01:12:13</li>
44</ul><p class="description">Local time when the sleep period started</p>
45
46<h3 class="h3">Sleep.bedtime_end</h3>
47<ul class="list-wrapper">
48 <li class="list">Type: String</li>
49 <li class="list">Format: Date time, YYYY-MM-DDThh:mm:ss</li>
50 <li class="list">Example: 2021-05-01T09:36:13</li>
51</ul><p class="description">Local time when the sleep period ended</p>
52
53<h3 class="h3">Sleep.timezone_offset</h3>
54<ul class="list-wrapper">
55 <li class="list">Type: Int</li>
56 <li class="list">Unit: Seconds</li>
57 <li class="list">Example: 2400</li>
58</ul><p class="description">Time zone offset from UTC as seconds</p>
59
60<h3 class="h3">Sleep.bedtime_duration</h3>
61<ul class="list-wrapper">
62 <li class="list">Type: Int</li>
63 <li class="list">Unit: Seconds</li>
64 <li class="list">Example: 28000</li>
65</ul><p class="description">Total duration of the sleep period (duration = bedtime_end - bedtime_start)</p>
66
67<h3 class="h3">Sleep.total_sleep</h3>
68<ul class="list-wrapper">
69 <li class="list">Type: Int</li>
70 <li class="list">Unit: Seconds</li>
71 <li class="list">Example: 26000</li>
72</ul><p class="description">Total amount of sleep registered during the sleep period (total = rem + light + deep)</p>
73
74<h3 class="h3">Sleep.awake</h3>
75<ul class="list-wrapper">
76 <li class="list">Type: Int</li>
77 <li class="list">Unit: Seconds</li>
78 <li class="list">Example: 2800</li>
79</ul><p class="description">Total amount of awake time registered during the sleep period</p>
80
81<h3 class="h3">Sleep.light</h3>
82<ul class="list-wrapper">
83 <li class="list">Type: Int</li>
84 <li class="list">Unit: Seconds</li>
85 <li class="list">Example: 18000</li>
86</ul><p class="description">Total amount of light sleep registered during the sleep period</p>
87
88<h3 class="h3">Sleep.rem</h3>
89<ul class="list-wrapper">
90 <li class="list">Type: Int</li>
91 <li class="list">Unit: Seconds</li>
92 <li class="list">Example: 5000</li>
93</ul><p class="description">Total amount of rem sleep registered during the sleep period</p>
94
95<h3 class="h3">Sleep.deep</h3>
96<ul class="list-wrapper">
97 <li class="list">Type: Int</li>
98 <li class="list">Unit: Seconds</li>
99 <li class="list">Example: 3000</li>
100</ul><p class="description">Total amount of deep sleep registered during the sleep period</p>
101
102<h3 class="h3">Sleep.hr_lowest</h3>
103<ul class="list-wrapper">
104 <li class="list">Type: Int</li>
105 <li class="list">Unit: Beats per minute</li>
106 <li class="list">Example: 50</li>
107</ul><p class="description">The lowest heart rate (5 minutes sliding average) registered during the sleep period</p>
108
109<h3 class="h3">Sleep.hr_average</h3>
110<ul class="list-wrapper">
111 <li class="list">Type: Int</li>
112 <li class="list">Unit: Beats per minute</li>
113 <li class="list">Example: 55</li>
114</ul><p class="description">The average heart rate registered during the sleep period</p>
115
116<h3 class="h3">Sleep.efficiency</h3>
117<ul class="list-wrapper">
118 <li class="list">Type: Float</li>
119 <li class="list">Range: 0.0 - 1.0</li>
120 <li class="list">Example: 0.9</li>
121</ul><p class="description">Sleep efficiency is the coefficient of the sleep period spent asleep (total_sleep / bedtime_duration)</p>
122
123<h3 class="h3">Sleep.latency</h3>
124<ul class="list-wrapper">
125 <li class="list">Type: Int</li>
126 <li class="list">Unit: Seconds</li>
127 <li class="list">Example: 758</li>
128</ul><p class="description">Detected latency from bedtime_start to the beginning of the first five minutes of persistent sleep</p>
129
130<h3 class="h3">Sleep.temperature_delta</h3>
131<ul class="list-wrapper">
132 <li class="list">Type: Float</li>
133 <li class="list">Unit: Celcius</li>
134 <li class="list">Example: -0.1</li>
135</ul><p class="description">Skin temperature deviation from the long-term temperature average</p>
136
137<h3 class="h3">Sleep.average_hrv</h3>
138<ul class="list-wrapper">
139 <li class="list">Type: Int</li>
140 <li class="list">Unit: Milliseconds</li>
141 <li class="list">Example: 78</li>
142</ul><p class="description">The average HRV(Heart Rate Variability) calculated with rMSSD method</p>
143
144<h3 class="h3">Sleep.respiratory_rate</h3>
145<ul class="list-wrapper">
146 <li class="list">Type: Float</li>
147 <li class="list">Unit: Breaths per minute</li>
148 <li class="list">Example: 14</li>
149</ul><p class="description">Average respiratory rate</p>
150
151<h3 class="h3">Sleep.standardized_sleep_score</h3>
152<ul class="list-wrapper">
153 <li class="list">Type: Int</li>
154 <li class="list">Range: 0-100</li>
155 <li class="list">Example: 88</li>
156</ul><p class="description">Standardized sleep score</p>
157
158<h3 class="h3">Sleep.source_specific_sleep_score</h3>
159<ul class="list-wrapper">
160 <li class="list">Type: Int</li>
161 <li class="list">Range: 0-100</li>
162 <li class="list">Example: 88</li>
163</ul><p class="description">Specific sleep score by data provider</p>
164
165<h3 class="h3">Sleep.levels.date_time</h3>
166<ul class="list-wrapper">
167 <li class="list">Type: String</li>
168 <li class="list">Format: Date time, YYYY-MM-DDThh:mm:ss</li>
169 <li class="list">Example: 2021-05-01T01:52:13</li>
170</ul><p class="description">Date and time the user started in sleep level</p>
171
172<h3 class="h3">Sleep.levels.level</h3>
173<ul class="list-wrapper">
174 <li class="list">Type: String</li>
175 <li class="list">Values: deep | light | rem | awake</li>
176</ul><p class="description">The sleep level the user entered</p>
177
178<h3 class="h3">Sleep.levels.seconds</h3>
179<ul class="list-wrapper">
180 <li class="list">Type: Int</li>
181 <li class="list">Unit: Seconds</li>
182 <li class="list">Example: 320</li>
183</ul><p class="description">The length of time the user was in the sleep level</p>
184