Overview

This is a complete python implementation of the Fitbit API.

It uses oAuth for authentication, it supports both us and si measurements

Quickstart

If you are only retrieving data that doesn’t require authorization, then you can use the unauthorized interface:

import fitbit
unauth_client = fitbit.Fitbit('<consumer_key>', '<consumer_secret>')
# certain methods do not require user keys
unauth_client.food_units()

Here is an example of authorizing with OAuth 2.0:

# You'll have to gather the tokens on your own, or use
# ./gather_keys_oauth2.py
authd_client = fitbit.Fitbit('<consumer_key>', '<consumer_secret>',
                             access_token='<access_token>', refresh_token='<refresh_token>')
authd_client.sleep()

Fitbit API

Some assumptions you should note. Anywhere it says user_id=None, it assumes the current user_id from the credentials given, and passes a - through the API. Anywhere it says date=None, it should accept either None or a date or datetime object (anything with proper strftime will do), or a string formatted as %Y-%m-%d.

class fitbit.Fitbit(client_id, client_secret, access_token=None, refresh_token=None, expires_at=None, refresh_cb=None, redirect_uri=None, system='en_US', **kwargs)[source]

Before using this class, create a Fitbit app here. There you will get the client id and secret needed to instantiate this class. When first authorizing a user, make sure to pass the redirect_uri keyword arg so fitbit will know where to return to when the authorization is complete. See gather_keys_oauth2.py for a reference implementation of the authorization process. You should save access_token, refresh_token, and expires_at from the returned token for each user you authorize.

When instantiating this class for use with an already authorized user, pass in the access_token, refresh_token, and expires_at keyword arguments. We also strongly recommend passing in a refresh_cb keyword argument, which should be a function taking one argument: a token dict. When that argument is present, we will automatically refresh the access token when needed and call this function so that you can save the updated token data. If you don’t save the updated information, then you could end up with invalid access and refresh tokens, and the only way to recover from that is to reauthorize the user.

body(date=None, user_id=None, data=None)

Get body data: https://dev.fitbit.com/docs/body/

activities(date=None, user_id=None, data=None)

Get body data: https://dev.fitbit.com/docs/activity/

foods_log(date=None, user_id=None, data=None)

Get food logs data: https://dev.fitbit.com/docs/food-logging/#get-food-logs

foods_log_water(date=None, user_id=None, data=None)

Get water logs data: https://dev.fitbit.com/docs/food-logging/#get-water-logs

sleep(date=None, user_id=None, data=None)

Get sleep data: https://dev.fitbit.com/docs/sleep/

heart(date=None, user_id=None, data=None)

Get heart rate data: https://dev.fitbit.com/docs/heart-rate/

bp(date=None, user_id=None, data=None)

Get blood pressure data: https://dev.fitbit.com/docs/heart-rate/

delete_body(log_id)

Delete a body log, given a log id

delete_activities(log_id)

Delete an activity log, given a log id

delete_foods_log(log_id)

Delete a food log, given a log id

delete_foods_log_water(log_id)

Delete a water log, given a log id

delete_sleep(log_id)

Delete a sleep log, given a log id

delete_heart(log_id)

Delete a heart log, given a log id

delete_bp(log_id)

Delete a blood pressure log, given a log id

recent_foods(user_id=None, qualifier='')

Get recently logged foods: https://dev.fitbit.com/docs/food-logging/#get-recent-foods

frequent_foods(user_id=None, qualifier='')

Get frequently logged foods: https://dev.fitbit.com/docs/food-logging/#get-frequent-foods

favorite_foods(user_id=None, qualifier='')

Get favorited foods: https://dev.fitbit.com/docs/food-logging/#get-favorite-foods

recent_activities(user_id=None, qualifier='')

Get recently logged activities: https://dev.fitbit.com/docs/activity/#get-recent-activity-types

frequent_activities(user_id=None, qualifier='')

Get frequently logged activities: https://dev.fitbit.com/docs/activity/#get-frequent-activities

favorite_activities(user_id=None, qualifier='')

Get favorited foods: https://dev.fitbit.com/docs/activity/#get-favorite-activities

accept_invite(other_user_id)[source]

Convenience method for respond_to_invite

activities_daily_goal(calories_out=None, active_minutes=None, floors=None, distance=None, steps=None)[source]

