Make your product
work with UP.

Sleeps

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

Delete a single sleep event.

Deletes an existing sleep event. The event must have been created by the partner for this call to succeed.
URI Method Response Type Returns
/nudge/api/sleeps/{xid} DELETE application/json Status

Example:

DELETE https://jawbone.com/nudge/api/v.1.0/sleeps/40F7_htRRnRaVaukZMRiBg HTTP/1.1
Host: jawbone.com
	

Will return:

HTTP 200 OK
{
   "meta": 
   {
      "user_xid": "6xl39CsoVp2KirfHwVq_Fx",
      "message": "OK",
      "code": 200,
      "time": 1351121565
    },
    "data": {}
}