Withings

Body scale Blood pressure monitor Baby Monitor Store My account

Developer resources (API)

Document revision date : Jul 7th 2011 [v2.0]

Contents
Introduction
Basics
Identification
Service Catalog

Introduction

Withings Body metrics Services API (WBS API) is a set of webservices allowing developers and third parties limited
access to users' data.

Prior to any access by an external application, the user has to explicitly allow their data to be accessed through the
WBS API. The authentication and provisionning procedure is described in our Oauth implementation guide.

It is freely available for non-commercial use by any developer and may be licensed (or freely licensed in some
cases) for commercial use by prior arrangement.Please review the API terms of use and register your service, website
or application here. Please contact us if you have any question regarding this process.

A small PHP library is available to illustrate this documentation. Giving it a look will save you time. It is here.

Stefan Andersen feeled the urge to rewrite this sample code using more classes and exceptions. You can find it here.

If you are an iPhone developer, you may download the sample iPhone application source code. This application is a
example of code to illustrate the API and not the wiScale application. It will anyway save a lot of time to those
integrating our API in an iPhone application.

Android developers can find sample code and more information about integration with Android applications in this page

Basics

Request format
The WBS API is REST-based. Basically, WBS requests are sent as HTTP POST or GET requests.

A typical WBS API service request follows this template :

http://wbsapi.withings.net/[service_name]?action=[action_name]&[parameters]

Where :
[service_name] is the requested service,

http://www.withings.com/en/api/wbsapiv2[10/14/2011 6:57:18 PM]

Withings

[action_name] is the action you want to perform on the requested service,

[parameters] are parameters, mandatory or optional, passed to the requested service.

Authentication
Alongside the [parameters] aforementionned, you will need to provide the required Oauth related parameters.
These are not detailled here for simplicity's sake, but please keep in mind that Oauth authentication is
mandatory. More information regarding Oauth are given in the Oauth section. Please make sure you first
carefully read our Oauth implementation guideline beforehand.

Every service needs a mandatory action parameter. For example, the user service has two possible actions
(getbyuserid and update). action is a parameter of the GET or POST request (user?action=getbyuserid)

For every thing you want to do, there is a service and an action. The measure?action=getmeas service, which gets
anything ranging from the user's weight and body fat to blood pressure and heart pulse, is probably the most useful.

Response format
Responses to such requests are JSON documents. All responses look like the following:

{"status":0, "body":{} }

The body field may eventually be absent or empty, depending on the service/action requested and the success or
failure of the requested action.
Any single response will provide a mandatory status field. A status value set to 0 means that the action was
successfully processed. Other values mean the request was not processed properly. Please refer to the Error codes
sections to get a hint as to what went wrong, and why.

A json library IS available for your programming language at http://www.json.org. Please don't try to parse a JSON
document without first visiting this site. Use an already available JSON library: it saves a lot of effort.

As a first example (and this is a good starting point to check that this is working in your actual environement):

http://wbsapi.withings.net/once?action=probe
returns

{"status":0}

Authentication
You typically use the WBS API to retrieve data related to a given user, for example weight and body fat or blood
pressure measurements. A user is part of an account.

An account is what Withings device users use to log into their dashboard. An account is uniquely defined by an email
address. For access to be granted to a given account, its password (chosen by the user at registration time) is needed.
A single account might be used by several device users (a parent and their young kids), or each user might have their
own account.

However, Withings currently offers two kinds of accounts : standard accounts and professional oriented accounts. The
later differentiates from the fact that it only contains an anonymous 'Unknown user' and that additional users can not be
added. Since professional oriented accounts only feature the 'unknown' user, the API will only obviously only give
access to that user. On the other hand, for standard accounts, only users created through the "Add a new user" button
will be accessible through the API.