Implements the following APIs for period equal to daily

https://dev.fitbit.com/docs/activity/#get-activity-goals https://dev.fitbit.com/docs/activity/#update-activity-goals

Pass no arguments to get the daily activities goal. Pass any one of the optional arguments to set that component of the daily activities goal.

Arguments: * calories_out – New goal value; in an integer format * active_minutes – New goal value; in an integer format * floors – New goal value; in an integer format * distance – New goal value; in the format X.XX or integer * steps – New goal value; in an integer format

activities_list()[source]

https://dev.fitbit.com/docs/activity/#browse-activity-types

activities_weekly_goal(distance=None, floors=None, steps=None)[source]

Implements the following APIs for period equal to weekly

https://dev.fitbit.com/docs/activity/#get-activity-goals https://dev.fitbit.com/docs/activity/#update-activity-goals

Pass no arguments to get the weekly activities goal. Pass any one of the optional arguments to set that component of the weekly activities goal.

Arguments: * distance – New goal value; in the format X.XX or integer * floors – New goal value; in an integer format * steps – New goal value; in an integer format

activity_detail(activity_id)[source]

https://dev.fitbit.com/docs/activity/#get-activity-type

activity_stats(user_id=None, qualifier='')[source]

This implements the following methods:

recent_activities(user_id=None, qualifier='')
favorite_activities(user_id=None, qualifier='')
frequent_activities(user_id=None, qualifier='')
add_alarm(device_id, alarm_time, week_days, recurring=False, enabled=True, label=None, snooze_length=None, snooze_count=None, vibe='DEFAULT')[source]

https://dev.fitbit.com/docs/devices/#add-alarm alarm_time should be a timezone aware datetime object.

add_favorite_activity(activity_id)[source]

https://dev.fitbit.com/docs/activity/#add-favorite-activity

add_favorite_food(food_id)[source]

https://dev.fitbit.com/docs/food-logging/#add-favorite-food

body_fat_goal(fat=None)[source]

Implements the following APIs

Pass no arguments to get the body fat goal. Pass a fat argument to update the body fat goal.

Arguments: * fat – Target body fat in %; in the format X.XX

body_weight_goal(start_date=None, start_weight=None, weight=None)[source]

Implements the following APIs

Pass no arguments to get the body weight goal. Pass start_date, start_weight and optionally weight to set the weight goal. weight is required if it hasn’t been set yet.

Arguments: * start_date – Weight goal start date; in the format yyyy-MM-dd * start_weight – Weight goal start weight; in the format X.XX * weight – Weight goal target weight; in the format X.XX

create_food(data)[source]

https://dev.fitbit.com/docs/food-logging/#create-food

delete_alarm(device_id, alarm_id)[source]

https://dev.fitbit.com/docs/devices/#delete-alarm

delete_favorite_activity(activity_id)[source]

https://dev.fitbit.com/docs/activity/#delete-favorite-activity

delete_favorite_food(food_id)[source]

https://dev.fitbit.com/docs/food-logging/#delete-favorite-food

food_detail(food_id)[source]

https://dev.fitbit.com/docs/food-logging/#get-food

food_goal(calories=None, intensity=None, personalized=None)[source]

Implements the following APIs

https://dev.fitbit.com/docs/food-logging/#get-food-goals https://dev.fitbit.com/docs/food-logging/#update-food-goal

Pass no arguments to get the food goal. Pass at least calories or intensity and optionally personalized to update the food goal.

Arguments: * calories – Manual Calorie Consumption Goal; calories, integer; * intensity – Food Plan intensity; (MAINTENANCE, EASIER, MEDIUM, KINDAHARD, HARDER); * personalized – Food Plan type; True or False

food_units()[source]

https://dev.fitbit.com/docs/food-logging/#get-food-units

get_alarms(device_id)[source]

https://dev.fitbit.com/docs/devices/#get-alarms

get_badges(user_id=None)[source]

https://dev.fitbit.com/docs/friends/#badges

get_bodyfat(base_date=None, user_id=None, period=None, end_date=None)[source]

https://dev.fitbit.com/docs/body/#get-body-fat-logs base_date should be a datetime.date object (defaults to today), period can be ‘1d’, ‘7d’, ‘30d’, ‘1w’, ‘1m’, ‘3m’, ‘6m’, ‘1y’, ‘max’ or None end_date should be a datetime.date object, or None.

