July 21, 2016

How to integrate multiple Wellness devices using Human API

In a recent project for one of our clients, we came across a need to gather data from multiple wellness devices. We were faced with a choice between creating a custom connector for each device’s API, or using a service that gathers data in one place.

One possible solution was Human API (http://www.humanapi.co/) who stated that they provide an easy way to get data from multiple health systems and wearable devices (like Fitbit, Misfit etc.). Another one we found interesting (especially for enterprise solutions) would be Validic (https://validic.com/). We will not refer to it in this article, but it may be a focus of a separate article in the future.

In the end of this blog post, we made our conclusions regarding whether it’s cheaper to build and maintain a custom solution or to use Human API or a similar tool. For that purpose, we made a simple demo app to discover how easy (or hard) Human API integration is.

Vicert Dashboard Demo Application

The idea for our demo application is to retrieve user data from multiple wearable devices using Human API and display it using various charts. It shows the following info:

  • Today’s progress – current calories burn, activity (walking, running, cycling etc.) distance and activity duration compared to the user-set goals
  • Summary of calories burned, activity distance and activity duration for last 5 days
  • A list of recent activities
  • Calories burned for the last month


We exposed an API using a Node.js application, which connects to Human API and returns data to the client.

The client is an Angular application, where we utilized a JavaScript library HumanConnect, which is provided by Human API.

Authentication using HumanConnect

In order to allow Human API to collect user data, the user has to connect his/her account with Human API. This process is repeated for every service the user wants to connect.

The authentication process is done in six steps visualized in the image below (image source: http://hub.humanapi.co/docs/overview-of-human-connect):

  1. Angular application sends clientId (an ID received when you register your application with HumanAPI) and userId (an ID used to identify a user in our application) to user.humanapi.co service.
  2. HumanAPI responds with a sessionTokenObject.
  3. Angular application sends the sessionTokenObject to our Node.js server.
  4. Node.js server sends the sessionTokenObject along with the clientSecret (also received when you register your application with HumanAPI)
  5. HumanAPI server responds with humanId, accessToken and publicToken. This data is stored in the application database for future use.
  6. Node.js server responds to the Angular application in order to notify that the process is finished.


Angular implementation of the Authentication process

Human API provides a widget for this purpose which you can embed into your Web or Mobile application.

First we add HumanConnect library to our application as a Bower (http://bower.io/) dependency:


We then create a factory in order to inject human connect where needed:


In the HTML template, we have a button which opens a HumanAPI connect popup


And in our Angular controller function openHumanConnect() calls the function open of the HumanConnect library, which initiates the authentication process.


Provided options object contains the following properties:

  • clientUserId – an ID used to identify a user in our application
  • clientId – an ID received when you register your application with HumanAPI
  • publicToken – empty if connecting the user for the first time, otherwise a token received from HumanAPI during authentication (step 5).
  • finish – callback function called when a response is received from HumanAPI (step 2)

Here is the implementation of the finish function:


We are posting the sessionTokenObject to our Node.js server (step 3), and we save the received public token object in the browser’s local storage (step 6).

Node.js implementation of the Authentication process

On the server side we implemented a function that handles “/human/connect” route called from the Angular application:


It calls our connect function which sends the sessionTokenObject to the Human API (step 4), and returns the received public token to the Angular application (step 6) once the request to Human API is completed.

Below is the implementation of the connect function:


As seen above, our server application sends the sessionTokenObject received from the client to Human API (step 4), and receives (step 5) the accessToken, publicToken and humanId, which are stored in our database, so that we can later access user’s data.


With everything set-up, a click on Connect Health Data button opens a full screen overlay where user can connect/disconnect an external source.


Choosing a new source sends the user to authenticate with the appropriate service and allow HumanAPI to access his/her data, through a standard OAuth or similar authentication process.

Retrieving Data

Finally, we need to fetch some data from Human API. This is pretty much straight-forward – all we need to do is to hit some of the available API endpoints providing the accessToken we have received above.

Below is an example of how to fetch a list of activities, using Node.js server:


It is also possible to provide an additional query for each request, e.g. start and end date, the number of activities being returned etc. Everything is well documented on the Human API developer hub.

Further Improvements And Optimization

In a production application, you will probably want to store user-data on your own server, and to make updates when required.

Human API provides a notification mechanism which notifies your server (via an exposed endpoint) that there is new data to be pulled from the server.

There is also a concept of batch queries which retrieves data for all your users for a specified time period. It can be executed in regular intervals to keep the data in sync.

It took us less than two days to completely set-up authentication and basic data pulling from Human API. From a developer’s perspective it was straight forward and worth the effort.

Taken into account the estimated number of users, required connections, and developer hours required for implementing and maintaining connections to required APIs, vs implementing only one API source it really makes a lot of sense to use Human API as the middle layer integration. In the past, Human API pricing was different (per instance), so for some solutions, it scaled pretty fast, however they updated the pricing in the meantime making it really affordable! If you are interested in building something like this, feel free to reach out!

Author: Tech Team
Like this article? Share it!