Elcies logo

Health Data Aggregator - ELCIES

ELCIES

Organize health and fitness data from dozens of apps into one interface

Collects and shows data per user

  • Data

API reference on SwaggerHub

Introduction

The Health Data Aggregator API links data from digital health wearables, devices and apps. This allows you to personalize your fitness, health and lifestyle services to individual users. Also, you can build your own intervention and prevention campaigns based on health and physical activity data. Examples of such data are steps, calorie consumption, weight, heart rate, sleep quality, blood pressure and glucose level.

Conceptual model

Conceptual model

Definitions

Tile

A tile represents a specific bit of data related to fitness, health or lifestyle. For instance, the activity tile represents a daily activity summary such as walking, running etc. Or data such calculated BMI, sleep log and body temperature.

API workflow

Sequence diagram

Features

  • Create spaces for your application
  • Add users to connect their devices to the application
  • Check information related to those users

Getting started

Authentication

To authenticate you'll need to request an access token. Use your API Store app's credentials (Consumer Key and Consumer Secret) to make an authentication request. The authorization service returns a JSON message that contains the access_token field.

Use one of the following 3 options:

cURL

Execute below cURL command to receive an access token. Replace APP_CONSUMER_KEY and APP_CONSUMER_SECRET with your app's credentials.

curl -X POST \
 'https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials' \
 -H 'content-type: application/x-www-form-urlencoded' \
 -d 'client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET'

If you are using cURL for Windows, please use the command below instead.

curl -X POST "https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials" -H "content-type: application/x-www-form-urlencoded" -d "client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET"

The authentication service returns a JSON message that contains the access token field.

{
    "refresh_token_expires_in": "0",
    "api_product_list": "[xxxxxxx]",
    "api_product_list_json": [
        " xxxxxxx"
    ],
    "organization_name": "kpn",
    "developer_email": "demo123@kpn.com",
    "token_type": "Bearer",
    "issued_at": "1521039195424",
    "client_id": "APP_CONSUMER_KEY",
    "access_token": "haf2SDl07E9N7RluNQ4kJ1TkGgso",
    "application_name": "6e38edxxxxxxxxxxxxxxxx4065d79c",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

SwaggerHub

  1. Click on the Authorize button on the top right.
  2. In the form, fill in client_id and client_secret, using your app's credentials.
  3. Click Authorize.

Postman

When using Postman, you will have to import the Swagger file into a Postman collection as follows:

  1. Open the API reference on SwaggerHub.
  2. On the top right, click Export, click Download API and click 'YAML Unresolved'.
  3. In Postman from the menu click File and click Import... Choose the YAML file you downloaded in the previous step. A new collection will be added.
  4. Select Get Access Token from the collection.
  5. Make sure the right environment is selected, corresponding to the API.
  6. Edit the environment variables client_id and client_secret, using your app's credentials.
  7. Check the response code and message.
  8. Press the Send button to get an access token.

Note: Request variables are no longer linked to an environment, but to the collection.

How to...

Register user

Create a new user by providing an identifier that is appropriate for you. In the response to this request, you'll find a callbackurl returned. Use this URL to configure your device, to make the device send data to to Health Data Aggregator platform.

SwaggerHub:

  1. Create user with GET /connectedservice.
  2. Click Try it out.
  3. Supply ExternalUserId which is the ID of user.
  4. Click Execute.
  5. Check the response code and message. Use the callbackurl from the response in your application to connect with a device.

Postman:

  1. Create user with (GET) connectedservice.
  2. Supply ExternalUserId which is the ID of user.
  3. Click Send.
  4. Check the response code and message.

List user

Get a list of all created users.

SwaggerHub:

  1. List user with GET /userlist.
  2. Click Try it out.
  3. Click Execute.
  4. Check the response code and message.

Postman:

  1. List users with (GET) User.
  2. Click Send.
  3. Check the response code and message.

Update CallbackURL

Use this request to setup a CallbackURL that is used by the platform to send all incoming data to. In this way you can relay the data to another party of your choice.

SwaggerHub:

  1. Update URL with GET /updateCallbackUrl.
  2. Click Try it out.
  3. Enter a value for url.
  4. Click Execute.
  5. Check the response code and message.

Postman:

  1. Update URL with (GET) updateCallbackUrl.
  2. Enter a value for url.
  3. Click Send.
  4. Check the response code and message.

Get tile detail

After the instructions, all the different tiles of information are listed.

SwaggerHub:

  1. Get tile detail with GET /tiledetail.
  2. Click Try it out.
  3. Fill out Param with userID, tilename and date.
  4. Click Execute.
  5. Check the response code and message.

Postman:

  1. Get tile detail with (GET).
  2. Fill out request queryparam userId, tilename and date.
  3. Click Send.
  4. Check the response code and message.
Code    Description
activitytile    Get daily activity summary (e.g. 'walking', 'running' - 'distance' only included when relevant)
caloriestile    The number of calories burned during the day for periods of time when the user was active
bmitile    Calculated BMI
bodywatertile    Track body water percentage
bonemasstile    Track bone mass percentage
musclemasstile    Track muscle mass percentage
sleeptypetile    The last measured sleep log entries for a given date range (including start and end dates)
bodytemperaturetile    Collects body temperature within seconds
bloodglucosetile    The last entries blood glucose
stepstile    The last measured steps
sleeptile    The last measured sleep log
cholesterolprofiletile    The last measured cholesterol
bloodpressuretile    The last measured blood pressure
weighttile    The last measured weight
heighttile    The last measured height
heartratetile    A heart rate monitor (HRM) measures the rate of a person's heartbeat
peaktile    Peak
cardiotile    Cardio information
fatburntile    Fat burn zone, which means your heart rate is 50 to 69% of maximum
calories_consumedtile    Calories consumed
carbs_consumedtile    Carbs consumed
fat_consumedtile    Fat consumed
protein_consumedtile    Protein consumed
sodium_consumedtile    Sodium consumed
sugar_consumedtile    Sugar consumed
iron_consumedtile    Iron consumed
calcium_consumedtile    Calcium consumed
vit_atile   Vitamin A
vit_ctile    Vitamin C
potasstile    The value of consumed potassium
choltile    The value of consumed cholesterol
trn_fattile    The value of consumed trans fat
mon_fattile    The value of consumed monounsaturated fat
ply_fattile    The value of consumed polyunsaturated fat
sat_fattile    The value of consumed saturated fat
water_consumedtile    The value of consumed water

Return codes

Code   Description
200   Success
201   Created
202   Accepted
302   Found. Link in location header
400   Bad request
401   Unauthorized
403   Forbidden
404   Not found
405   Method not allowed
412   Precondition failed
429   Too many requests
500   Internal server error
502   Bad gateway
503   Service unavailable