You can specify period or end_date, or neither, but not both.

get_bodyweight(base_date=None, user_id=None, period=None, end_date=None)[source]

https://dev.fitbit.com/docs/body/#get-weight-logs base_date should be a datetime.date object (defaults to today), period can be ‘1d’, ‘7d’, ‘30d’, ‘1w’, ‘1m’, ‘3m’, ‘6m’, ‘1y’, ‘max’ or None end_date should be a datetime.date object, or None.

You can specify period or end_date, or neither, but not both.

get_devices()[source]

https://dev.fitbit.com/docs/devices/#get-devices

get_friends(user_id=None)[source]

https://dev.fitbit.com/docs/friends/#get-friends

get_friends_leaderboard(period)[source]

https://dev.fitbit.com/docs/friends/#get-friends-leaderboard

get_meals()[source]

https://dev.fitbit.com/docs/food-logging/#get-meals

get_sleep(date)[source]

https://dev.fitbit.com/docs/sleep/#get-sleep-logs date should be a datetime.date object.

intraday_time_series(resource, base_date='today', detail_level='1min', start_time=None, end_time=None)[source]

The intraday time series extends the functionality of the regular time series, but returning data at a more granular level for a single day, defaulting to 1 minute intervals. To access this feature, one must fill out the Private Support form here (see https://dev.fitbit.com/docs/help/). For details on the resources available and more information on how to get access, see:

https://dev.fitbit.com/docs/activity/#get-activity-intraday-time-series

invite_friend(data)[source]

https://dev.fitbit.com/docs/friends/#invite-friend

invite_friend_by_email(email)[source]

Convenience Method for https://dev.fitbit.com/docs/friends/#invite-friend

invite_friend_by_userid(user_id)[source]

Convenience Method for https://dev.fitbit.com/docs/friends/#invite-friend

list_subscriptions(collection='')[source]

https://dev.fitbit.com/docs/subscriptions/#getting-a-list-of-subscriptions

log_activity(data)[source]

https://dev.fitbit.com/docs/activity/#log-activity

log_sleep(start_time, duration)[source]

https://dev.fitbit.com/docs/sleep/#log-sleep start time should be a datetime object. We will be using the year, month, day, hour, and minute.

reject_invite(other_user_id)[source]

Convenience method for respond_to_invite

respond_to_invite(other_user_id, accept=True)[source]

https://dev.fitbit.com/docs/friends/#respond-to-friend-invitation

search_foods(query)[source]

https://dev.fitbit.com/docs/food-logging/#search-foods

subscription(subscription_id, subscriber_id, collection=None, method='POST')[source]

https://dev.fitbit.com/docs/subscriptions/

time_series(resource, user_id=None, base_date='today', period=None, end_date=None)[source]

The time series is a LOT of methods, (documented at urls below) so they don’t get their own method. They all follow the same patterns, and return similar formats.

Taking liberty, this assumes a base_date of today, the current user, and a 1d period.

https://dev.fitbit.com/docs/activity/#activity-time-series https://dev.fitbit.com/docs/body/#body-time-series https://dev.fitbit.com/docs/food-logging/#food-or-water-time-series https://dev.fitbit.com/docs/heart-rate/#heart-rate-time-series https://dev.fitbit.com/docs/sleep/#sleep-time-series

update_alarm(device_id, alarm_id, alarm_time, week_days, recurring=False, enabled=True, label=None, snooze_length=None, snooze_count=None, vibe='DEFAULT')[source]

https://dev.fitbit.com/docs/devices/#update-alarm alarm_time should be a timezone aware datetime object.

user_profile_get(user_id=None)[source]

Get a user profile. You can get other user’s profile information by passing user_id, or you can get the current user’s by not passing a user_id

https://dev.fitbit.com/docs/user/

user_profile_update(data)[source]

Set a user profile. You can set your user profile information by passing a dictionary of attributes that will be updated.

https://dev.fitbit.com/docs/user/#update-profile

water_goal(target=None)[source]

Implements the following APIs

https://dev.fitbit.com/docs/food-logging/#get-water-goal https://dev.fitbit.com/docs/food-logging/#update-water-goal

Pass no arguments to get the water goal. Pass target to update it.

Arguments: * target – Target water goal in the format X.X, will be set in unit based on locale

Indices and tables