API Developers

Our smart products and apps are all about greater freedom and more choice. And that goes for developers, too.

The Withings API allows developers to create new applications that take advantage of the Withings devices and the data they record.

Using the Withings API, developers can access health data measured by our products, including weight, body fat, lean mass, blood pressure and heart rate and use it to improve their existing user experience – or to create brand new ones. The API is based on OAuth for authentication. It is free to use and lets you retrieve data from our devices seamlessly and without hold-ups.

Simply register your application to get going.

Check out the documentation for more details and sample code. If you have any questions, please contact us at contact-mkt@withings.com.

Last revision date: 18/04/2013Introduction

The Withings Body metrics Services API (further referred as the WBS API) is a set of webservices that gives developers and third-party applications a limited access to the Withings database and user data.

Any access to data through the WBS API is conditioned by the user’s explicit prior approval. The authentication and approval procedure uses OAuth and is described in details in our Oauth implementation guide.

The WBS API offers a notification system that sends Push notifications in near-real time whenever new data is recorded for a user who linked their account with your service. We strongly encourage all partners to make the most of this notification system in order to create the best user experience and spread out server charge.

All body metrics data types measured by Withings devices are available through the WBS API, in addition to other relevant user data. An exhaustive list of all data types available can be found in the present documentation, under the Service Catalogue section.

The WBS API is currently licensed for free. We invite you to review the Terms & Conditions page for more information before registering your service, website, application, etc. here. Do not hesitate to contact us if you have any question regarding this process under the category “Business inquiries → Partnership and API”.

We have developed sample code for various programming languages, please find them below.

You'll find a sample php code with small explanation here. It's using a lightweight Oauth library you can modify to get a full functionnal oauth client. You just have to follow the code in example.php file.

Authentication

An account is what Withings users use to log into their dashboard. An account is uniquely defined by an email address and a password, entered by the end user when registering. A single account may contain several users (e.g.: members of a family).

The WBS API connects third-party service with a user, but uses the account’s e-mail and password for authentication. An account must have at least one user in it in order to make the connection through the WBS API possible.

A user of a Withings device is uniquely defined by a userid and is tied to your application through their Oauth credentials. These parameters are mandatory in all requests and are given 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.
Eg: oauth_signature=yAF9SgZa09SPl3H1Y5aAoXgyauc

A complete WBSAPI request would be:

http://wbsapi.withings.net/measure?action=getmeas&oauth_consumer_key=7e563166232c6821742b4c277350494a455f392b353e5d49712a34762a&oauth_nonce=f22d74f2209ddf0c6558a47c02841fb1&oauth_signature=yAF9SgZa09SPl3H1Y5aAoXgyauc=&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1309783586&oauth_token=c68567f1760552958d713e92088db9f5c5189754dfe4e92068971f4e25d64&oauth_version=1.0&userid=1229

You can test your request here

OAuth Implementation Guide

Please check the dedicated page for Oauth authentication guidelines

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,
[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.

Responses codes

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.

Here the responses codes with their description :

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}

User

user / getbyuserid

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

This can be used to retrieve 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.

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

Measure

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.

       {
            "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
                            }
                        ]
                    }
                ]
            }
        }
                        

Notification

The most effective way for third parties to retrieve measurements updates is to setup Push notifications for the users who have linked their account with them. Notifications are handled on a user-per-user basis: each third party application need to subscribe once for every user being monitored, as explained here. Each time the subscribed users use their Withings device to take a new measurement, or manually add or modify any measurement or objective, the WBS API will send notifications to all their monitoring third parties.

Please note that a given user cannot be subscribed by more than 16 third party services.

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.

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.

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.

        {
            "status": 0
        }
                        

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.

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

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 device type.

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

                        

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.

        {
            "status": 0
        }
                        

What if I need more help?

If you encounter implementation issues, have questions or would like to submit new features request or bugs, We encourage you to e-mail us through this contact form under the category “Business inquiries → Partnership and API”.

PLEASE READ THESE TERMS OF USE AND CONDITIONS CAREFULLY BEFORE USING A WITHINGS API.

By accessing and using any Withings API you explicitly agree to comply with and be bound by the following terms and conditions. These terms of use cover the Withings Application Programming Interface (API).

