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 :

Where :
[service_name] is the requested service,
[action_name] is the action you want to perform on the requested service,
[parameters] are parameters, mandatory or optional, passed to the requested service.

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:

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):

returns

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.

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). 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 :

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

• 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.

						{
							"status": 0,
							"body": {
								"updatetime": 1249409679,
								"measuregrps": [
									{
										"grpid": 2909,
										"attrib": 0,
										"date": 1222930968,
										"category": 1,
										"measures": [
											{
												"value": 79300,
												"type": 1,
												"unit": -3
											},
											{
												"value": 652,
												"type": 5,
												"unit": -1
											},
											{
												"value": 178,
												"type": 6,
												"unit": -1
											},
											{
												"value": 14125,
												"type": 8,
												"unit": -3
											}
										]
									},
									{
										"grpid": 2908,
										"attrib": 0,
										"date": 1222930968,
										"category": 1,
										"measures": [
											{
												"value": 173,
												"type": 4,
												"unit": -2
											}
										]
									}
								]
							}
						}


								

					{
						"status": 0,
						"body": {
							"users": [
								{
									"id": 29,
									"firstname": "John",
									"lastname": "Doe",
									"shortname": "JON",
									"gender": 0,
									"fatmethod": 0,
									"birthdate": 211629600,
								}
							]
						}
					}
								

						{
							"status": 0
						}
								

						{
							"status": 0
						}
								

						{
							"status": 0,
							"body": {
								"expires": 2147483647,
								"comment": "Your Own Application Description"
							}
						}
								

                                {
                                    "status":0,
                                    "body": {
                                        "profiles": [{"expires":2147483647,"comment":"http:\/\/www.withings.com"},{"expires":2147483647,"comment":"http:\/\/www.corp.withings.com"}]
                                    }
                                }
								

What if I need more help ?