Quickstart
All Terra requests can be downloaded as a postman collection here
1. Connect an account
Users
Terra holds the concept of Users
in which each TerraUser
is a an object with the following structure
{
"user_id": String, // not nullable
"provider": String, // not nullable
"last_webhook_update": String //ISO8601 formatted string
}
Concept of a User object
A user is one connection to one provider. If you'd like to connect multiple wearables to one of your users, this will require multiple TerraUser objects
You can create users by using a Terra Connect authentication session
Authentication
In order to authenticate your first TerraUser
, use the appropriate TerraConnect endpoint and make a request as shown below
curl --location --request POST 'https://api.tryterra.co/v2/auth/generateWidgetSession' \
--header 'dev-id: YOUR_DEV_ID' \
--header 'X-API-Key: YOUR_API_KEY' \
Credentials
Make sure to replace YOUR_DEV_ID and YOUR_API_KEY with the appropriate credentials, found in your Terra Dashboard's API customization page
You'll receive a JSON response that looks like the following
{
"expires_in": 900, //Length of the auth session, in seconds
"session_id": SOME_SESSION_ID, //unique ID for the session
"status": "success",
"url": "https://widget.tryterra.co/session/SOME_SESSION_ID" //URL to access the session
}
From which you can copy & paste the URL into your browser, select a provider, and authenticate.
Upon the final redirection, your URL will look like the following:
https://widget.tryterra.co/session/demo/success?user_id=SOME_USER_ID&resource=SOME_PROVIDER
Where the authenticated user ID will be available as a query parameter for convenience. You can copy this user ID and save it somewhere for convenience
User creation
The newly created
TerraUser
object will also be sent to your webhook
2. Request Data
Once you've connected an account and saved the User ID provided, you can now make data requests.
These can be made for:
- Activity - event recorded for a specific workout
- Athlete - user information
- Body - data relating to body measurements, such as weight, height, glucose etc...
- Daily - daily summary of a user's total activity such as steps, distance, etc...
- Menstruation - log of a user's menstruation data
- Nutrition - log of a user's nutrition data, including both individual meals and a daily summary
- Sleep - events recorded for sleep sessions
You can now try this out for yourself with your newly created TerraUser
Make a request with the format:
curl --location -g --request GET 'https://api.tryterra.co/v2/activity?to_webhook=false&user_id=YOUR_USER_ID&start_date=2022-07-20&end_date=2022-07-22&to_webhook=false' \
--header 'dev-id: YOUR_DEV_ID' \
--header 'X-API-Key: YOUR_API_KEY'
Query parameters to include:
to_webhook': set to false for testing - this ensures you get the data in the HTTP response and not [asynchronously sent to your webhook](doc:getting-data-into-your-project)
user_id: the user ID of the user created in step 1
start_date: ISO8601 date string for which you want to query
end_date`: ISO8601 date string for which you want to query
You should now receive the requested data in the HTTP response.
3. Data updates
Ideally, you will want to automatically receive up-to-date data without having to query the API for it.
To do that, set up a webhook endpoint - essentially an endpoint on your server which accepts HTTP POST requests.
Once done, make sure you handle each event type appropriately.
Updated 4 months ago