Withings API Quickstart Guide

Two weeks ago I spent some time getting acquainted with the Withings API in order to access my heart rate and weight data tracked by their Smart Body Analyzer.

It was a painful experience. But I did eventually get things up and running. #woot

I thought I would share the process I took in the hopes that it will alleviate other poor souls from having to endure such pain!

1. Register Your Application

The purpose here is to identify and authenticate your application.

Register your app.

It might be helpful to register a dev app and your production app separately.

You will be provided the following two keys:

WITHINGS_OAUTH_CONSUMER_KEY='123456abcdef'
WITHINGS_OAUTH_CONSUMER_SECRET='123456abcdef'

Log in to my.withings.com. In your "sharing" settings you can grab the following user id:

WITHINGS_USER_ID='1234567'

2. Get Temporary Request Token

The purpose here is to identify your request for OAuth authorization.

Install the withings-api gem:

gem install 'withings-api'

Boot up your console:

include Withings::Api

consumer_token = ConsumerToken.new(WITHINGS_OAUTH_CONSUMER_KEY, WITHINGS_OAUTH_CONSUMER_SECRET)
=> #<Withings::Api::ConsumerToken:0x007fe32fc007c8 @key="123456abcdef", @secret="123456abcdef">

request_token_response = Withings::Api.create_request_token(consumer_token, "http://api.localhost:5000")
=> #<Withings::Api::RequestTokenResponse:0x007fe32c260428 @oauth_request_token=#<OAuth::RequestToken:0x007fe32c260478 @token="789101112ghijkl", @secret="789101112ghijkl", @consumer=#<OAuth::Consumer:0x007fe32c1f2b08 @key="123456abcdef", @secret="123456abcdef", @options={:signature_method=>"HMAC-SHA1", :request_token_path=>"/account/request_token", :authorize_path=>"/account/authorize", :access_token_path=>"/account/access_token", :proxy=>nil, :scheme=>:query_string, :http_method=>:get, :oauth_version=>"1.0", :site=>"https://oauth.withings.com"}, @http_method=:get, @http=#<Net::HTTP oauth.withings.com:443 open=false>>, @params={:oauth_token=>"789101112ghijkl", "oauth_token"=>"789101112ghijkl", :oauth_token_secret=>"789101112ghijkl", "oauth_token_secret"=>"789101112ghijkl"}>>

request_token = request_token_response.request_token
=> #<Withings::Api::RequestToken:0x007fe32c215d88 @key="789101112ghijkl", @secret="789101112ghijkl">

3. Authorize Request Token

The purpose here is to authorize your access to this user's account data.

request_token_response.authorization_url
=> "https://oauth.withings.com/account/authorize?oauth_token=789101112ghijkl"

Copy and paste the above link into your web browser. A redirect will happen. Once completed copy that new link in your address bar to a text document on your local machine.

http://api.localhost:5000/?userid=1234567
&oauth_token=789101112ghijkl
&oauth_verifier=AmbCCIRYdZKWLPiQyG

4. Get Permanent Access to the Data

Now that your request_token has been authorized:

access_token_response = Withings::Api.create_access_token(request_token, consumer_token, "user_id_not_currently_required_by_withings")
=> #<Withings::Api::AccessTokenResponse:0x007fe32ed34b18 @oauth_access_token=#<OAuth::AccessToken:0x007fe32ed34cf8 @token="131415161718mnopqr", @secret="131415161718mnopqr", @consumer=#<OAuth::Consumer:0x007fe32ec35730 @key="123456abcdef", @secret="123456abcdef", @options={:signature_method=>"HMAC-SHA1", :request_token_path=>"/account/request_token", :authorize_path=>"/account/authorize", :access_token_path=>"/account/access_token", :proxy=>nil, :scheme=>:query_string, :http_method=>:get, :oauth_version=>"1.0", :site=>"https://oauth.withings.com"}, @http_method=:get, @http=#<Net::HTTP oauth.withings.com:443 open=false>>, @params={:oauth_token=>"131415161718mnopqr", "oauth_token"=>"131415161718mnopqr", :oauth_token_secret=>"131415161718mnopqr", "oauth_token_secret"=>"131415161718mnopqr", :userid=>"1234567", "userid"=>"1234567"}>>

Store this access token in your app's database for future data requests for this user.

access_token = access_token_response.access_token
=> #<Withings::Api::AccessToken:0x007fe32ed6d080 @key="131415161718mnopqr", @secret="131415161718mnopqr">

You've gained access for this user:

access_token_response.user_id
=> "1234567"

The OAuth access token key/secret:

access_token.key
=> "131415161718mnopqr"
access_token.secret
=> "131415161718mnopqr"

WITHINGS_OAUTH_TOKEN=131415161718mnopqr
WITHINGS_OAUTH_SECRET=131415161718mnopqr
You can use data access methods for retreiving user Withings data.

5. Access the Data

Now we can get some "actual" data! Install the simplificator-withings gem:

gem install 'simplificator-withings'
gem install 'ruby-hmac'

Boot up your console again:

require 'withings'
include 'Withings'

oauth_token='131415161718mnopqr'
oauth_token_secret='131415161718mnopqr'
user_id='1234567'

response = Withings::Connection.get_request('/user', oauth_token, oauth_token_secret, :action => :getbyuserid, :userid => user_id)
=> {"users"=>[{"id"=>1234567, "firstname"=>"Christopher", "lastname"=>"Hopkins", "shortname"=>"CTH", "gender"=>0, "fatmethod"=>132, "birthdate"=>470336400, "ispublic"=>0}]}

user_data = response['users'].detect { |item| item['id'] == user_id.to_i }

user = Withings::User.new(user_data.merge({:oauth_token => oauth_token, :oauth_token_secret => oauth_token_secret}))
=> #<Withings::User:0x007f8b74763980 @short_name="CTH", @first_name="Christopher", @last_name="Hopkins", @user_id=1234567, @birthdate=1984-11-26 12:00:00 -0500, @gender=:male, @fat_method=132, @oauth_token="131415161718mnopqr", @oauth_token_secret="131415161718mnopqr">

user.measurement_groups(device: Withings::SCALE)

To get your weight:

user.measurement_groups(measurement_type: 1).first.weight

# To convert to lbs
(lbs_weight*2.20462).round(2)

To get your heart rate (although not supported yet through the official docs):

user.measurement_groups(measurement_type: 11).first

6. Build Something Handsome

If you find this useful and end up using your data for something cool I would love to hear about it — tweet me. And in case you missed it, check out the dashboard + api I built that uses these two data sets plus more.