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, system='en_US', **kwargs)

_COLLECTION_RESOURCE(resource, date=None, user_id=None, data=None)

Retrieving and logging of each type of collection data.

Arguments:

resource, defined automatically via curry [date] defaults to today [user_id] defaults to current logged in user [data] optional, include for creating a record, exclude for access

This implements the following methods:

body(date=None, user_id=None, data=None)
activities(date=None, user_id=None, data=None)
foods_log(date=None, user_id=None, data=None)
foods_log_water(date=None, user_id=None, data=None)
sleep(date=None, user_id=None, data=None)
heart(date=None, user_id=None, data=None)
bp(date=None, user_id=None, data=None)

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

_DELETE_COLLECTION_RESOURCE(resource, log_id)

deleting each type of collection data

Arguments:

resource, defined automatically via curry log_id, required, log entry to delete

This builds the following methods:

delete_body(log_id)
delete_activities(log_id)
delete_foods_log(log_id)
delete_foods_log_water(log_id)
delete_sleep(log_id)
delete_heart(log_id)
delete_bp(log_id)

_food_stats(user_id=None, qualifier='')

This builds the convenience methods on initialization:

recent_foods(user_id=None, qualifier='')
favorite_foods(user_id=None, qualifier='')
frequent_foods(user_id=None, qualifier='')

• https://dev.fitbit.com/docs/food-logging/#get-favorite-foods
• https://dev.fitbit.com/docs/food-logging/#get-frequent-foods
• https://dev.fitbit.com/docs/food-logging/#get-recent-foods

_resource_goal(resource, data={}, period=None)

Handles GETting and POSTing resource goals of all types

accept_invite(other_user_id)

Convenience method for respond_to_invite

activities_daily_goal(calories_out=None, active_minutes=None, floors=None, distance=None, steps=None)

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()

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

activities_weekly_goal(distance=None, floors=None, steps=None)

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)

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

activity_stats(user_id=None, qualifier='')

• https://dev.fitbit.com/docs/activity/#activity-types
• https://dev.fitbit.com/docs/activity/#get-favorite-activities
• https://dev.fitbit.com/docs/activity/#get-recent-activity-types
• https://dev.fitbit.com/docs/activity/#get-frequent-activities

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')

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

add_favorite_activity(activity_id)

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

add_favorite_food(food_id)

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

body_fat_goal(fat=None)

Implements the following APIs

• https://dev.fitbit.com/docs/body/#get-body-goals
• https://dev.fitbit.com/docs/body/#update-body-fat-goal

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)

Implements the following APIs

• https://dev.fitbit.com/docs/body/#get-body-goals
• https://dev.fitbit.com/docs/body/#update-weight-goal

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)

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

delete_alarm(device_id, alarm_id)

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

delete_favorite_activity(activity_id)

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

delete_favorite_food(food_id)

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

food_detail(food_id)

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

food_goal(calories=None, intensity=None, personalized=None)

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()

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

get_alarms(device_id)

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

get_badges(user_id=None)

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

get_bodyfat(base_date=None, user_id=None, period=None, end_date=None)

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)

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()

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

get_friends(user_id=None)

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

get_friends_leaderboard(period)

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

get_meals()

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

get_sleep(date)

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)

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)

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

invite_friend_by_email(email)

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

invite_friend_by_userid(user_id)

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

list_subscriptions(collection='')

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

log_activity(data)

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

log_sleep(start_time, duration)

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)

Convenience method for respond_to_invite

respond_to_invite(other_user_id, accept=True)

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

search_foods(query)

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

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

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

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

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')

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

user_profile_get(user_id=None)

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)

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)

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

• Index
• Module Index
• Search Page