Collect Your Own Fitbit Data with Python

So you’ve got your Fitbit over the Christmas break and you’ve got some New Years Resolutions. You go online and see the graphs on your dashboard but you’re still not pleased. You want more data, more graphs, and more information. Well say no more, because I’m going to teach you how to collect your own Fitbit data using nothing but a little Python code. With this tutorial, you can get your elusive minute by minute data (also known as intraday data), which is not readily available when you first get your Fitbit.

Step 1: Set up your account and create the app

The first thing you’ll need to do is create a Fitbit account. Once you’ve done that, you can go to Under “Manage”, go to “Register An App”. This will lead you to a page with a form that looks like:

Application Registration

For the application website and organization website, name it anything starting with “http://” or “https://”. Secondly, make sure the OAuth 2.0 Application Type is “Personal” as this is key to allowing us to download our intraday data. Lastly, make sure the Callback URL is “” in order to get our Fitbit API to connect properly. After that, click on the agreement box and submit.

NOTE: depending on the app, we may need an additional step to fill out a form in order to gain permission to our intraday data at this link. Fitbit is supportive of personal projects and any other non profit research, so these should already be callable, but commercial apps might take longer to be approved.

After that, you’ll be redirected to a page looking like this:

The parts we will need from this page are the OAuth 2.0 Client ID and the Client Secret.

Step 2: The API

Once Step 1 is completed, our next step is to use a Fitbit unofficial API. Click the green button on the right side to download the repo and afterwards unzip the file. After that, open up the command line to change directories to the directory containing the unzipped files and run a quick ‘sudo pip install -r requirements/base.txt’ and ‘sudo pip install cherrypy’ . Then run ‘sudo python install’. After you create a new directory for your project, make sure to copy the ‘’ script to it.

Now we’re finally ready to start coding. First things first, we will need to import the necessary packages and bring in our Client_ID and Client_Secret from earlier to authorize ourselves.

import fitbit
import numpy as np
import gather_keys_oauth2 as Oauth2
import pandas as pd
import datetime
CLIENT_ID = '[See Page Above]'
CLIENT_SECRET = '[See Page Above]'

Using the ID and Secret, we can obtain the access and refresh tokens that authorize us to get our data.

server = Oauth2.OAuth2Server(CLIENT_ID, CLIENT_SECRET)
ACCESS_TOKEN = str(server.fitbit.client.session.token['access_token'])
REFRESH_TOKEN = str(server.fitbit.client.session.token['refresh_token'])
auth2_client = fitbit.Fitbit(CLIENT_ID, CLIENT_SECRET, oauth2=True, access_token=ACCESS_TOKEN, refresh_token=REFRESH_TOKEN)

Once you run this code, we will be taken to a page that requests data from your Fitbit profile, click ‘Allow’ and our script will be authorized.

We’re in! … but not so fast. We’ve authenticated ourselves but we still haven’t gotten our data. Before jumping in, I have one handy trick that will save a lot of manual typing: many of the calls require a date format of (YYYY-MM-DD) as a string format. So if you were to collect your data daily, we’ll have to change this string manually everyday. Instead, we can import the useful ‘datetime’ package and let it do the formatting for us instead.

yesterday = str(( - datetime.timedelta(days=1)).strftime("%Y-%m-%d"))
today = str("%Y-%m-%d"))

Step 3: Acquire the data

We can finally now call for our data.

fit_statsHR = auth2_client.intraday_time_series('activities/heart', base_date=yesterday, detail_level='1sec')

While this data looks readable to us, it’s not yet ready to be saved on our computer. The following bit of code reads the dictionary format and iterates through the dictionary values — saving the respective time and value values as lists before combining both into a pandas data frame.

time_list = []
val_list = []
for i in fit_statsHR['activities-heart-intraday']['dataset']:
heartdf = pd.DataFrame({'Heart Rate':val_list,'Time':time_list})

Now that is much better! Eventually, we are going to want to plot the data so it is necessary to convert the time column to a datetime object.

# Convert to DateTime
heartdf['Time'] = pd.to_datetime(heartdf['Time'], format='%H:%M:%S')

We’re now able to plot a simple time-series graph of a heartbeat over the day:

Now to finally save our data locally. Thinking ahead, we’ll be calling our data about once a data (1 file = 1 day), so we’ll want to have a good naming convention that prevents any future mixups or overriding data. My preferred format is to go with heartYYYMMDD.csv. The following code takes our heart data frame and saves them as a CSV in the /Downloads/Heart/ directory.

heartdf.to_csv('/Users/benjamingahtan/Downloads/Heart'+ \
yesterday+'.csv', \
columns=['Time','Heart Rate'], header=True, \
index = False)
Small army of heart rate files

But wait! There’s still more!

Reading the documentation, there’s plenty of other data we can still collect like:

Our sleep log data:

"""Sleep Summary on the night of ...."""
fit_statsSum = auth2_client.sleep(date='today')['sleep'][0]
ssummarydf = pd.DataFrame({'Date':fit_statsSum['dateOfSleep'],
'Minutes Asleep':fit_statsSum['minutesAsleep'],
'Minutes Awake':fit_statsSum['minutesAwake'],
'Restless Count':fit_statsSum['restlessCount'],
'Restless Duration':fit_statsSum['restlessDuration'],
'Time in Bed':fit_statsSum['timeInBed']
} ,index=[0])

And that’s all you need to get started on collecting all your Fitbit data! So play around some more, read the Python Fitbit documentation, get lost in it for a whole, find your way out, and see overall how nifty your heart data is.

Thanks for taking the time to read my tutorial and feel free to leave a comment and follow as I’ll be posting more tutorials on data mining and data science.


  1. Orcas Fitbit API Github
  2. Python-Fitbit documentation
  3. Official Fitbit API documentation
  4. Fitbit Intraday Access Form
  5. Pandas data frame documentation
One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.