Basis Data Export

Utility that exports and saves your Basis B1 devices' uploaded sensor data. You can learn more about Basis at http://www.mybasis.com/

Instructions

In order to use this script, you must already have at least one Basis account (and a Basis B1 band).

Usage:

This script can be run several ways. You should put the usernames and passwords of the Basis accounts you want to download data from in a file called users.csv. Each pair of username and password should be in its own line and be comma separated. You should enter the BASIS_EXPORT_FORMAT value in the file basisdataexport.php so you don't have to specify the value every time the script is run. Make sure the data/ folder is writable!

Method 1 - Interactive Mode

1. Open a terminal window and cd to this script's directory
2. Type php basisdataexport.php
3. Follow the prompts (hit ENTER to use default values)
4. Your data will be saved to /data/basis-data-[YYYY-MM-DD].[format]

Method 2 - Via command-line arguments (useful for crons)

$ php basisdataexport.php -s2014-11-01 -e2014-11-05 -fcsv

Usage php basisdataexport.php -h -s[YYYY-MM-DD] -e[YYYY-MM-DD] -f[json|csv]

Options:
  -s Data export start date (YYYY-MM-DD) (if not used, defaults to yesterday's date)
  -e Data export end date (YYYY-MM-DD) (if not used, defaults to current date)
  -f  Data export format (json|csv) (if not used, defaults to json)
  -h  Show this help text

Make sure there are no spaces between any flags and values!

Saving Your Data

If the script runs successfully, your data will be saved in the data/ folder. Files are saved in the format basis-data-[YYYY-MM-DD].[format] (i.e., basis-data-2014-04-04.json).

That's it! (for now).

Biometric Data

Basis currently returns the following biometric data points. They each represent an average (i.e., for heart rate, GSR, skin/air temperature) or sum (i.e., steps, calories) over the previous 1-minute period:

• Time - time reading was taken
• Heart Rate - beats per minute
• Steps - number of steps taken
• Calories - number of calories burned
• GSR - Galvanic skin response (i.e., sweat/skin conductivity. Learn more about GSR here - http://en.wikipedia.org/wiki/Skin_conductance)
• Skin Temperature - skin temperature (degrees F)
• Air Temperature - air temperatute (degrees F)

There are some other aggregate metrics included in the reponse such as min/max/average/standard deviation metrics for each set of data.

Sleep Data

Basis currently returns the following sleep data points (it's in a different format than the metrics data because it's a newer version of their API):

• Start Time - local timestamp in MM/DD/YY HH:MM format
• Start Time ISO - user timestamp in ISO format
• Start Time Time Zone - user time zone, i.e., America/New_York
• Start Time Offset - minutes offset from GMT (i.e., -240 for America/New_York)
• End Time - user timestamp in MM/DD/YY HH:MM format
• End Time ISO - user timestamp in ISO format
• End Time Time Zone - user time zone, i.e., America/New_York
• End Time Offset - minutes offset from GMT (i.e., -240 for America/New_York)
• Light Minutes - number of minutes in "light sleep" stage
• Deep Minutes - number of minutes in "deep sleep" stage
• REM Minutes - number of minutes in "REM sleep" stage
• Interruption Minutes - number of minutes interrupted (i.e., woke up, went to bathroom, etc.)
• Unknown Minutes - number of minutes unknown (i.e., device wasn't able to take readings)
• Tosses and Turns - number of tosses and turns that occurred
• Type - always returns 'sleep'
• Actual Seconds - total sleep time recorded, in seconds
• Calories - number of calories burned
• Average Heart Rate - beats per minute
• Minimum Heart Rate - beats per minute (currently this always returns null)
• Maximum Heart Rate - beats per minute (currently this always returns null)
• State - returns 'complete' if event was completed at time of export
• Version - API version used (i.e., 2)
• ID - internal id for given sleep event

Sleep data is often broken into multiple segments - Basis treats each sleep activity as a separate 'event' if there is a 15-minute gap in readings (i.e., sensors couldn't detect anything).

Activity Data

Similar to sleep data, Basis currently returns the following activity data points (walking, biking, running):

• Start Time - local timestamp in MM/DD/YY HH:MM format
• Start Time ISO - user timestamp in ISO format
• Start Time Time Zone - user time zone, i.e., America/New_York
• Start Time Offset - minutes offset from GMT (i.e., -240 for America/New_York)
• End Time - user timestamp in MM/DD/YY HH:MM format
• End Time ISO - user timestamp in ISO format
• End Time Time Zone - user time zone, i.e., America/New_York
• End Time Offset - minutes offset from GMT (i.e., -240 for America/New_York)
• Type - activity type (i.e., walk, run, bike)
• Actual Seconds - total activity time, in seconds
• Steps - number of steps taken
• Calories - number of calories burned
• Minutes - actual number of minutes activity was performed (excludes time not moving?)
• Average Heart Rate - beats per minute (currently this always returns null)
• Minimum Heart Rate - beats per minute (currently this always returns null)
• Maximum Heart Rate - beats per minute (currently this always returns null)
• State - returns 'complete' if event was completed at time of export
• Version - API version used (i.e., 2)
• ID - internal id for given sleep event

Tips

• You can set up a cron to run once per day to automatically grab your previous day's data (assuming you are syncing your device each day)

• If you want to archive data across a date range you can use curl's [ ] syntax to do it easily (thanks to @Edrabbit for the tip!). For example, to get all of May cached in /data:

  curl http://localhost/basis-data-export/basisdataexport.php?date=2013-05-[01-31]

Special Tip for Windows Users and Setting Up SSL/cURL

(Thanks to @joshuagarity for the tip!) If you haven't already, you will need to install an SSL certificate on your system in order for the script to work (because the user authentication only works over SSL, and is required by cURL). Here's how:

• Download a certificate file at http://curl.haxx.se/ca/cacert.pem and save it somewhere on your computer

• Run update php.ini -- add curl.cainfo = "PATH_TO/cacert.pem" where "PATH_TO/cacert.pem" is the location of the certificate file you just downloaded. If you are running XAMPP, you would save the cacert.pem to c:\xampp\cacert.pem. Then, open XAMPP, click on Config, then selected PHP.ini. On the second line of the file paste the following:

  curl.cainfo = "C:\xampp\cacert.pem"

• Lastly, save the file and you should be able to run the script.