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
, andexpires_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
, andexpires_at
keyword arguments. We also strongly recommend passing in arefresh_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
-
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_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_stats
(user_id=None, qualifier='')[source]¶ - 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')[source]¶ https://dev.fitbit.com/docs/devices/#add-alarm alarm_time should be a timezone aware datetime object.
-
body_fat_goal
(fat=None)[source]¶ 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)[source]¶ 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 optionallyweight
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
-
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_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
orintensity
and optionallypersonalized
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
orFalse
-
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_friends_leaderboard
(period)[source]¶ https://dev.fitbit.com/docs/friends/#get-friends-leaderboard
-
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_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_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.
-
respond_to_invite
(other_user_id, accept=True)[source]¶ https://dev.fitbit.com/docs/friends/#respond-to-friend-invitation
-
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
-
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.
-
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
-