1. Services. The Withings API is a Withings, Inc service that allows licensees to retrieve certain data regarding Withings users. Withings will announce new releases through the e-mail address provided by you.
2. Copyright and License. You are granted a worldwide, non-exclusive, non-sublicenseable and non-transferable license to the Withings API. This license is subject to the following restrictions:
   • You may not use the Withings API for any other purpose not expressly and unambiguously authorised by these Terms of Use, without Withings' prior written consent. All rights not expressly granted to You under these Terms of Use are reserved by Withings.
   • The Withings API allows you to access a user's personal data. You must always ensure that you have the express permission of a user to access their data and you will not attempt to access data for which you have not obtained adequate permission.
   • You may not use the Withings API in any manner or for any purpose that violates any law or regulation, any right of any person, including but not limited to intellectual property rights, rights of privacy, or rights of personality, or in any manner inconsistent with the Withings TOS or these Terms of Use;
   • You further agree not to otherwise reproduce, modify, distribute, decompile, disassemble or reverse engineer any portion of the Withings API or any data provided by Withings, Inc.
   • This API is currently provided free of charge. Withings Inc. reserves the right to, at a future date, charge for access to these APIs.
   • If you become aware that any user of your implementation is in material breach of this API Terms of Use then you agree to notify Withings, Inc. promptly of such breach by e-mail to contact-mkt@Withings.com and to take prompt commercially reasonable, corrective action at your expense to remedy such breach.
   • All calls to the Withings API must reference the API Key issued to you as an approved licensee. You agree to keep the API Key confidential, and not to share it with any third party. This license is personal to you, and any affiliates must seek and obtain their own license and API Key.
   • You may not sell, lease, share, transfer, or sublicense the Withings API or access codes thereto without Withings's prior, express, written permission;
   • Use of the API is subject to restrictions on rate limit, use types and method calls as outlined on the Withings developer portal. If Withings reasonably believes that you have exceeded your rate limits or have attempted to circumvent the rate limit or authentication systems, your ability to utilise the API may be temporarily suspended or permanently revoked. Withings may monitor your usage of the API in order to improve our service and to ensure compliance with our policies.
3. Indemnity. You agree to hold harmless and indemnify Withings, Inc., and its subsidiaries, affiliates, officers, agents, employees, and suppliers, from and against any third party claim arising from or in any way related to your or your users' use of the Withings API, violation of these API Terms of Use or other actions connected with use of Withings, Inc. services, including any liability or expense arising from all claims, losses, damages (actual and consequential), suits, judgments, litigation costs and attorneys' fees, of every kind and nature. In such a case, Withings, Inc. will provide you with written notice of such claim, suit or action.
4. WARRANTIES.
   THIS SITE, THE MATERIALS, DATA, AND THE SERVICES ARE PROVIDED ON AN "AS IS" BASIS WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED. YOU EXPRESSLY AGREE THAT USE OF THIS SITE, INCLUDING ALL CONTENT OR DATA DISTRIBUTED BY, DOWNLOADED OR ACCESSED FROM OR THROUGH THIS SERVICE, IS AT YOUR SOLE RISK. WE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT AS TO THE INFORMATION, MATERIALS, AND CONTENT ON THE SITE. WE DO NOT REPRESENT OR WARRANT THAT MATERIALS IN THIS SITE ARE ACCURATE, COMPLETE, RELIABLE, CURRENT, OR ERROR-FREE. WE ARE NOT RESPONSIBLE FOR TYPOGRAPHICAL ERRORS OR OMISSIONS RELATING TO PRICING, TEXT OR PHOTOGRAPHY.
5. LIABILITY LIMITATION.
   IN NO EVENT SHALL WITHINGS, ITS OFFICERS, DIRECTORS, AGENTS, AFFILIATES, EMPLOYEES, ADVERTISERS, OR DATA PROVIDERS BE LIABLE FOR ANY INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL OR PUNITIVE DAMAGES (INCLUDING BUT NOT LIMITED TO LOSS OF USE, LOSS OF PROFITS, OR LOSS OF DATA) WHETHER IN AN ACTION IN CONTRACT, TORT (INCLUDING BUT NOT LIMITED TO NEGLIGENCE), EQUITY OR OTHERWISE, ARISING OUT OF OR IN ANY WAY CONNECTED WITH THE USE OF THE WITHINGS API SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY SO THE ABOVE LIMITATIONS MAY NOT APPLY TO YOU.

6. a. Intellectual Property. The Withings API and Withings Brand are the property of Withings, Inc., and subject to the intellectual property rights of Withings, Inc. (c) 2008 Withings, Inc.. All rights reserved.

   b. You will not attempt or encourage others to:

   • Re-sell, re-license or syndicate access to the API to third parties in a way that bypasses said third parties requirements to register with Withings for API access;
   • Perform wholesale export of Withings Data for the purpose of account migration or service duplication;
   • Use data scraping, data harvesting, web crawlers, or other data extraction methods to extract data from Withings, the Withings API, the Withings Platform or Withings' databases;
   • Use or access the API for the purpose of monitoring the performance or functionality of the Withings Platform or for any other benchmarking or competitive purposes;
   • Include functionality that proxies, requests or collects Withings Users' passwords.
   • If you are unsure whether your intended use of the API is in compliance with these Terms of Service, please contact us.

