Make your product
work with UP.

Object Types

An overview of the different objects returned by API calls.

Band Events

Field Name Type Description Permissions
date int Date of the event sleep_read
move_read
action string Type of band event. Can be enter_sleep_mode, exit_sleep_mode, enter_stopwatch_mode, exit_stopwatch_mode. Sleep mode logs a sleep event, stopwatch mode logs a workout.

sleep_read

move_read
tz string Time zone, Olsen format

sleep_read

move_read

time_created int Epoch timestamp when band event was generated. sleep_read
move_read

Body

Field Name Type Description Permissions
xid string Unique ID for this event that can be used to retrieve data for this specific event
weight_read
title
string Title of this body event
weight_read
type
string
Type of event, in this case a body event. It will be the string "body"
weight_read
time_created
int
Epoch timestamp when this body event was created
weight_read
time_updated int
Epoch timestamp when this body event was updated
weight_read
date
int
Date when this body event was created taking into account the user time zone, formatted as YYYYMMDD
weight_read
place_lat
float
Latitude of location where body event was logged
location_read
weight_read
place_lon
float
Longitude of location where body event was logged
location_read
weight_read
place_acc int
Accuracy of location where body event was logged, in meters
location_read
weight_read
place_name
string
Name of location where body event was logged
location_read
weight_read
image
URI
Link to the image of this body event (relative, add prefix https://jawbone.com)
weight_read
note
string
Note on this body event
weight_read
lean_mass
int
Lean mass percentage
weight_read
weight
int
Body weight in kilograms
weight_read
body_fat
int
Body fat percentage
weight_read
bmi
int
Body mass index
weight_read
tz int
Time zone when this body event was logged, Olson format
weight_read

Custom (Generic)

Field Name Type Description Permissions
xid string Unique ID for this event that can be used to retrieve data for this specific event
generic_event_read
title
string
Title of this custom event
generic_event_read
type
string
Type of event, in this case a custom event. It will be the string 'generic'.
generic_event_read
time_created
int
Epoch timestamp when this custom event was created
generic_event_read
time_updated
int
Epoch timestamp when this custom event was updated
generic_event_read
date
int
Date when this custom event was created taking into account the user time zone, formatted as YYYYMMDD
generic_event_read
place_lat
float
Latitude of location where custom event was logged
location_read
generic_event_read
place_lon
float
Longitude of location where custom event was logged
location_read
generic_event_read
place_acc int
Accuracy of location where custom event was logged, in meters
location_read
generic_event_read
place_name
string
Name of location where custom event was logged
location_read
generic_event_read
image
URI
Link to the image of this custom event (relative, add prefix https://jawbone.com)
generic_event_read
attributes
JSON list
JSON list of attributes submitted by 3rd party partner
generic_event_read
tz int
Time zone when this custom event was logged, Olson format
generic_event_read

Goals

Field Name Type Description Permissions
body_weight int Weight goal in kilograms. weight_read
body_weight_intent int User's weight intent. 0=lose, 1=maintain, 2=gain weight_read
move_steps int Steps goal move_read
sleep_total int Sleep goal in seconds sleep_read
intake_calories_remaining float Calories available to be consumed today in order to achieve user weight goal. meal_read
move_steps_remaining int Steps remaining today in order to achieve user's step goal. move_read
sleep_seconds_remaining int Number of seconds of sleep remaining today in order to achieve user's sleep goal. sleep_read

Meal

Field Name Type Description Permissions
xid string The application's unique identifier for this meal meal_read
title string Title of this meal meal_read
note string Note on this meal meal_read
type string Type of event, in this case a meal. It will be the string "meal". meal_read
sub_type
int Meal type. 1=Breakfast, 2=Lunch, 3=Dinner meal_read
time_created int Epoch timestamp when this meal was created meal_read
time_updated int Epoch timestamp when this meal was last updated meal_read
time_completed int Epoch timestamp when this meal was completed meal_read
date int Date when this meal was created taking into account user time zone, formatted as YYYYMMDD meal_read
place_lat float Latitude of location where meal was logged location_read
meal_read
place_lon float Longitude of location where meal was logged location_read
meal_read
place_acc int Accuracy of location where meal was logged, in meters
location_read
meal_read
place_name string Name of location where meal was logged. location_read
meal_read
num_drinks int Number of drinks in this meal meal_read
num_foods int Number of foods in this meal. meal_read
fiber float Fiber content (in grams) meal_read
polyunsaturated_fat float Polyunsaturated fat content (in grams) meal_read
potassium float Potassium content (in milligrams) meal_read
fat float Fat content (in grams) meal_read
carbohydrate float Carbohydrate content (in grams) meal_read
saturated_fat float Saturated fat content (in grams) meal_read
protein float Protein content (in grams) meal_read
monounsaturated_fat float Monounsaturated fat content (in grams) meal_read
sodium float Sodium content (in milligrams) meal_read
vitamin_c float Percentage of daily recommended vitamin C (based on a 2000 calorie diet) meal_read
vitamin_a float Percentage of daily recommended vitamin A (based on a 2000 calorie diet) meal_read
calories int Calories for this meal meal_read
unsaturated_fat float Unsaturated fat content (in grams) meal_read
sugar float Sugar content (in grams) meal_read
calcium float Percentage of daily recommended calcium (based on a 2000 calorie diet) meal_read
iron float Percentage of daily recommended iron (based on a 2000 calorie diet) meal_read
cholesterol float Cholesterol content (in milligrams) meal_read
tz string Time zone when this meal was consumed, Olson format meal_read

Mood

Field Name Type Description Permissions
xid String The application's unique identifier for this mood. mood_read
title string Title of this mood mood_read
type string Type of event, in this case a meal. It will be the string "mood". mood_read
sub_type int Mood type (0 = unknown, 1 = ultra_energized, 2 = energized, 3 = good, 4 = just_ok, 5 = unhappy, 6 = miserable, 7 = ultra_miserable, 8 = feeling_fine) mood_read
time_created int Epoch timestamp when this mood was created mood_read
time_updated int Epoch timestamp when this mood was last updated mood_read
date int Date when this mood was created taking into account user time zone, formatted as YYYYMMDD mood_read
place_lat float Latitude of location where mood was logged location_read
mood_read
place_lon float Longitude of location where mood was logged location_read
mood_read
place_acc int Accuracy of location where mood was logged, in meters
location_read
mood_read
place_name string Name of location where mood was logged. location_read
mood_read
tz string Time zone when this mood was consumed, Olson format mood_read

Moves

Field Name Type Description Permissions
xid string Unique ID for this event that can be used to retrieve data for this specific event
move_read
title
string
Title of this move
move_read
type string
Type of event, in this case a move. It will be the string "move".
move_read
time_created
int
Epoch timestamp when this move was created
move_read
time_updated
int
Epoch timestamp when this move was last updated
move_read
time_completed
int
Epoch timestamp when this move was completed move_read
date int Date when this move was created taking into account user time zone, formatted as YYYYMMDD
move_read
snapshot_image URI
Link to the image of this move event (relative, add prefix https://jawbone.com)
move_read
distance
int
Distance travelled, in meters
move_read
km
int
Distance travelled, in kilometers
move_read
steps int
Number of steps taken
move_read
active_time
int
Total active time for move, in seconds
move_read
longest_active
int
Longest consecutive active period, in seconds
move_read
inactive_time
int
Total inactive time for move, in seconds
move_read
longest_idle
int
Longest consecutive inactive period, in seconds
move_read
calories
int
Total calories burned. This is computed by this formula: wo_calories+bg_calories+bmr_day / 86400 * active_time
move_read
bmr_day
int
Estimated basal metabolic rate for entire day, in calories.
move_read
bmr
int
Estimated basal metabolic rate at time of last sync. For previous days should approximately equal bmr_day
move_read
bg_calories
int
Calories directly from UP band activity outside the context of a workout.
move_read
wo_calories
int
Calories burned from workouts.
move_read
wo_time
int
Total time spent in workouts, in seconds
move_read
wo_active_time
int
Actual active time during workout, in seconds
move_read
wo_count
int
Number of workouts logged during this move
move_read
wo_longest
int
Longest workout period, in seconds
move_read
tz string Most active time zone, Olson format
move_read
tzs [epoch timestamp, timezone]
Move can have more than one timezone associated with it if the user has crossed timezone in the given day. Epoch timestamp for the period starting in that time zone, and the time zone string.
move_read
hourly_totals JSON Data broken out by hour (values as above). move_read

Settings

Field Name Type Description Permissions
XID int Unique ID for user basic_read
metric int User setting for units. 0 = Imperial (American) system, 1 = Metric system basic_read
share_sleep boolean Whether the user shares sleep events with their teammates. sleep_read
share_mood boolean Whether the user shares mood events with their teammates. mood_read
share_body boolean Whether the user shares body events with their teammates. weight_read
share_eat boolean Whether the user shares meal events with their teammates. meal_read
share_move boolean Whether the user shares move events with their teammates. move_read

Sleep

Field Name Type Description Permissions
xid String The application's unique identifier for this sleep. sleep_read
title String Title of the sleep. sleep_read
sub_type int Type of sleep. 0=normal, 1=power nap, 2=nap. sleep_read
type String Type of event, in this case a sleep. It will be the string "sleep". sleep_read
time_created int Epoch timestamp when this sleep was created. sleep_read
time_completed int Epoch timestamp when this sleep was completed. sleep_read
date int Date for the sleep taking the user's time zone into account. Format is YYYYMMDD. sleep_read
place_lat float Latitude of location where meal was logged location_read
sleep_read
place_lon float Longitude of location where meal was logged location_read
sleep_read
place_acc int Accuracy of location where meal was logged, in meters
location_read
sleep_read
place_name string Name of location where meal was logged. location_read
sleep_read
snapshot_image URI Link to the image of this sleep event (relative, add prefix https://jawbone.com)
sleep_read
smart_alarm_fire int Epoch timestamp when smart alarm was fired. sleep_read
awake_time int Epoch timestamp when the user awoke. sleep_read
asleep_time int Epoch timestamp when the user fell asleep. sleep_read
awakenings int Number of times the user awoke during sleep period. sleep_read
rem int REM sleep duration in seconds. NOTE: not in use at this time. sleep_read
light int Total light sleep time, in seconds. sleep_read
sound int Total sound sleep time, in seconds. sleep_read
awake int Total time spent awake, in seconds. sleep_read
duration int Total time for this sleep event, in seconds. sleep_read
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). sleep_read
tz string Time zone when this sleep was logged, Olson format. sleep_read

Timezone

Field Name Type Description Permissions
time int timestamp when this timezone went into effect basic_read
tz string timezone information basic_read
date int Date in format YYYYMMDD, calculated based on "time" and "tz" basic_read

Trends

Each trend entry is a tuple: (date, trend_info), where date is in the format YYYYMMDD and trend_info has the following data:

Field Name Type Description Permissions
earliest
int
First date there is data for this user, in YYYYMMDD format
extended_read
weight
int
Weight of the user, in kilograms
weight_read
gender
boolean
Gender of user. True = female, False = Male. NOTE: There is a current bug in the API where this value is returning as NULL. Workaround is to use user call at top above to retrieve gender
extended_read
age
int
Age of user
extended_read
bmr
int
Basal metabolic rate per day
move_read
body_fat
int
Body fat percentage of user
weight_read
m_steps
int
Number of steps taken
move_read
m_calories
int
Number of calories burned directly from activity
move_read
m_total_calories
int
Total number of calories burned including bmr
move_read
m_active_time
int
Total active time
move_read
m_workout_time
int
Workout time
move_read
m_distance
int
Total distance travelled, in meters
move_read
e_calories
int
Calories consumed
meal_read
e_carbs
int
Total carbs consumed (in grams)
meal_read
e_cholesterol
int
Total cholesterol consumed (in milligrams)
meal_read
e_protein
int
Total protein consumed (in grams)
meal_read
e_calcium
int
Percentage of daily recommended calcium (based on a 2000 calorie diet)
meal_read
e_unsat_fat
int
Total unsaturated fat (in grams)
meal_read
e_sat_fat
int
Total saturated fat (in grams)
meal_read
e_sodium
int
Total amount of sodium (in milligrams)
meal_read
e_sugar
int
Total amount of sugar (in grams)
meal_read
e_fiber
int
Total amount of fiber (in grams)
meal_read
s_asleep_time
int
Time user fell asleep. Seconds to/from midnight. If negative, subtract from midnight. If positive, add to midnight
sleep_read
s_awake
int First time user woke up. Seconds to/from midnight. If negative, subtract from midnight. If positive, add to midnight
sleep_read
s_awake_time
int
Final time user woke up (end of sleep period). Seconds to/from midnight. If negative, subtract from midnight. If positive, add to midnight
sleep_read
s_awakenings
int
Number of times user awoke during the sleep period
sleep_read
s_light
int
Number of seconds of light sleep during the sleep period sleep_read
s_sound
int
Number of seconds of sound sleep during the sleep period
sleep_read
s_duration
int
Total number of seconds of sleep during the sleep period
sleep_read
s_quality
int
Sleep quality percentage (based on a proprietary formula of light and deep sleep to awake time)
sleep_read
n_bedtime
int
Time user entered sleep mode for nap. Seconds to/from midnight. If negative, subtract from midnight. If positive, add to midnight
sleep_read
n_asleep_time
int
Time user fell asleep for nap. Seconds to/from midnight. If negative, subtract from midnight. If positive, add to midnight
sleep_read
n_awake
int
First time user woke up from nap. Seconds to/from midnight. If negative, subtract from midnight. If positive, add to midnight
sleep_read
n_awake_time
int
Final time user woke up (end of nap). Seconds to/from midnight. If negative, subtract from midnight. If positive, add to midnight
sleep_read
n_awakenings
int
Number of times user awoke during the nap
sleep_read
n_light
int
Number of seconds of light sleep during the nap
sleep_read
n_sound int
Number of seconds of sound sleep during the nap
sleep_read
n_duration
int
Total number of seconds of sleep during the nap
sleep_read
n_quality
int
Total number of seconds of sleep during the nap
sleep_read

User

Field Name Type Description Permissions
xid string Unique ID for this user (matches user_xid in Meta section)
basic_read
first string First name of user
basic_read
last string Last name of user basic_read
image URI Link to the profile image of this user (relative, add prefix https://jawbone.com)
basic_read
weight float Weight of the user, in kilograms extended_read
height float Height of the user, in meters
extended_read

Workout

Field Name Type Description Permissions
xid string Unique ID for this event that can be used to retrieve data for this specific event
workout_read
title string
Title of this workout
workout_read
type
string
Type of event, in this case a workout
workout_read
sub_type
int
Workout type, see Type table below
workout_read
time_created int
Epoch timestamp when this workout was created
workout_read
time_updated
int
Epoch timestamp when this workout was updated
workout_read
time_completed
int
Epoch timestamp when this workout was completed
workout_read
date int Date when this workout was created, formatted as YYYYMMDD workout_read
place_lat
float
Latitude of location where workout was logged
location_read
workout_read
place_lon
float
Longitude of location where workout was logged
location_read
workout_read
place_acc
int
Accuracy of location where workout was logged, in meters
location_read
workout_read
place_name
string Name of location where workout was logged
location_read
workout_read
route
URI
Link to the image of route taken for workout (relative, add prefix https://jawbone.com)
workout_read
image
URI
Link to the image of this workout (relative, add prefix https://jawbone.com)
workout_read
snapshot_image
URI
Link to the image of this workout's intensity (relative, add prefix https://jawbone.com)
workout_read
steps
int
Number of steps during this workout. Note steps will only be provided if the user was wearing the physical UP band during workout
workout_read
time
int
Total time for this workout, in seconds
workout_read
bg_active_time
int
Total time in movement as logged by the UP band. Note bg_active_time will only be provided if the user was wearing the physical UP band during workout
workout_read
meters
int
Total distance travelled, in meters
workout_read
km
int
Total distance travelled, in meters
workout_read
intensity
int
Intensity of the workout as selected by the user or 3rd party app. 1 = easy, 2 = moderate, 3 = intermediate, 4 = difficult, 5 = hard
workout_read
calories
int
Total calories burned during workout
workout_read
bmr int
Basal metabolic rate during workout
workout_read
bg_calories
int
Calories burned as logged by the UP band. Note bg_calories will only be provided if the user was wearing the physical UP band during workout
workout_read
tz int
Time zone when this workout was logged, Olson format
workout_read