Core concepts

Developer ID (Dev ID)

Your developer ID is your unique identifier for access to the API. This is how Terra identifies you, and ties Users & their data back to you.

Think of your dev ID like your username

It does not constitute sensitive information. Making it publicly available is not a security conern

You may find your dev ID in the credentials section of your Terra Dashboard account

API Key

Your API key is your secret access token for the API. This is how Terra knows you're legitimately the developer behind the dev ID you're using.

Think of your API Key like your password

It constitutes sensitive information. Making it publicly available is a big security risk

You may find your API Key in the credentials section of your Terra Dashboard account

Destinations

Terra sends data to your server through a Destination. At its most basic, this is a Webhook, but can also take the form of an SQL database, an Azure Blog storage, or an Amazon SQS queue. You can customize which Destination is active at any given time through your Terra Dashboard.

Source/Provider/Integration

A Source (also referred to as a Provider, or Integration) is a wearable fitness & health data supplier, such as Fitbit, Garmin or Apple Health. These can be turned on or off (enabling or interrupting the flow of data) through your Terra Dashboard.

Check out the list of supported integrations here

User

Throughout this documentation, a connection made to one fitness wearable account (e.g. one Fitbit account, or one Garmin account) will be referred to as "one User".

This means that multiple Users can be created for one individual, also referred to as an End User.

Any time a e.g. Fitbit/Garmin/Google Fit account is connected through Terra, a User is created

End User

An End User represents a person who may own one or more wearable devices, and can have multiple Users associated to them through Terra.

Reference ID

You can use a Reference ID in order to tie a User back to an End User. The reference_id should be the identifier of the End User on your systems. This could be the End User's username, their email address, or any way in which you identify them.

When creating a User, you will have the option of passing in a reference_id to conveniently link it back to an End User

Event

An Event is a piece of data (usually a JSON object) sent to your Destination. This can be one of the Data Types or a metadata event type

Large Request

A data request spanning more than 28 days (unless defined otherwise).

This type of request will always be processed asynchronously, and sent to your destinations in chunks. The chunks sent to you will each be of either

• at most 10MB

• at most 10 objects within the data array

whichever limit of the two gets hit first will determine the chunk's size

Polled/Event-Driven integrations

Integrations that are Event-Driven allow for the fastest data retrieval speeds. As soon as new data is synced from the user's wearable's app (e.g. the Fitbit app) to the Provider's cloud, a notification (or event) gets sent to Terra with the newest data, following which Terra sends you a payload to your Destination with the latest available data.

Integrations that are Polled do not have an event-sending system, and require Terra to periodically check for data updates by polling their servers. This will be done as often as every 5 minutes.

Data Types

Activity

This represents a workout session completed (not currently active or planned) by the user, with a defined start and end time. For example, this corresponds to when a user woud press "start workout" on their Garmin smartwatch, go for a run, then press "end workout".

Sleep

This represents a sleep session completed by the user. The start time and end time can be representative of the time that the user got in bed instead of the time that they fell asleep at, if tracked by the wearable device.

Daily

This represents a summary of the total activity completed by a user for a given 24 hour period, defined by the start and end time of the payload.

These payloads will be sent multiple times throughout a given day, as a user moves around, and will be a total of their activity up until that point in the day. When ingesting Daily events, always overwrite data for a given date with the latest one sent to your Destination.

Menstruation

This represents a day in the user's menstrual cycle, and includes information about that day within the context of their overall monthly cycle, such as current phase, and any metadata associated with that day (bleeding level, feelings of nausea, etc).

Body

This represents the various Body metrics for a user for a given 24 hour period, defined by the start and end time of the payload.

These payloads will be sent multiple times throughout a given day, as a user generates more body-related metrics (weigh-ins, blood glucose measurements etc), and will be a total up until that point in the day. When ingesting Body events, always overwrite data for a given date with the latest one sent to your Destination.

Nutrition

This represents the various food logged by a user for a given 24 hour period, defined by the start and end time of the payload.

This will be data logged in Food Diary apps such as MyFitnessPal, Fitbit or MacrosFirst. Each meal represents a given food item logged within that day.

API Versions

Terra API is versioned in two main ways.

Major API versions

These API versions are very infrequent and represent a large architectural change in the API endpoints, and underlying infrastructure. You will identify these with the base URL (i.e. api.tryterra.co/v2, api.tryterra.co/v1, and access.tryterra.co are 3 separate major versions)

Minor API versions

These can be identified by the version included in every payload you receive from Terra, and will be versioned by date. For example, at the time of writing, the latest API version is 2022-03-16. The version prior to it was 2022-03-02.

Only breaking changes to the API are versioned. Any non breaking changes will be continuously developed, tested, and deployed.