7. Miscellaneous.
   Entire Agreement; Amendment. This Agreement contains the entire agreement of the parties with respect to the transaction described in this Agreement, and no prior or simultaneous oral or other written representations or promises shall be a part of this Agreement or otherwise effective. This Agreement may not be amended or released, in whole or in part, except by a document signed by both parties.

   Severability. If any provision of this Agreement is held to be unenforceable, the remaining provisions shall be unaffected and shall be construed to the maximum extent possible so as to give effect to the intent of the parties. Each provision of this Agreement is severable from and independent of any other provision. Further, in the event that any remedy hereunder is determined to have failed of its essential purpose, all limitations of liabilities and exclusions of damages shall remain in effect.

8. Modification. Withings, Inc. may change, add to or delete these Terms of Use or any portion thereof from time to time at its sole discretion. You are responsible for monitoring these changes and complying with the most recent Terms of Use.
9. Relationship Formed. The relationship formed between You and Withings shall in no event be construed such that either party is an agent, representative, employee, partner, or joint venturer of the other party.
10. Term & Termination. Withings may change, suspend or discontinue the API service at any time for any reason, with a 30 days' notice. We reserve the right, with a 30 days' notice, and in our sole discretion, to terminate your license to use the Withings API, and to block or prevent future access to and use of the API. Upon any termination of these Terms of Use, You shall promptly delete and remove all calls to the Withings API from all web pages, scripts, widgets, applications, and other software or hardware in your possession or under your control.
11. General. You represent that you have the authority to bind the organisation (if any) identified in your application for the Withings API. You agree not to export from anywhere any part of the Withings API provided to you or any direct product thereof except in compliance with, and with all licenses and approvals required under, applicable export laws, rules and regulations. If any part of these API Terms of Use is determined to be invalid or unenforceable, then the invalid or unenforceable provision will be replaced with a valid, enforceable provision that most closely matches the intent of the original provision and the remainder of these API Terms of Use will continue in effect. Except as expressly stated herein, these API Terms of Use constitute the entire agreement between you and Withings, Inc. with respect to the Services and supersede all prior or contemporaneous communications of any kind between you and Withings, Inc. with respect to the Withings API.

1. You may establish a link to the Withings website (www.withings.com), provided that the link does not state or imply that Withings sponsors or endorses any other web site, or presents Withings in a false, misleading, defamatory or derogatory manner. This permission to link to the Withings website does not permit you to use any Withings materials or content, unless separately agreed to in this Agreement or some other agreement with Withings.

2. You may not use "Withings" or any variation thereof in the name of your Developer Applications. You may not use "Withings" or any variation thereof in any domain name, email address, keyword or social media user name.

3. You may make truthful, factual references to Withings in plain-text prose descriptions of your Developer Applications' features and benefits (including references to a Developer Application's interoperability with Withings). For example, the Withings trademark can be used in the manner shown in one of the referential descriptions below:

• "Designed for use with Withings devices"
• "For use with the Withings [insert particular feature/product name]"
• "Synchs with the Withings [insert particular feature/product name]"
• "Designed to interact with Withings devices"

These phrases can appear near, but must be completely separate and apart from the name/logo of the Developer Application. The font size of phrases using the Withings mark should not be larger than the surrounding font, and should not appear more prominently than the name/logo of the Developer Application.

4. In all materials that contain an approved phrase as set out above, including product packaging, the following legend must also be placed in the "fine print" of such materials. The legend may be in a small type size, but must still be legible: "Withings is a registered trademark and service mark of Withings, Inc. [Insert name of the Developer Application] is designed for use with the Withings platform. This product is not put out by Withings, and Withings does not service or warrant the functionality of this product."

5. You acknowledge and agree that this Agreement does not include the right to use any Withings logo (each a "Withings Logo" and together the "Withings Logos") as part of any brand for the Developer Applications themselves, or as part of any brand(s) or trade name(s) or other designators for your business or non-tested products. The Withings Logo may be used only in the size and format made available to you through Withings' Developer Centre to label or designate data records fetched from the Withings Platform. You may not use the Withings Logos in any other manner, including but not limited to use on promotional materials, standalone technical support or consulting services, or other goods or services without Withings' explicit written permission.