Quick Start
Introduction
As you know, Terra allows you to connect user wearables and receive fitness & health data in a unified format. To achieve this, 3 actions are required on your end:
1- Receive data from Terra
2- Connect users to terra
3- Query historical data from Terra
Let's setup below each of these steps to get started with the API!
1- Receiving Data: Webhooks
One of the key features of Terra is pushing data asynchronously to an endpoint of your choice. This allows you to:
- Receive data whenever it is available by the user's wearable without having to query it
- Receive large amounts of data without worrying about the payload size in a classic HTTP request
First, you need to tell Terra where it should send the data. This can be done in the Dashboard under API > Customise > Settings > Webhook URL. Set an endpoint where you would like to receive the data.
Change your webhook endpoint on the Terra dashboard
Don't have an endpoint yet?
That's fine! You can keep following the setup by using an online endpoint for free on webhook.site. You can also use the code recipe below to setup a simple webhook endpoint, or follow the video tutorial.
Test it!
Once your webhook endpoint is setup, you can test it using the data generator! In your dashboard, head to API > Data Generator. Select a provider (e.g., Oura), and a scope (e.g., Sleep) to generate fake data, then click "Send to Webhook". If your endpoint was setup correctly, you should receive the data seen on the dashboard to your webhook!
Generate data using the data generator to test your webhook endpoint
Replying with a 200 status
Your webhook endpoint will need to reply to Terra with a 200 status code when a payload is received. Otherwise, Terra will assume your endpoint did not receive the data and will retry sending the data.
Congrats! Now you are all set to receive data from Terra.
2- Connecting Users: Terra Widget
Now that you can receive data from Terra, it is time to connect an actual wearable account to your application. Different users will have different wearables. Terra helps you connect users' wearables by using a widget, which is a ready front-end where the user can select a wearable and complete the authentication process.
What does the widget look like?
You can see an example of that the widget will look like for your users on https://demo.tryterra.co! The widget button and background colours as well as logo can be customised in your dashboard under the Widget section.
In order to use the widget to connect users, you need to:
1- Request a widget session
2- Present the session to your user
3- Save the user identifier generated by Terra for that user
Requesting a widget session
Let's assume you have a user IDed as Dolphin. From your service (e.g., your backend server), request a widget session from Terra with reference_id = "Dolphin" (more details about widget session requests here with examples in Java, Python, etc...)
curl --request POST \
--url https://api.tryterra.co/v2/auth/generateWidgetSession \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'dev-id: dev-id' \
--header 'x-api-key: api-key' \
--data '
{
"reference_id": "Dolphin",
"providers": "Oura, Garmin, Fitbit, Google, Polar",
"auth_success_redirect_url": "myapplication.com/success",
"auth_failure_redirect_url": "myapplication.com/fail",
"language": "EN"
}
'
Terra will reply back with a widget session URL. This is a unique session URL through which your user can select and connect a wearable.
{
"session_id": "2be51614-7df8-423e-9a00-6649e3c7eeba",
"status": "success",
"url": "https://widget.tryterra.co/2be51614-7df8-423e-9a00-6649e3c7eeba"
}
Redirect the user to this widget session. They will progress through the following screens:
Left to right: Terra prompt, wearable selection, wearable auth
Once the user successfully authenticates, Terra will send you a webhook push with details about this authentication. This payload will contain the authenticated user Terra id as well as the original ID you sent (i.e., "Dolphin").
{
"status":"success",
"type":"auth",
"widget_session_id":"2be51614-7df8-423e-9a00-6649e3c7eeba", // <- the widget session user
"message":"User has successfully authenticated",
"user":{
"provider":"FITBIT", // <- the connected wearable type
"user_id":"783165d4-3c58-43ca-8670-3a5c20297902", // <- the Terra id
"last_webhook_update":null
},
"reference_id":"Dolphin" // <- the ID on your end
}
Using the session result
Once your user connects a wearable successfully, it is important that you remember the Terra id on your end. This is because the Terra id is used for:
- Identifying whose data Terra sent to you
- Querying data for a specific user wearable
For "Dolphin", save the Terra id and the provider received in the auth success webhook. This is an example if you had a table storage of your users, where Lion has connected both their Polar and their Garmin:
My User ID | Terra IDs | Other information... |
|---|---|---|
Dolphin | | |
Lion | |
Building your own widget
You can create your own widget by using the /authenticate endpoint to generate the provider authentication URLs, and build your own frontend on top.
3- Querying Data
The final key feature of the API is that you can request historical data. For example, you might want to check Dolphin's activities for the past 5 months to generate insights about their training schedule.
Querying data involves two key parameters:
- A scope (activity, daily, sleep, etc...)
- A date range (start and end time)
To query activity data for the past 5 months, execute the following query:
curl --request GET \
--url 'https://api.tryterra.co/v2/activity?user_id=783165d4-3c58-43ca-8670-3a5c20297902&start_time=2022-05-15&end_time=2022-05-30&to_webhook=true&with_samples=true' \
--header 'Accept: application/json' \
--header 'dev-id: dev-id' \
--header 'x-api-key: api-key'
This will send activity data for Dolphin for the past 2 weeks to your webhook! The payload will contain the Terra user id associated with Dolphin's Fitbit, which will allow you to associate the data to Dolphin's account in your app.
{
"data": [
{
"active_durations_data": {
"activity_levels_samples": [
{
"activity_level": 1,
"timestamp": "2022-05-31T09:50:46.824548+00:00"
},
{
"activity_level": 0,
"timestamp": "2022-05-31T10:03:46.824548+00:00"
} // etc...
],
"activity_seconds": 3349.3554477752477
},
"calories_data": {
"net_activity_calories": 731.0387310918702
},
"distance_data": {
"detailed": {
"distance_samples": [
{
"distance_metres": 0,
"timer_duration_seconds": 0,
"timestamp": "2022-05-31T09:50:46.824548+00:00"
},
{
"distance_metres": 31.717550060250783,
"timer_duration_seconds": 13,
"timestamp": "2022-05-31T10:03:46.824548+00:00"
} // etc...
]
},
"summary": {
"distance_metres": 175.80883243153818,
"steps": 8279
}
},
"heart_rate_data": {
"detailed": {
"hr_samples": [
{
"bpm": 91,
"timestamp": "2022-05-31T09:50:46.824548+00:00"
},
{
"bpm": 161,
"timestamp": "2022-05-31T10:03:46.824548+00:00"
} // etc...
]
},
"summary": {
"avg_hr": 52.337520106300275
}
},
"metadata": {
"end_time": "2022-05-31T10:55:46.824548+00:00",
"start_time": "2022-05-31T09:50:46.824548+00:00",
"summary_id": "243711068167",
"type": 79,
"upload_type": 0
},
"movement_data": {
"avg_speed_metres_per_second": 8.243373167413132
},
"position_data": {
"end_pos_lat_lng": [
52.09762763446029,
1.4787756254080242
],
"start_pos_lat_lng": [
52.701487734444875,
0.8743390708772818
]
}
}
],
"type": "activity",
"user": {
"provider": "FITBIT",
"user_id": "783165d4-3c58-43ca-8670-3a5c20297902"
}
}
4 - Wrap up
Congratulations on making it to the end! Through this guide, you should've learned:
- How to receive data on your webhook
- How to connect a wearable
- How to query historical data from Terra
Updated about 20 hours ago