Stata and cURL

​The Fitbit API and OAuth 2.0

Why Care Block:
OAuth 2.0 is in use for most API's, from Fitbit toFacebook, Instagram to Twitter.
​cURL works seamlessly with Stata's syntax and allows for sending HTTP requests – in English, we can take advantage of a lot of good resources.

​Setting It Up

Welcome to part two of the three part series regarding Fitbit Heart Rate data.  Quick recap: part one showed us how to encode strings in Base64, which we will use today.
​
I think it's safe to say that people are fascinated by themselves and their day-to-day biology that usually goes unnoticed.  The trend of wearable technology seems to be thriving and shows little sign of a slowdown.  Fitbit, in particular, has exploded in popularity as one can be seen sported by President Obama on the latest episode of Comedians in Cars Getting Coffee.  Now I have to mention that I don’t think I’d have this interest if it were not for Belen, first for introducing me to the Fitbit and second for being such great competition in our respective daily step goal challenges.

While Fitbit does an excellent job at providing a great amount of data available to your fingertips, heart rate data has been particularly elusive.  Why?  Well, it's probably what people are most interested in when buying the Charge HR and could be used in conjunction with step count to paint a pretty accurate picture of the wearer's habits – hence it's only available using their API.  The following provides a mid-level description of how we go about getting access to our own data.  Let's start with registering an Application, you can read more about it at https://dev.fitbit.com/docs.

​​Enter all your personal information, but pay special attention to the sections above.  If you want Heart Rate data, you must select the "Personal" box under OAuth2.0 Application Type*.  You may wish to give your application Read and Write privileges as well if it's your own personal application.  Finally, you can use the Callback URL http://www.wmatsuoka.com/fitbitapi.html or you can use any other site.  It's just the redirection site after authentication, more on this in the next section. 

​First Stage: Code

From here on out, all important variables have been color coded to easily see what's going on.  

Find your application's client_id and client_secret by going to "MANAGE MY APPS".  Click on your App and you'll see the following information: 

​Enter this information into the following code snippet below:

local client_id     "BBC123"
local client_secret "9gh68g9fg77ff896ihh7gi8ih768f96i"
local redirect      "http%3A%2F%2Fwww.wmatsuoka.com%2Ffitbitapi.html"

encode64 "`client_id':`client_secret'"
local client64 = r(base64)
                               // This can be ran straight from a browser
local url = "https://www.fitbit.com/oauth2/authorize"                 ///
    + "?response_type=code&client_id=`client_id'"                     ///
    + "&redirect_uri=`redirect'"                                      ///
    + "&scope=activity%20nutrition%20heartrate%20location%20"         ///
    + "nutrition%20profile%20settings%20sleep%20social%20weight"

view browse "`url'"

What's going on here?  We store the Client ID, Client Secret, and Callback URL in local macros.  The previous post's encode64 appears here, but isn't used until the next section.  These locals are passed into a single string which is then passed to your browser using the view browse command.  After entering your login information, this is the following result:

Here, I've provided an example of how you would manually input this code into Stata.  If you wish for more automation, just know that the code appears in the URL.  For example, if your Callback URL is http://www.google.com, then the code would appear as:

http://www.google.com?code=abcdefghijklmnopqrstuvwxyz916

​
​Second Stage: Authorization

Well we did it! We made it to the cURL section.  Make sure you've downloaded cURL and can call it from your command prompt (curl --help).

First, we need to know a little bit about the shell command.  Shell (which can also be called by typing "!") allows you to send operating system commands from Stata, the advantage of the shell command is that it will wait until the command has finished before resuming the Stata do-file.  Alternatively, there's the command winexec – it operates like shell, with the exception that Stata won’t wait for it to complete before moving on to the next do-file command.

In order to pass the code back to Stata after viewing the code in your browser, I like to use the display directive _request().  It halts your code and allows you to enter a value before continuing, storing the value in a global macro.

display "Please wait for browser "                                  ///
    "and enter the code from the redirect URL" _request(code)
if ("$code" == "") exit

local d_client "client_id=`client_id'"
local d_auth   "grant_type=authorization_code"

!curl -i -H "Content-Type: application/x-www-form-urlencoded"       ///
    -H "Authorization: Basic `client64'" --request POST --data      ///
    "`d_client'&`d_auth'&redirect_uri=`redirect'&code=$code"        ///
    https://api.fitbit.com/oauth2/token                             ///
    --output "accesstoken.json"

​
​This asks for your access token, which is necessary to make any request to Fitbit and places the result in the file "accesstoken.json".  You can see that it uses your client_id, the Base64 encoded local made in the previous stage, and the code that you entered from the browser.  You may change the output file name, but the information contained should be the following:

Response from server:
{
 "access_token" : "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0NTE4MDAyNjksInNjb3BlcyI6Indsb2Mgd3BybyB3bnV0IHdzZXQgd3NsZSB3aHIgd3dlaSB3YWN0IHdzb2MiLCJzdWIiOiIzSzdQVzYiLCJhdWQiOiIyMjlZRFciLCJpc3MiOiJGaXRiaXQiLCJ0eXAiOiJhY2Nlc3NfdG9rZW4iLCJpYXQiOjE0NTE3OTY2Njl9.nO9nHAM2daPPvAMd6wIJgAc7B4KKRXFP6X8Jawy-l8s",
 "expires_in" : "3600",
 "refresh_token" : "4fe7f608a98644205161d85f91f7e3034d8cf463d89f1dd7e89f84b096a2f0ff",
 "scope" : "nutrition sleep settings social weight activity heartrate profile location",
 "token_type" : "Bearer",
 "user_id" : "WMM999"
}

​You may parse this file how ever you wish, just make sure to take the access_token and, optionally, the user_id (you can just memorize this value and hardcode it into your requests if the application is only for your personal use).  The token lasts for an hour, so you may use it to call multiple requests within the Fitbit's call limit which happens to be 150 requests per hour.

​Third Stage: Requests

​Now that all that security stuff is out of the way, we can actually do work and start pulling our data.

global uid    = "WMM999"
local d       = "2015-12-31"
local fburl   = "https://api.fitbit.com"
local request = "`fburl'/1/user/\$uid/activities/heart/date/`d'/1d/1sec.json"
local output  = "output_file.json"

winexec curl -i -H "Authorization: Bearer $access_token" ///
        --request GET "`request'" --output "`output'"

Here, we store the access token parsed from the previous stage in the global $access_token.  I separated the request into separate locals to be easier to change certain values, but it could easily be written as a single string.  Finally, we use winexec over shell in this stage, because we can contain this last statement within a loop and execute multiple requests almost simultaneously.   The request above stores second-level heart rate data from the last day of the year in the file "output_file.json"; an example of this data will be shown in the next post.  

For a full list of requests, check out Fitbit's website.  Otherwise, try practicing this method with other APIs - you'll be surprised by what you find!