Create a gist now

Instantly share code, notes, and snippets.

What would you like to do?
Everything Wrong With The Withings API

Top Six Things You Need To Know About The Withings API*

*where “you” is probably a developer, or at least a strange user

I should preface this by saying that I got a Withings Smart Body Analyzer for Christmas last year and I’ve been generally happy with it. It purports to be able to take my heart rate through my bare feet and that seems not to work for my physiology, but overall I’m a fan. If if their Wikipedia page is to be believed they are having a pretty rad impact on making the Quantified Self movement more for normal people and they only have 20 full time employees. Also they try hard to use SI units, which I can get behind. Anyway, on to the rant.

I originally called this post “Everything wrong with the Withings API” and I meant it. For every useful field I can extract from their “award winning” app, I have spent an hour screaming at the inconsistencies in their implementation or inexplicable holes in their data coverage. This is as much a post for developers looking for reasons why they are tearing their hair out trying to access an unruly metric as it is for anyone who provides a third party API that is intended to be consumed by anyone not themselves, and what us poor data consumers have to deal with.

It’s inconsistent about formatting

Sometimes we assemble a query for startdate (which needs to be formatted as a time in epoch seconds, for sleep detail measures) and sometimes for startdateymd (which returns a starttime in epoch milliseconds for sleep summary measures). Some measures return device identifiers: a model 16, for example, is their Pulse watch, and a model 32 is their Aura bedmat. What then am I to make of a sleep data object reporting a model 61??

Model 61, you say?

They don’t understand OAuth.

“The Withings OAuth implementation is not perfect” says the gentle author in the README for the withings-request node module. That author has helpfully rendered transparent a lot of the failings (encrypting the wrong url parameters, returning unparseable nonsense) to consumers of the data, and for that I am grateful. I’m not sure if this is a problem of multiple authors on the part of Withings or what. Hey, try a code review.

Cat quota: complete

It is incomplete

Their API lacks access to certain measures, like the Smart Body Analyzer is supposed to track air quality and it doesn’t show up even in v2. It’s their prerogative, I suppose, and might plausibly have the benefit of forcing people to come back to the mothership app? Anyway, even with an enabled subscription it will arbitrarily and for no reason not deliver days worth of data of one measure or another. When it does deliver the data it disagrees with the primary presentation in the master: see below to contrast (1) a week of data as presented in the app (2) a week of data as returned by a sleep detail query and (3) the same week as queried for at the sleep summary endpoint.

Data they are willing to present

Caption3b: This is the JSON output of the sleep detail for this past week. Notice not a single “state:3”, which would represent REM sleep

{
model: 16,
series: [
{
startdate: 1421586709,
state: 2,
enddate: 1421587669
},
{
startdate: 1421587669,
state: 1,
enddate: 1421589589
},
{
startdate: 1421589589,
state: 2,
enddate: 1421593849
},
{
startdate: 1421593849,
state: 1,
enddate: 1421595229
},
{
startdate: 1421595229,
state: 2,
enddate: 1421596429
},
{
startdate: 1421596429,
state: 1,
enddate: 1421599309
},
{
startdate: 1421599309,
state: 2,
enddate: 1421601769
},
{
startdate: 1421601769,
state: 1,
enddate: 1421602189
},
{
startdate: 1421602189,
state: 0,
enddate: 1421603089
},
{
startdate: 1421603089,
state: 1,
enddate: 1421603569
},
{
startdate: 1421603569,
state: 0,
enddate: 1421603629
}
]
}

Caption 3c: The JSON output of the sleep summary data for this past week, indicating upwards of single-digit minutes of REM sleep on a given night instead of multiple hours as in the app screenshot. A somewhat abbreviated snapshot of reality

It disagrees with itself

Conversely but just as irritatingly, for some days a user on a single account will get several sets of sleep summary data, with several mutually incompatible descriptions of the same night. Look at how many times I must have traveled back and forth in time last Thursday, for example.

Extra data that disagrees with itself!

Account linking and device sharing is terrible.

My partner and I share a scale and prior to its purchase we had separate accounts, but couldn’t figure out how to get it to recognize a measurement as his without making him a new account which was subordinate to mine, which screwed up activity tracking through his own phone. Now he basically doesn’t use the step counter, so, fail.

This is also a very special advanced use case but my boss, another colleague, and I are all 'friends' or 'connections' or whatever on Withings and weigh within rounding error of each other (I gather that the delta must be like 10 pounds). This means that about one time in three, I'll get one of their weights as the data point in my graph, and vice versa, and the jump is still five pounds or more. With only two people of approximately the same weight sharing a scale, you take a measurement then lean to the left foot or right foot to indicate which account you want the measurement to go to. But with three people in range, it's arbitrary, and sucks.

They don't listen

I wrote to them complaining about this and got a rapid, unhelpful response, where the link to the referenced press release returns a 404. Customer service is hard.

This is the assistance you get.

In conclusion, Withings, you’ve got good products and I wish you the best as a company, but I quietly curse you about 30 times a day. Please don’t take it personally.

This is brilliant. Was about to get one from amazon to satiate the inevitable newyear fitness drive in our house and give me something new to hack. Might just make one from a Raspberry Pi instead.

bxlouis commented Jul 2, 2016 edited

I agree with you, Withings has got good products but does not listen to its customers.

However, in caption 3b, it is normal there is no REM since you're asking an Activity Tracker (model = 16) which does not record this sleep phase.

Anyway, I have a question maybe you will be able to help me! Is there a way to ask the Aura if someone is in bed at a precise moment? It would be really useful in a home automation system, in order to trigger a "night" scene (close all the blinds, turn down the heater, etc.).

Also, is it possible to retrieve the alarm(s) value(s) ? Same thing, one could trigger a "wake up" scene (open the blinds, turn on the bathroom heater...) ?

cloom commented Nov 5, 2016

I have the smart body analyzer that also takes temperature humidity and I was so happy and excited to use the API to get my bedroom's temperature (yes I jump on it in the morning and before going to bed sometimes).
I was so disappointed when I realized it was not possible. I really don't understand how you can provide API for one type of data and not another, this should be pretty much the same code. So at the end, I never use the temperature data this device is getting :(

Have You tested, how fast data appears on their server. I.e. is it possible to detect that user has entered into light sleep phase within couple of minutes, or it takes much more time until the data appears?

jlwin commented Jan 23, 2017

Has anyone been able to get the activity score that is displayed e.g. on the Withings Steel HR/pop/activé in the second dial? I would like to manipulate the shown score with any other score on a 0-100 scale that I provide to an api. For example: I would like to show my rescuetime.com productivity score on my watch.
Any Idea how to make this happen? If there is a possibility to change the goal, I could set the step goal to a value that is calculated based on the current amount of steps and the productivity score value (step goal = current amount of steps / own score).

atbyrd commented Apr 2, 2017

Has anyone seen the x-recruitment headers?

kempyk commented May 14, 2017

Great article highlighting the problems out there! Does anyone have an examples that export the intraday heart rate readings out to say a csv? Seems like a such as basic ask that's missing from their product i can't believe someone hasn't coded something like this already since the steel HR is out.

caedn commented May 29, 2017

Thank you for the article. I was pulling my hair out trying to get some more data from the API. Withings really need to fix this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment