-
Get the user's sleep list
- Returns the list of sleeps of the current user. This list can be paginated by date or timestamp.
-
| URI | Method | Response Type | Returns |
| /nudge/api/users/@me/sleeps | GET | application/json | Collection>Sleep |
| Parameter | Type | Description |
| date | int | Date, formatted as YYYYMMDD. If omitted, returns the information for today. |
| page_token | int | Timestamp used to paginate the list of sleeps. The Developer must use the "next" link provided in the "links" section. |
| start_time | int | To be used along with end_time. Epoch timestamp that denotes the start of the time range queried for events. |
| end_time | int | To be used with start_time. Epoch timestamp that denotes the end of the time range queried for events. |
| updated_after | int | Epoch timestamp to list events that are updated later than the timestamp. To be used with start_time to list events that were completed after said start_time. |
Example:
GET https://jawbone.com/nudge/api/v.1.0/users/@me/sleeps?start_time=1383289200 HTTP/1.1
Host: jawbone.com
Will return:
HTTP 200 OK
{
“meta”:
{
“user_xid”: “6xl39CsoVp2KirfHwVq_Fx”,
“message”: “OK”,
“code”: 200
"time": 1386122022
},
“data”:
{
"items":
[{
"xid": "40F7_htRRnQ6_IpPSk0pow",
"title": "for 6h 46m",
"sub_type": 0,
"time_created": 1384963500,
"time_completed": 1385099220,
"date": 20131121,
"place_lat": "37.451572",
"place_lon": "-122.184435",
"place_acc": 10,
"place_name": "My House",
"snapshot_image": "/nudge/image/e/1385066264/40F7_htRRnQ6_IpPSk0pow/grEGutn_3mE.png"
"details":
{
"smart_alarm_fire": 1385049600,
"awake_time": 1385049573,
"asleep_time": 1385023259,
"awakenings": 2
"rem": 0
"light": 8340,
"deep": 16044,
"awake": 3516,
"duration": 27900,
"quality": 75
"tz": "America/Los_Angeles"
}
},
{
... more items ....
}],
"links":
{
"next": "/nudge/api/v.1.0/users/6xl39CsoVp2KirfHwVq_Fx/sleeps?page_token=1384390680"
},
“size”: 10
}
}
| Data Value | Type | Description |
| xid | string | Unique ID for this event. Can be used to retrieve data for this specific event, see below. |
| title | string | Title of this sleep |
| sub_type | int | Type of sleep. 0=normal, 1=power_nap, 2=nap |
| type | string | Type of event, in this case a sleep. |
| time_created | int | Epoch timestamp when this sleep was created. |
| time_completed | int | Epoch timestamp when this sleep was completed. |
| date | int | Date when this sleep was created factoring in user timezone, formatted as YYYYMMDD. |
| place_lat | float | Latitude of location where sleep was logged. |
| place_lon | float | Longitude of location where sleep was logged. |
| place_acc | int | Accuracy of location where sleep was logged, in meters. |
| place_name | string | Name of location where sleep was logged. |
| snapshot_image | URI | Link to the image of this sleep event (relative, add prefix https://jawbone.com) |
| smart_alarm_fire | int | Epoch timestamp when smart alarm was fired. |
| awake_time | int | Epoch timestamp when the user awoke. |
| asleep_time | int | Epoch timestamp when the user fell asleep. |
| awakenings | int | Number of times the user awoke during sleep period. |
| rem | int | REM sleep duration in seconds. NOTE: not in use at this time. |
| light | int | Total light sleep time, in seconds. |
| deep | int | Total deep sleep time, in seconds. |
| awake | int | Total time spent awake, in seconds. |
| duration | int | Total time for this sleep event, in seconds. |
| quality | int | Sleep quality for the night. Based on a proprietary formula of light and deep sleep vs wake time. Note this is a different value than the percentage shown in the UP app (which is the percentage of sleep goal completed). |
| tz | string | Time zone when this sleep was logged, Olson format. |
| size | int | Number of items in this list. |
| next | URI | Link to next page of data (relative, add https://jawbone.com as prefix). |
-
Get the information about a specific sleep period
- Returns detailed information about the given sleep period denoted by xid.
-
| URI | Method | Response Type | Returns |
| /nudge/api/sleeps/{xid} | GET | application/json | Sleep |
Example:
GET https://jawbone.com/nudge/api/v.1.0/sleeps/BwiqMyhqs18M HTTP/1.1
Host: jawbone.com
Will return:
HTTP 200 OK
{
“meta”:
{
“user_xid”: “6xl39CsoVp2KirfHwVq_Fx”,
“message”: “OK”,
“code”: 200
"time": 1386122022
},
“data”:
{
"xid": "40F7_htRRnQ6_IpPSk0pow",
"title": "for 6h 46m",
"sub_type": 0,
"time_created": 1384963500,
"time_completed": 1385099220,
"date": 20131121,
"place_lat": "37.451572",
"place_lon": "-122.184435",
"place_acc": 10,
"place_name": "My House",
"snapshot_image": "/nudge/image/e/1385066264/40F7_htRRnQ6_IpPSk0pow/grEGutn_3mE.png"
"details":
{
"smart_alarm_fire": 1385049600,
"awake_time": 1385049573,
"asleep_time": 1385023259,
"awakenings": 2
"rem": 0
"light": 8340,
"deep": 16044,
"awake": 3516,
"duration": 27900,
"quality": 75
"tz": "America/Los_Angeles"
}
}
}
-
Get the user's sleep graphs
- Returns the image of the given sleep.
-
| URI | Method | Response Type | Returns |
| /nudge/api/sleeps/{xid}/image | GET | image/png | Binary image |
Example:
GET https://jawbone.com/nudge/api/v.1.0/sleeps/ABC123/image HTTP/1.1
Host: jawbone.com
Will return:
Binary contents of the image.
-
Get sleep phases
- A sleep period can be sub-divided into phases: awake, light and deep. This endpoint returns a time-series of the sleep phase during the period. Each entry is a tuple that contains a timestamp and the sleep phase (1=awake, 2=light, 3=deep). The timestamps are distributed based on when the type of sleep changes.
-
| URI | Method | Response Type | Returns |
| /nudge/api/sleeps/{xid}/snapshot | GET | application/json | Snapshot |
Example:
GET https://jawbone.com/nudge/api/v.1.0/sleeps/BwiqMyh8M/snapshot HTTP/1.1
Host: jawbone.com
Will return:
HTTP 200 OK
{
“meta”:
{
“user_xid”: “b9yCLa3f01yf”,
“message”: “OK”,
“code”: 200
"time": 1386714147
},
“data”:
[
[1312369860, 1],
[1312369920, 3],
[1312369980, 2],
...
]
}
-
Create sleep
- Creates a new sleep.
-
| URI | Method | Response Type | Returns |
| /nudge/api/users/@me/sleeps | POST | application/json | Sleep |
| Parameter | Type | Description |
| time_created | int | Start time of the sleep (seconds since the epoch) |
| time_completed | int | End time of the sleep (seconds since the epoch) |
| tz | string | Timezone where the sleep was created. |
Example:
POST https://jawbone.com/nudge/api/v.1.0/users/@me/sleeps HTTP/1.1
Host: jawbone.com
time_created=1386752401&time_completed=1386774001
Will return:
HTTP 201 Created
{
“meta”:
{
“user_xid”: “6xl39CsoVp2KirfHwVq_Fx”,
“message”: “OK”,
“code”: 200
"time": 1386795656
},
“data”:
{
"xid": "40F7_htRRnQ6_IpPSk0pow",
"title": "For 6h 0m",
"sub_type": 0,
"time_created": 1386752401,
"time_completed": 1386774001,
"date": 20130515,
"place_lat": null,
"place_lon": null,
"place_acc": "",
"place_name": "",
"snapshot_image": "/nudge/image/e/1385066264/40F7_htRRnQ6_IpPSk0pow/grEGutn_3mE.png"
"details":
{
"smart_alarm_fire": 0,
"awake_time": 1386774001,
"asleep_time": 1386752401,
"awakenings": 0,
"rem": 0
"light": 0,
"deep": 0,
"awake": 0,
"duration": 21600,
"quality": 0
"tz": "America/Los_Angeles"
}
}
}
