Introduction

Withings BodyScale 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.

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.

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 the user's weight and body fat, 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 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 measurements. A user is part of an account.

An account is what BodyScale 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 BodyScale 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 BodyScale 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 weigh-in, 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"
			}
		}