Richard J. Prinz

If you are using one of FitBit’s fitness tracker devices like the ‘One’ for some time you create a lot of data. When you synchronize your tracker all recorded data is sent to FitBit’s servers. The FitBit portal provides some features for graphically displaying and analyzing your data. It’s also possible to export it manually as CSV to process it further. But what if you want your data locally available without manual export to make own statistics. This is what the ‘fitbit_dumper’ is for.

Update: Since 2016 FitBit uses OAuth2. See this blog post for an update.

The ‘fitbit_dumper’ is a command line utility written in Javascript for node.js. It exports your FitBit data into a local sQlite database or a CSV file. The utility exports activity, weight and sleep data per day. Each type (activity, weight or sleep) requires one API call. According to FitBit API documentation only 150 API calls per hout are allowed. So it’s not possible to dump large amounts of data at once.

Install the dumper with

npm install -g fitbit_dumper

More infos at https://www.npmjs.com/package/fitbit_dumper and https://github.com/rprinz08/fitbit_dumper.

The dumper can be started with ‘fbdump’.

fbdump understands the following command line parameters:

USAGE: node fbdump [OPTION1] [OPTION2]... arg1 arg2...
The following options are supported:
  -s, --start <ARG1>    Start date YYYYMMDD
  -e, --end <ARG1>      End date YYYYMMDD
  -f, --force <ARG1>    Force download from FitBit, even if local data already exists
  -v, --verbose         Verbose debug output
  -q, --quiet           No output at all; overrules --verbose; assumes YES to all questions
  -i, --dbinit          (Re)Initialize database. DELETES ALL EXISTING LOCAL DATA!
  -d, --dbdump          Dump out database as CSV
  -r, --register        (Re)Register with FitBit

The dumper uses a time window specified by a start (-s, –start) and end date (-e, –end) to either query date from the FitBit API or to export data from the local sqlite database.

• If you omit both it uses a date range vom NOW (the current date) to 14 days back.
• If you omit a start date (-s, –start) a date 14 days to the past from the end date (-e, –end) will be asumed.
• If you omit an end date (-e, –end) a start date +14 days (or NOW) is used.

The dumper first checks if there is already data available in the database and will not query the FitBit API for these days. This behaviour can be overridden with the -f (–force) flag. This also querys existing days and overwrites them in the database.

The easiest way to use the dumper is using a unix crontab entry. I used my always running Raspberry PI to schedule a fitbit_dumper run every day at midnight without parameters. I normally dont sync my FitBit ONE every day. And by using the scheduled dumper I dont have to care about data exports for my own data analysis any longer. My Raspberry PI and the fitbit_dumper do this for me automatically.

Registering

Before using the dumper you have to register it under http://dev.fitbit.com/. Login and Register a new application named fitbit_dumper.
Follow the screenshot below.

Click on a picture for a larger view

      

After doing this copy the Client Consumer Key and the Client Consumer Secret and enter it in the corresponding fields in app.js.

// ----------------------------------------------------------------------------
// make configuration changes here
var FB_CONSUMER_KEY = '6d29ca149799037a6a263ba0bfc';
var FB_CONSUMER_SEC = '91f246119b4f0f9303363cb7';
var CSV_DELIMITER = ';';
var CSV_QUOTE = '"';
//var CSV_LOCALE = 'de-DE';
var CSV_LOCALE = undefined;
// ----------------------------------------------------------------------------
// dont change anything after this line

In this section you can also configure some parameters for exporting the CSV file like the delimiter character.

Permissions

At the first start of fbdump you must grant read access permission to your data. If you use the dumper on a PC a browser window should be opened automatically. If you use it in a terminal or if your browser does not start automatically copy and paste the shown link to a browser.
In the browser follow the instructions. Log in to your FitBit account, provide read access to the dumper and copy and paste the shown PIN code back to the fbdump prompt. If the dumper finishes without errors you now can export your fitness data.

Click on a picture for a larger view