Make your product
work with UP.

Sleeps

Get the user's sleep list

Returns the list of sleeps of the current user. This will include light, deep, and awake times during the sleep period if the user logged the sleep via the UP band.

This list can be paginated by date or timestamp.
URI Method Response Type Returns
/nudge/api/v.1.1/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.1/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,
            "tz": "America/Los_Angeles"
         }
      },
      {
      ... more items ....
      }],
      "links": 
      {
         "next": "/nudge/api/v.1.1/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.
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.
tz string Time zone when this event was generated. Whenever possible, Olson format (e.g., "America/Los Angeles") will be returned, otherwise the GMT offset (e.g., "GMT+0800") will be returned.
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/v.1.1/sleeps/{xid} GET application/json Sleep

Example:

GET https://jawbone.com/nudge/api/v.1.1/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,
         "tz": "America/Los_Angeles"  
      }
   }   
}
	

Get the user's sleep graphs

Returns the image of the given sleep.
URI Method Response Type Returns
/nudge/api/v.1.1/sleeps/{xid}/image GET image/png Binary image

Example:

GET https://jawbone.com/nudge/api/v.1.1/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 phases during the sleep event. Each entry contains a timestamp and the sleep phase. The timestamp indicates the start of the sleep phase.

NOTE: the v1.0 endpoint, /snapshot, has been deprecated but is still useable, but as it may not be supported in future versions we recommend updating to this endpoint. You can view the deprecated snapshot endpoint documentation here.

URI Method Response Type Returns
/nudge/api/v.1.1/sleeps/{xid}/ticks GET application/json Ticks

Example:

GET https://jawbone.com/nudge/api/v.1.1/sleeps/BwiqMyh8M/ticks
HTTP/1.1
Host: jawbone.com
	

Will return:

HTTP 200 OK
{
   “meta”:
   {
      “user_xid”: “b9yCLa3f01yf”,
      “message”: “OK”,
      “code”: 200
      "time": 1386714147
   },
   “data”:
   {
      "items": 
      [{
         "depth": 1, 
         "time": 1396163460
      }, {
         "depth": 2, 
         "time": 1396164300
      }, {
         "depth": 3,
         "time": 1396164600
      },{
      ... more phases ...
      }],
      "size": 30
   }
}
	
Data Value Type Description
depth int Sleep phase. 1=awake, 2=light, 3=deep
time int Epoch timestamp when this sleep phase started.

Create a sleep (with or without sleep phases)

Creates a new sleep. The new sleep will be added to the overall statistics for the user's sleep for the day. It is recommended you check to confirm that the user has not already logged sleep for the time period you are writing to avoid double counting.
URI Method Response Type Returns
/nudge/api/v.1.1/users/@me/sleeps POST application/json Sleep
Parameter Type Description
time_created int Start time of the sleep (epoch time)
time_completed int End time of the sleep (epoch time)
ticks (optional) list List of sleep phases in time/depth pairs (1=awake, 2=light, 3=deep) and start times (epoch time).

Note:
  • The difference in time between "time_created" and the time of the first tick will be captured and displayed as the time it took the user to fall asleep and will not be displayed in the UP app sleep graph -- it will be displayed in UP as "Fell asleep - [x] minutes" on the Sleep Details page
  • The difference in time between the time of the last tick and "time_completed" will be the duration of the last sleep phase
tz string Time zone when this event was generated. Whenever possible, Olson format (e.g., "America/Los Angeles") will be returned, otherwise the GMT offset (e.g., "GMT+0800") will be returned.
share boolean Set whether to share event on user's public feed. Will not override if user's privacy setting is set to not share.

Example:

POST https://jawbone.com/nudge/api/v.1.1/users/@me/sleeps?time_created=1432160600&time_completed=1432170000&ticks=[{"depth": 2, "time": 1432160800},{"depth": 1, "time": 1432161800},{"depth": 3, "time": 1432163800},{"depth": 2, "time": 1432165800},{"depth": 1, "time": 1432168800},{"depth": 2, "time": 1432169800}]
HTTP/1.1
Host: jawbone.com
	

Will return:

HTTP 201 Created
{
   “meta”:
   {
      “user_xid”: “uXZ3TI0TcU4PShNIS0_tmg”,
      “message”: “OK”,
      “code”: 200
      "time": 1433451371
   },
   “data”:
   {
      "xid": "TVEkOY_huUlkHA5Y7KCSirVyR8v_Ds9n",
      "title": "for 1h 43m",
      "sub_type": 2,
      "time_created": 1432160600,
      "time_completed": 1432170000,
      "date": 20150520,
      "place_lat": null,
      "place_lon": null,
      "place_acc": "",
      "place_name": "",
      "snapshot_image": "/nudge/image/e/1433455524/TVEkOY_huUnvmoC7tZTHXA1nDRKtanZJ/enj6lnNu11g.png"
      "details": 
      {
         "smart_alarm_fire": 0,
         "awake_time": 1432170000,
         "asleep_time": 1432160800,
         "awakenings": 0,
         "rem": 0
         "light": 4200,
         "deep": 2000,
         "awake": 3200,
         "duration": 9400,
         "tz": "America/Los_Angeles"  
      }
   }   
}
	

Representation in UP app:

At feed level:

At detail level:


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/v.1.1/sleeps/{xid} DELETE application/json Status

Example:

DELETE https://jawbone.com/nudge/api/v.1.1/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": {}
}