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.
Our payloads to your webhook adhere to a strict standard:
- There will always be a
terra-signaturefield in theheadersof 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_webhookastrueorfalse.
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!
