Dashboard

Core concepts

Understand the fundamental terms and concepts used throughout the Terra API ecosystem. Grasping these will help you integrate Terra more effectively.

Terra credentials

Developer ID

  • What it is: Your Developer ID dev-id is your unique identifier as a developer on the Terra platform. Think of it like your username.

  • Its role: Terra uses this to identify you and associate connected Users and their data back to your account.

  • Security: Not sensitive; can be publicly available.

  • Where to find it: Credentials section of your Terra Dashboard.

Think of your dev ID like your username

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

API Key

  • What is is: Your API key is your secret access token for the API. Think of it like your password.

  • Its role: Authenticates your application's requests, verifying you're the legitimate developer behind the dev-id.

  • Security: Highly sensitive; treat it like a password and never expose it publicly or in client-side code.

  • Where to find it: Credentials section of your Terra Dashboard.

Think of your API Key like your password

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

Data flow & Connections

Source (Provider/Integration)

  • What it is: A Source (also referred to as a Provider, or Integration) is the origin of health and fitness data (e.g., Fitbit, Garmin, Apple Health).

  • Management: You can enable or disable Sources via your Terra Dashboard, controlling the flow of data.

  • List of sources: You can view a list of all available health data sources here.

Destination

  • What it is: Where Terra sends the processed data (e.g., your server via Webhook, SQL database, Azure Blob storage, Amazon SQS queue).

  • Customisation: Configure your active Destination in the Terra Dashboard.

  • List of destinations: You can view a list of all available destinations here.

User (Terra user)

  • What it is: Represents a connection made through Terra to a specific fitness wearable account (e.g., one Fitbit account, one Garmin account).

  • Key point: A single End User (a real person) might have multiple Terra Users if they connect different wearable accounts (e.g., both their Fitbit and their Garmin). Each connection creates a new Terra User ID.

  • For reference: 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".

End User (The person)

  • What it is: The actual individual who owns the wearable devices and whose data is being accessed. An End User can be associated with multiple Terra Users.

Reference ID

  • What it is: An identifier you provide to link a Terra User back to an End User in your own system.

  • Purpose: 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.

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

Data & events

Event

  • What it is: A piece of data, typically a JSON object, sent to your Destination.

  • Types: Can be specific Data Types (like an activity or sleep session) or a metadata event (e.g., authentication success).

Data types

  • Concept: Categories of health and fitness information Terra processes. Each has a defined structure.

  • Examples:

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

    • Sleep: 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 - potentially including time in bed vs. time asleep.

    • Daily: 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.

    • 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.

    • 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).

    • 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.

Large Request

  • What it is: A data request spanning more than 28 days (unless defined otherwise).

  • Processing: 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

Integration mechanisms

Event-driven integrations

  • How it works: 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.

Polled integrations

  • How it works: 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.

API Versions

Terra API is versioned to manage changes and improvements.

Major API versions

  • Indication: Significant architectural changes to API endpoints and infrastructure. These API versions are very infrequent.

  • Identification: 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

  • Indication: Smaller updates, often non-breaking.

  • Identification: You can identify these 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.

PreviousAccount setup and API keysNextOverview

Last updated

Was this helpful?