< Blogs
Elliott

Elliott

May 11, 2022

Data Flow: How to get data with Terra

Terra operates mainly in the form of Webhooks and REST API requests to provide you as a developer with data. Let us explore how this works. Whenever a new activity is generated, you receive it via wehbooks. In case you want to access an older activity, you can request it via HTTP.

Before we begin, you must sign up with Terra and have an active subscription with us before you can get data: https://dashboard.tryterra.co

Authentication

The first step in any form of getting data is to get the user's consent. For us, this is easily done through our /authenticateUser endpoint. You pass us the resource you wish to authenticate a user for (for example /authenticateUser?resource=fitbit) and we provide you with a unique user identifier along with an authentication_url that you redirect the user to for authentication.

We recommend mapping the unique user_id we provide to you in this process with an internal id that you use to identify users. This is because we will always send this along with every payload and thus it will help you identify who the payload is for.

At the end of this process, we will tell you if the user gave us consent to their data or not! This is either by webhook or by redirecting to an authentication failure URL.

Getting Data

Thats it! You can now get data by simply having a server running that has an endpoint which accepts POST requests, aka the webhook URL you set on our dashboard. We will push data to your webhook for that user either whenever it is available, or after a set interval period (the webhook intervals in the dashboard) has passed.

Our payloads to your webhook adhere to a strict standard:

  • There will always be a terra-signature field in the headers of the request so that you can verify it is us who sent it
  • The payload content will follow the same format whenever it comes in
{
    user: , //metadata of the user for this payload
    data: Array<>, //Array of Data in JSON format
    type: String, //The type of data this payload is for, i.e daily
}
  • The data we send are always the same style following our models

The Rest API part

If you ever wish to get historic data for a user, this is where the Rest API comes in.

We provide you with 7 different datatype endpoints: activity, body, athlete, daily, sleep, nutrition and menstruation for you to get historic data from. For example if you wish to get daily data from a month ago by user 12345, you simply have to hit our daily endpoint as such:

curl --location --request GET 'https://api.tryterra.co/v2/daily?end_date=2022-05-01&start_date=2022-04-01&user_id=12345' \
--header 'dev-id: ' \
--header 'X-API-Key: '

You can also:

  • Customise the dates (we also accept UNIX timestamps!)
  • Choose which endpoint to hit
  • Request for a different user
  • Choose to send this data to your webhook or not by adding a query parameter: to_webhook as true or false .

Special Providers

A few of our providers namely Apple Health and Samsung Health requires a full commitment on an application on the device itself. We currently have two main SDKs: TerraiOS and TerraAndroid.

Within these SDK's there are very simple-to-use functions for requesting permission and for requesting data from the user's device. In your backend, the data coming in will still adhere to our strict standard.

What happens next?

This is all there is to getting data from Terra! It is that simple.

However, what happens now that you've received a giant JSON payload of data to your webhook?

Go and build what you want with it! For anyone trying to build a simple app for displaying and monitoring health data, parsing the JSON payload into an internal data model might help. For anyone looking to train machine learning algorithms, parsing it and storing it in separate files to divide train/test set might be a good start. The possibilities are endless!

More Topics

All Blogs
Team Spotlight
Startup Spotlight
How To
Blog
Podcast
Product Updates
Wearables
See All >
Strava Pulls the Plug on their API: What This Means for Developers

Strava Pulls the Plug on their API: What This Means for Developers

Strava discontinued their API service, changing the ecosystem of third-party apps that have relied on their platform. How can developers react to this?

Terra APITerra API
November 21, 2024
Alternatives to the latest changes in the Strava API

Alternatives to the latest changes in the Strava API

Strava just introduced big changes to their API program. These changes will basically kill off a lot of apps. Use Terra API instead to avoid this

Kyriakos EleftheriouKyriakos Eleftheriou
November 19, 2024
Cycling Legend, Investor, and Podcaster - Lance Armstrong

Cycling Legend, Investor, and Podcaster - Lance Armstrong

In this podcast, Kyriakos the CEO of Terra interviews Lance Armstrong about his journey as a young athlete, cycling champion, and successful investor and podcaster.

Terra APITerra API
November 8, 2024
Founder of Donโ€™t Die - Bryan Johnson

Founder of Donโ€™t Die - Bryan Johnson

In this podcast, Bryan Johnson shares his personal story of how he began his journey to becoming the the world's most measured human.

Terra APITerra API
October 25, 2024
CEO and Co-Founder of Veri - Anttoni Aniebonam

CEO and Co-Founder of Veri - Anttoni Aniebonam

In this podcast with Kyriakos the CEO of Terra, Anttoni Aniebonam shares his journey founding Veri, and his decision in the acquisition by Oura to further his vision.

Terra APITerra API
September 27, 2024
next ventures
pioneer fund
samsung next
y combinator
general catalyst

Cookie Preferences

Essential CookiesAlways On
Advertisement Cookies
Analytics Cookies

Crunch Time: Embrace the Cookie Monster Within!

We use cookies to enhance your browsing experience and analyse our traffic. By clicking โ€œAccept Allโ€, you consent to our use of cookies according to our Cookie Policy. You can change your mind any time by visiting out cookie policy.