A user (as listed in the dashboard's leftmost part) of a Withings device is uniquely defined by a userid and is tied to
your own application through his Oauth credentials. These parameters are mandatory in all requests and are given
back to your application as soon as you tie your application to the userid. For more information on setting up and
retrieving Oauth credentials between your application and a Withings user, please refer to Oauth implementation
guidelines. Every single request made to WBSAPI must include authentication parameters, and in particular an Oauth
signature that will allow the API to authenticate you.

The required Oauth parameters are :

oauth_consumer_key : the Oauth token tied to your very own application. Could be thought as a public key for your
application. This token is retrieved during the Oauth provisionning setup between the user and your application, refer to
Oauth implementation guidelines to get your application's credentials.
Eg : oauth_consumer_key=7e563166232c6824642b4c277350494ff55f392b353e5d49712a34762a
oauth_token : The Oauth token of the Withings user tied to your application (ie tied to your own consumer_token).

http://www.withings.com/en/api/wbsapiv2[10/14/2011 6:57:18 PM]

Withings

This token is retrieved during the Oauth provisionning setup between the user and your application, refer to Oauth
implementation guidelines.
Eg : oauth_token=c68567f1760552958d713e92088db9f5c5189754dfe4e92068971f4e25d64
oauth_nonce : a random hexadecimal string you generate.
Eg : oauth_nonce=f22d74f2209ddf0c6558a47c02841fb1
oauth_version : the supported Oauth version, currently 1.0.
Eg : oauth_version=1.0
oauth_signature_method : the Oauth signature method, preferred method is HMAC-SHA1.
Eg : oauth_signature_method=HMAC-SHA1
oauth_timestamp : the current EPOCH timestamp.
Eg : oauth_timestamp=1309783586
oauth_signature : the Oauth signature. This is calculated from the complete HTTP request. Please see Signing an
Oauth request for complete guide on signing your requests to the WBSAPI.
oauth_signature=yAF9SgZa09SPl3H1Y5aAoXgyauc

A complete WBSAPI request would be :

http://wbsapi.withings.net/measure?
action=getmeas&oauth_consumer_key=7e563166232c6821742b4c277350494a455f392b353e5d49712a34762a&oaut
h_nonce=f22d74f2209ddf0c6558a47c02841fb1&oauth_signature=yAF9SgZa09SPl3H1Y5aAoXgyauc=&oauth_signat
ure_method=HMAC-
SHA1&oauth_timestamp=1309783586&oauth_token=c68567f1760552958d713e92088db9f5c5189754dfe4e92068971
f4e25d64&oauth_version=1.0&userid=1229

Yes, parameters order does matter !

Although the HTTP standards states that the HTTP request parameters order do not matters, they actually do
when it comes to OAuth authentication.
So that to allow for non ambiguous signature generation, and since signature is derived from the request, the
Oauth standard clearly states that the signature must be calculated on a "base string" obtained from the
parameters contained in the request (except the oauth_signature of course) you want to submit, and that all the
parameters of the query shall be sorted alphabetically. Hence, signing "userid=12&oauth_method=HMAC-
SHA1..." and signing "oauth_method=HMAC-SHA1&userid=12..." will result in two different signatures and hence
your authentication will fail.
Please make intensive use of Quonos Oauth Checker to check your authentication algorithms.

Notification
The most effective way for third parties to retrieve measurements updates is to setup notifications (some might call it
"Push") for the users they are interested in. Notifications are handled on a user-per-user basis : each third party
application shall subscribe once for every user being monitored, as explained here. Each time the subscribed users
use their device and make it create a new measurement, or manually add, delete or modify any measurement or
objective, the WBS API will send notifications to all their monitoring third parties.

A given user can not be subscribed by more than 16 third parties.

When the WBS API sees that subscriber data has been modified, it sends a notification to the subscribing third party
application. The notification contains information that helps to determine what should be downloaded to remain in sync.

Notifications subscriptions last 3 weeks and it is the subscriber responsability to renew the subscription when
necessary, as explained here. Checking for the existence of a subscription and the retrieval of its expiry date can be
performed as shown here.

Would you need to list all the subscriptions you previously set for a given user, have a try with list.

The subscription can be revoked at anytime, as explained here.

Service Catalog
Depending on what you want to do, you may use the following services:
I want to GET some (or all) measurements of a specific user for which I have the userid and the Oauth
credentials. I use measure?action=getmeas . You may need to use user?action=update the target user to enable
your access to a given type of device measures.
I want to GET available information for a specific user for which I have the userid and the Oauth credentials. I use
user?action=getbyuserid .
I would like my application to be notified of measurement related event for the users I supervise whenever as they
happen. I use notify?action=subscribe.
I want to stop a notification I had put in place. I use notify?action=revoke.
I want to GET information about a notification I may have set up. I use notify?action=get.

http://www.withings.com/en/api/wbsapiv2[10/14/2011 6:57:18 PM]

Withings

measure / getmeas

Several use cases can be performed with this service, depending on its input parameters.

The userid parameter is mandatory. ALL others are provided for filtering purposes and are optional.

Parameters Response Example

Parameters
RequiredName Type Description
required userid integer The userid of the target user. This value is obtained when your user links his/her
Withings account with your application.
optional startdate integer Will prevent retrieval of values dated prior to the supplied parameter.
(EPOCH
format)
enddate integer Will prevent retrieval of values dated after the supplied parameter.
(EPOCH
format)
devtype integer Will retrieve data for this particular device type. For exemple, using &devtype=1 will
retrieve all body scale related measures (including weight, fatmass and fatfree
mass), while using &devtype=0 will retrieve all user personal data (ie. the height
and weight entered at user creation time). Can be used as a bitmask if necessary.
meastype integer Will restrict the type of data retrieved (see below the type list). Please note that
currently this filter only supports weight (ie type 1) height (ie type 4) types.
lastupdateinteger Is useful for performing data synchronization. It can be used by the system using
(EPOCH the WBS API to supply the last time (EPOCH format) it acquired data. Only entries
format) which have been added or modified since this time are retrieved.
category integer Can be set to 2 to retrieve objectives or to 1 to retrieve actual measurements.
limit integer Can be used to limit the number of measure groups returned in the result. For
instance, setting &limit=1 will return the last measure group only. Measure groups
are always delivered from the newest to the oldest one.
offset integer Can be used to skip the 'offset' most recent measure group records of the result set.
For instance, setting &offset=10 will return the 11th measure group and onward.
Used in conjunction with limit, it can be used to acquire large data sets in several
requests.

user / getbyuserid

This service will return an array containing information regarding the specified user.

This can be used to retrive a user's firstname, lastname, gender, or birthdate.

Issuing such a request on a professional account 'unknown' user will only yield id and firstname elements since other
ones are not significant for anonymous users.

Parameters Response Example

Parameters
RequiredName Type Description
required useridintegerThe userid of the target user. This can be obtained through an account/getuserslist or
through the user's "Share" overlay in the dashboard.

notify / subscribe

This service allows third parties to subscribe to notifications. Once the notification service has been subscribed, the
WBS API will notify the subscriber whenever the target user's measurements or objectives are added, modified or
deleted.

This allows third party applications to remain in sync with user's data.

To monitor a user, its userid is needed.

Two parameters are mandatory in all cases : userid and callbackurl. The optional parameter appli can be used to
restrict the request to the given device type.

Parameters Response Example

http://www.withings.com/en/api/wbsapiv2[10/14/2011 6:57:18 PM]

Withings

Parameters
RequiredName Type Description
required userid integer The userid of the user to subscribe notification for. This can be obtained through an
account/getuserslist or through the user's "Share" overlay in the dashboard.
required callbackurlURL- The URL the API notification service will call. .
encodedWBS API notification are merely HTTP POST requests to this URL (such as
string http://www.yourdomain.net/yourCustomApplication.php ?
userid=123456&startdate=1260350649&enddate=1260350650). Those requests
contain startdate and enddate parameters (both are integers in EPOCH format) and
the userid it refers to. It is up to the targeted system to issue a measure/getmeas
request using both figures to retrieve updated data.
This URL shall be provided as a URL-encoded string. Please refer to w3schools
URL encoding reference to learn more about URL encoding, use free online URL
encoders or check the example provided. The URL length shall not be greater than
128 characters.
optional appli integer Default value : 1 (Bodyscale). This field specifies the device type for which the
notification is to be activated. See measure/getmeas for supported device types.
required comment UTF-8 The comment string is used as a description displayed to the user when presenting
encodedhim your notification setup.
string

notify / revoke

This service allows third party applications to revoke a previously subscribed notification.

This will disable the notification feature between the WBS API and the specified applications for the specified user.

Two parameters are mandatory in all cases : userid and callbackurl. The optional parameter appli can be used to
restrict the request to the given device type.

Parameters Response Example

Parameters
RequiredName Type Description
required userid integer The userid of the target user.
required callbackurlURL- The URL-encoded URL used when subscribing to the notification service for the
encoded specified user.
string
optional appli integer Default value : 1 (Bodyscale). This field specifies the device type for which the
notification is to be deactivated. See measure/getmeas for supported device types.

notify / get

This service allows third party applications to check whether the notification service was previously subscribed on a
specific user and to retrieve the subscription expiry date.

Two parameters are mandatory in all cases : userid and callbackurl. The optional parameter appli can be used to
restrict the request to the given device type.

Parameters Response Example

Parameters
RequiredName Type Description
required userid integer The userid of the target user.
required callbackurlURL- The URL-encoded URL used when subscribing to the notification service for the
encoded specified user.
string
optional appli integer Default value : 1 (Bodyscale). This field specifies the device type for which the
notification is to be retrieved. See measure/getmeas for supported device types.

notify / list

This service allows third party applications to list all their currently provisionned notification callbacks for a specific user
and to retrieve the subscriptions expiry dates.

Only the userid parameter is mandatory. The optional parameter appli can be used to restrict the request to the given

http://www.withings.com/en/api/wbsapiv2[10/14/2011 6:57:18 PM]

Withings

device type.

Parameters Response Example

Parameters
RequiredName Type Description
required useridintegerThe userid of the target user.
optional appli integerDefault value : 1 (Bodyscale). This field specifies the device type for which the notification
is to be retrieved. See measure/getmeas for supported device types.

What if I need more help ?

Although this API was thought to be easy to understand, you might encounter implementation issues, have questions
or would like to submit new features request or bugs. We warmly encourage you to have a look at the WBSAPI
dedicated forum for any further help.

Follow us Facebook RSS Twitter Blog Keep informed Confirm

Work with us Press Support International Share this page

About us Home Body scale english By email
Become an affiliate RSS feed Blood pressure monitor franais On facebook
Withings App SDK Press releases Baby Monitor deutsch On twitter
Jobs Media kit Contact espaol
Press Contacts italiano

Legal slovaki

Privacy
nederland
Terms and conditions of use
turkish

http://www.withings.com/en/api/wbsapiv2[10/14/2011 6:57:18 PM]