Terra Connect: Navigating Wearable Data Integration with Python

What is Terra?

Terra offers a streamlined and efficient solution for integrating your application with the wearable data of your users. This platform enables the aggregation of data from various wearable devices available on Terra, including but not limited to Fitbit, Biostrap, Aktiia, and Apple Health. This broad compatibility ensures comprehensive data collection, enhancing the overall user experience and accessibility to health-related information.

How to Start with Terra?

At the end of this guide, you will authenticate a user and set up a Webhook to receive new data when it becomes available from that user’s wearable. The steps are:

✅ Obtain developer credentials from the dashboard.
✅ Authenticate a user using the Terra Connect Widget.
✅ Set up a Webhook endpoint where you can receive data.
✅ Configure Terra to send data to the endpoint.
✅ Receive data at the endpoint.

Explore the details of Terra’s integration services and discover a realm of possibilities by visiting our dedicated Terra Integration Service page. Enhance your application’s capabilities and tap into the potential of wearable data like never before!

Obtain dev-id and API Key

Head to the Terra dashboard. Under Connections, you will find your API Key and Dev ID in the bottom right corner of the API Credentials Popup. They are used in virtually every interaction with the API – keep them safe!

Fig.1.1 Source: Terra Dashboard

Generate Terra Connect Widget Session

The Terra Connect Widget serves as a user-friendly and efficient method for user authentication. This widget provides a seamless and convenient way to verify a user’s identity, enhancing the authentication process with its user-centric design and functionality.

url = "https://api.tryterra.co/v2/auth/generateWidgetSession"

payload = {
"reference_id": request.data['reference_id'],
"providers": "WITHINGS,OMRON",
"language": "en"
}
headers = {
"accept": "application/json",
"dev-id": os.getenv("TERRA_DEV_ID"),
"content-type": "application/json",
"x-api-key": os.getenv("TERRA_API_KEY")
}
response = requests.post(url, json=payload, headers=headers)
response.raise_for_status()
url = response.json()["url"]

Here “TERRA_DEV_ID”, is a developer id and “TERRA_API_KEY” is a secret key that we get from the Terra dashboard.

“Refernce_id” is something that we use for our reference which we can store in our DB for a better understanding of the data.

From the above code, we get the “Wedgit Session URL” from which we have to log user creds to the provider account to request live data.

Setup a Webhook

Terra effortlessly delivers the latest data to your designated Webhook as soon as it becomes accessible from the wearables of your users. This automatic data transmission ensures a timely and efficient flow of information, keeping your system updated with real-time insights from the user’s wearable devices.

For testing purposes, the easiest way to set up a Webhook endpoint is using an online provider Webhook.site.

Or you can use the normal get API URL from your project but that URL needs to be hosted on the server.

Configure Webhook

Once you’ve established your Webhook endpoint URL, navigate to the Terra dashboard. In the Connections section, seamlessly integrate the Webhook as a destination. Opt for “Add credentials” from the additional options dropdown, and paste your Webhook URL into the designated Webhook Host field. From this point forward, Terra will efficiently route all Webhook messages directly to the specified URL.

You can also find your webhook secret which will be sent with every payload, so you can verify that you are getting data from Terra.

Test the Webhook

Congratulations! You’ve effectively configured a Webhook endpoint.

You will now receive new data at your Webhook when it becomes available.

If you don’t have a tangible wearable device for testing, you can simulate Webhook updates using the Data Generator. Navigate to the dashboard, go to Tools > Generate, click the Generate Test Data button, and subsequently select Send to Webhook. This allows you to simulate and test Webhook functionality without the need for a physical wearable.

This is how we can collect the data from Terra with live Webhook.