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. This can be done either by the user in my.withings.com or by the user from a third party's web site using its proper email/password combination.

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 issue requests here

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

Identification

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 the publickey. In most requests, those two parameters are mandatory. Both can be found, for testing, in the 'Share' overlay within the user's dashboard at http://my.withings.com.

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.

Subscriptions will not be performed if the user has not allowed its profile to be public. 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.

						{
							"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,
									"ispublic": 1
								}
							]
						}
					}
								

					{
						"status": 0,
						"body": {
							"users": [
								{
									"id": 29,
									"firstname": "John",
									"lastname": "Doe",
									"shortname": "JON",
									"gender": 0,
									"fatmethod": 0,
									"birthdate": 211629600,
									"ispublic": 1,
									"publickey": "3753a06f1c5ee6a0"
								},
								{
									"id": 31,
									"firstname": "Jane",
									"lastname": "Doe",
									"shortname": "JAN",
									"gender": 1,
									"fatmethod": 0,
									"birthdate": 829562400,
									"ispublic": 1,
									"publickey": "3e203cb659c03995"
								},
								{
									"id": 37,
									"firstname": "Natalie",
									"lastname": "Doe",
									"shortname": "NAT",
									"gender": 1,
									"fatmethod": 0,
									"birthdate": 329911200,
									"ispublic": 1,
									"publickey": "051fc9bb6fa571a9"
								}
							]
						}
					}

								

						{
							"status": 0
						}
								

						{
							"status": 0
						}
								

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