Documentation

Android App

Android App User Guide is available here.

Python API Documentation

If you use python you can use the API available here.

JAVA API Documentation

Coming soon.

REST API Documentation (All languages)

The following documentation describes the REST API to be used as reference for all programming languages. Example are provided in JSON, however, XML is also supported.

Watch a short video introduction to API usage:

 

REST API Usage Example

Login

The login operation must be used in order to get a valid token (required to perform any read/write operation on users’ data). The acquired token will allow to perform any read/write operation for that specific user, except for users with administrative privileges that will be able to perform operation on all users within the same scope.

If the operation is successful returns 200 OK.

e.g. POST {entrypoint}/auth/login
Request Headers:

Content-Type: application/x-www-form-urlencoded
Accept: application/json

Body example:

username=a_username&password=a_password

Example response headers:

Authorized-By: 323804057
Content-Type: application/json
Date: Wed, 22 Nov 2017 16:14:20 GMT
Expires: 2017-11-22T17:14:20.465+0000
Server: Apache-Coyote/1.1

The header “Authorized-By” contains the token to be used for following requests. The header field “Expires” indicates expiration time for the token.

Example response body:

{
"personalData": {
"firstName": "Demo",
"lastName": "Selfman",
"userName": "uuselfmanuser@email.com",
"dateOfBirth": null,
"id": 123456789
}

The id field in the body can be used to operations on that specific user.

Retrieving Data

Data requests must be performed using a valid userId and token.

If the operation is successful returns 200 OK.
e.g.: POST {entrypoint}/users/123456789/events/example

A valid token must be specified in the request using the Authorized-By header field. Read operations require the client to specify the preferred encoding format (i.e. application/json OR application/xml) using the Accept. The API requires the client to perform all data read requests using an example that must be contained in the body of the request. The client must also specify the format of the request body using the Content-type header field, xml or json.

Request Headers Example:

Authorized-By: 323804057
Content-Type: application/json
Accept: application/json

Body example:

{
"type": "WITHINGS.BODY",
"label": "Heart Pulse",
"startTime":"2017-11-18T00:00:00.000+0000",
"endTime":"2017-11-25T23:59:59.999+0000"
}

The example to be used in the request body has the same structure of an event containing data. The query by example method provides a flexible way to perform complex query. Events structure fields can be used to restrict the scope of the query. Time interval of the request can be modified using startTime and endTime that must be formatted as string the standard ISO-8601 date format (YYYY–MM-DDThh:mm:ss.fff+zzzz where fff is in milliseconds and zzzz is hours and minute timezone difference from UTC). The type and label field can be used to further restrict the scope of the query. In the example type=”WITHINGS.BODY” and label=”Heart Pulse” will retrieve only Heart Pulse measurement from the Withings device in the specified time frame. Omitting the label in the request body example would retrieve all Withings Body measurement (i.e. including “Weight”, “SPO2” etc.).

Other example queries could be type=”WITHINGS.ACTIVITY” that allows to specify steps, distance, elevation and calories as accepted values for label.

Example of a response body of data:

{
    "startTime": "2017-11-09T00:00:00.000+0000",
    "endTime": "2017-11-09T00:00:00.000+0000",
    "label": "elevation",
    "type": "WITHINGS.ACTIVITY",
    "attributes": {
        "entry": [
            {
                "key": "elevation",
                "value": {
                    "value": "56.51",
                    "descriptor": "m"
                }
            }
        ]
}

Numerical values of the measurement are stored as event attributes containing a tuple (key, value, descriptor) where:

• the key indicates the type of measurement,
• value contains the measurement value,
• and the descriptor field is used to represent the unit of measurement for Withings data

Similarly, type=”RAW_DATA” allows to retrieve raw data from the smartphone sensors with ACC, GYRO and GPS as accepted values for label to retrieve accelerometer, gyroscope and GPS data respectively.

Example of response body containing RAW_DATA:

{
    "events": [
        {
            "startTime": "2017-11-24T19:12:38.095+0000",
            "endTime": "2017-11-24T19:13:38.111+0000",
            "label": "ACC",
            "type": "RAW_DATA",
            "data": "MS41MjYxLDAuNDA3Miw5LjM4MDM7MS41MjI0LDAuNDEwOSw5LjM2NjU7MS41MTY1LDAuNDAxOSw5LjM1MTY7MS41MzA5LDAuNDIwNSw5LjM0Nzk7MS41MTc2LDAuNDA3Miw5LjM2NjU7MS41MjE0LDAuNDEwOSw5LjM3NjY7MS41MjcxLDAuNDE2Nyw5LjM3MDg7MS41MTI3LDAuNDIwNSw5LjM2NjU7MS41MzE0LDAuNDAxOSw5LjM2NjU7MS41MzE0LDAuNDAxOSw5LjM2NjU7MS41MzE0LDAuNDE2Nyw5LjM1MTc7MS41MzA3LDAuNDAxOSw5LjM2NjU7MS41MTIzLDAuNDAxOSw5LjM2NjU7MS41MTIzLDAuNDIyMiw5LjM3Njc7MS41MjcxLDAuNDI1Myw5LjM1NjA7MS41MzE0LDAuNDIxMCw5LjM0ODU7MS41MjYyLDAuNDIxMCw5LjM5NDQ7MS41MjIyLDAuNDExMCw5LjM3NjU7MS41MzE0LDAuNDAxOSw5LjM3MDk7MS41MTIzLDAuNDAyMiw5LjM2NjU7MS41MTIzLDAuNDE1OSw5LjM2NjU7MS41MTIzLDAuNDAxOSw5LjM2NjU7MS41MjcwLDAuNDAxOSw5LjM2NjU7MS41MzExLDAuNDIxMCw5LjM2NjU7MS41MTIzLDAuNDE1OSw5LjM3MTY7MS41MTIzLDAuNDExNyw5LjM3NTg7MS41MjY5LDAuNDA2NCw5LjM4MTE7MS41MzE0LDAuNDAxOSw5LjM2NjU7MS41MzE0LDAuNDAxOSw5LjM2NjU7MS41MjE3LDAuNDExNiw5LjM2NjU7MS41MjY5LDAuNDIxMCw5LjM2NjU7MS41MzE0LDAuNDIwOCw5LjM2NjM7MS41MzE0LDAuNDAxOSw5LjM1MjM7MS41NDEyLDAuNDExNiw5LjM2NjU7MS41MzYwLDAuNDIxMCw5LjM2NjU7MS41MzE0LDAuNDIxMCw5LjM4NTU7MS41MjYyLDAuNDE1OCw5LjM2MTM7MS41MjE5LDAuNDExNSw5LjM1NzA7MS41MTY1LDAuNDIxMCw5LjM4MTQ7MS41MzE0LDAuNDAxOSw5LjM2NjU7MS41MjY2LDAuNDIxMCw5LjM3MTQ7MS41MTIzLDAuNDIxMCw5LjM3NjA7MS41MjY2LDAuNDA2Niw5LjM4MDk7MS41NTAyLDAuNDIwNyw5LjM2Njg7MS41MTcxLDAuNDA2Nyw5LjM3NjA7MS41MzE0LDAuNDIxMCw5LjM0NzM7MS41MzE0LDAuNDIxMCw5LjM2MTc7MS41MzE0LDAuNDIxMCw5LjM2NjU7MS41NDExLDAuNDAxOSw5LjM1MjE7MS41MjE4LDAuNDAxOSw5LjM1Njk7MS41MzE0LDAuNDAxOSw5LjM2MTc7MS41NTA1LDAuNDIwOSw5LjM4NTY7MS41MzYxLDAuNDAxOSw5LjM3MTI7MS41NDExLDAuNDAxOSw5LjM3NjI7MS41MzE0LDAuNDE2MSw5LjM2NjU7MS41MTI0LDAuNDIxMCw5LjM2NjU7MS41NDEzLDAuNDE2NCw5LjM2NjU7MS41MjE3LDAuNDExMyw5LjM3NTk7MS41MzE0LDAuNDA2Nyw5LjM4NTY7MS41MTI1LDAuNDIwOCw5",
            "id": 3861151436014238
        }
    ]
}

In case of RAW_DATA from inertial sensors (accelerometer and gyroscope) sensor readings are stored in the data field as byte[] using base64 encoding. Using a base64 decoder it is possible to reconstruct the data string containing the samples in CSV format (X,Y,Z,s;) where ‘;’ is used as delimiter for rows. Each row contains values separated by ‘,’ delimiter and contains respectively the 3D sample (X,Y,Z) followed by an integer indicating the relative time from the event start time in seconds.

Note: raw data requests typically  involve large amount of data to be sent. As rule of thumb, it is preferable to limit the request to time intervals lower than 30 minutes.  For larger request see the following section. (see ‘Things to avoid’ section at the bottom)

Making large raw data queries

Raw data queries for large time interval should be performed as multiple queries. The API provides also a utiliy service to facilitate queries of raw data over large time spans. The service idbyexample will provide a concise list of events id and the overall number of data events in the specified time interval. The querying method for this service is the same as for the query by example, but on a different URI.

POST - {entrypoint}/users/123456789/events/idbyexample

Example response:

{
    "eventsID": [
        {
            "id": "4080507038353592"
        },
        {
            "id": "4080507050163630"
        },
        {
            "id": "4080507059318841"
        },
        {
            "id": "4081452278445201"
        }
    ],
    "count": "4"
}

The list of ids contained in the response can be used to access events complete raw data.

e.g. GET - {entrypoint}/users/123456789/events/4080507038353592/

Retrieving data labels

Data annotations (data labels) are stored in form of events. A special type is used to identify annotations and can be used to retrieve annotation information as for the case of raw data. The service entry point for data retrieval is therefore the same as the one used to retrieve raw data:

e.g.: POST {entrypoint}/users/123456789/events/example

To retrieve the annotations the type “LABEL” must be used in the request body e.g.:

{ "type": "LABEL",  
"startTime":"2017-11-18T00:00:00.000+0000", 
"endTime":"2017-11-25T23:59:59.999+0000" }

The query on labels can also be restricted to one of the specific labels: ‘SITTING’, ‘STANDING’, ‘WALKING’, ‘RUNNING’, ‘CYCLING’, ‘WORKOUT’, ‘STAIRS_UP’,’STAIRS_DOWN’,’SLEEPING’,’TRANSPORTATION’, plus other five labels customizable through the app.

e.g. the following request body will retrieve only time intervals labeled as ‘WALKING’:

{ "type": "LABEL", 
  "label":"WALKING",
  "startTime":"2017-11-18T00:00:00.000+0000", 
  "endTime":"2017-11-25T23:59:59.999+0000" }

Retrieving Calendar Events

All events added through default Android calendar application will be automatically retrieved and sent to the server. Calendar events can be retrieved in form of events using the  same entrypoint:

e.g.: POST {entrypoint}/users/123456789/events/example

Using the type CALENDAR in the request body:

{ "type": "CALENDAR", 
  "startTime":"2017-11-18T00:00:00.000+0000", 
  "endTime":"2017-11-25T23:59:59.999+0000" }

Getting List of users

Access to this service is restricted to administrators users only. Other users can access only their own data.

To get data from all or some other users first you need to retrieve the list of users currently registered on the system. Then it will be possible retrieve data from all users iterating on the list of retrieved users’ ids.

The service providing access to the list of users is:

POST - {entrypoint}/users/useridsandpds2

The service will return the list of user n the response body as in the example below:

{
    "users": [
        {
            "id": "8959744230846",
            "userName": "adminUsername",
            "firstName": "Admin",
            "lastName": "Admin"
        },
        {
            "id": "7291901979847",
            "userName": "username1@email.com",
            "firstName": "user1",
            "lastName": "lastname1"
        },
        {
            "id": "86454267573203",
            "userName": "username2@email.com",
            "firstName": "user2",
            "lastName": "lastname2"
        }
    ],
    "count": "3"
}

Things to avoid

Specially when dealing with RAW DATA you should avoid making direct queries using the example service, unless you specify in the request a reasonable time interval that will not attempt to load too much data. Too large queries can lock the server side that will not be able to serve subsequent requests. In that case you will need to restart tomcat server. Always use the idbyexample service for large queries and then iterate on the list of events ID doing GET operations to download the data.

Similarly, DO NOT USE the users entrypoint to get the list of users. Use the users/useridsandpds2 service instead.

 

Complete REST Documentation

Complete API documentation is available here.