# Overview

## What is Health & Fitness API?

Terra's Health & Fitness API is your primary gateway to accessing comprehensive health data in your app from your users' wearables, devices, health apps, and medical devices.

* It **standardises** endpoints for authentication, requests, and data models across 500+ data sources. 
* It's **event-based**: user health and fitness data is automatically pushed to your destination (e.g., webhook) after authentication. API requests are therefore only needed for historical data.

<figure><img src="https://files.readme.io/f6a8853-web_api_cropped.png" alt="" width="563"><figcaption><p>Diagram showing the flow of data through Terra's Health &#x26; Fitness API</p></figcaption></figure>

***

## Key features

### 🎣 Automatic payloads for new data (via Webhook)

* **Mechanism:** Receive automated, near real-time data updates via HTTP POST requests (Webhooks) to your specified Destination endpoint.
* **Trigger:** Webhooks are typically triggered when new data is synced from a user's wearable or app to the provider's cloud service and subsequently processed by Terra.
* **Content:** Payloads include standardised JSON representing new or updated user data (e.g., a completed workout, daily summary, new sleep session).
* **Use Case:** Keep your application's data for users current without needing to poll for changes. Ideal for timely insights and responsive features.

**Example payload:**&#x20;

{% code expandable="true" %}

```json
Activity Payload (JSON)
{
  "metadata": {
    "timestamp_localization": 1,
    "start_time": "2026-01-19T10:48:51",
    "name": "Softball",
    "summary_id": 45209947591,
    "type": 93,
    "upload_type": 5,
    "end_time": "2026-01-19T12:01:51"
  },
  "position_data": {
    "start_pos_lat_lng_deg": ["..."],
    "position_samples": ["..."],
    "center_pos_lat_lng_deg": ["..."],
    "end_pos_lat_lng_deg": ["..."]
  },
  "distance_data": {
    "summary": { "...": "..." },
    "detailed": { "...": "..." }
  },
  "heart_rate_data": {
    "summary": { "...": "..." },
    "detailed": { "...": "..." }
  },
  "calories_data": {
    "total_burned_calories": 1285.6,
    "net_activity_calories": 189.95
  },
  "movement_data": {
    "speed_samples": ["..."],
    "max_speed_meters_per_second": 8.72,
    "avg_speed_meters_per_second": 9.05,
    "max_cadence_rpm": 35.74,
    "avg_cadence_rpm": 37.74
  },
  "device_data": {
    "manufacturer": "Terra",
    "name": "Random device name",
    "serial_number": 547901
  },
  "power_data": {
    "avg_watts": 14.21,
    "power_samples": ["..."],
    "max_watts": 24.86
  },
  "active_durations_data": {
    "activity_seconds": 981.86
  }
}
```

{% endcode %}

Garmin example [here](https://tryterra.co/integrations/garmin).&#x20;

### 🗄️ Historical data retrieval (via GET requests)

* **Mechanism:** Make synchronous or asynchronous `GET` requests to specific Terra API endpoints to fetch data for a user over a defined date range.
* **Scope:** Access data from the point a user first connected their account to Terra, subject to provider limitations.
* **Use Case:** Populate user profiles, establish baselines, perform trend analysis, or backfill data.
* **Considerations:** For large data ranges (e.g., >28 days), requests are often processed asynchronously, with data delivered in chunks via Webhooks or to a specified data store.

### 🔑 User authentication

* **Mechanism:** Terra provides tools (e.g., Terra Widget, or APIs to build your own UI) to facilitate the user authentication process, where users grant your application permission to access their health data via Terra.
* **User Identity:** Terra manages user connections and provides unique identifiers for each connected data source account.

### 🧩 Standardised data model

* **Mechanism:** All data retrieved from various providers is transformed by Terra into consistent, predefined JSON schemas.
* **Benefit:** Simplifies integration by providing a uniform data structure, regardless of the original source's format. You code against one set of models.
* **Scope:** Applies to all data types (Activity, Sleep, Body, Daily, Nutrition, etc.). Detailed schemas are available in the [Data Models](https://app.gitbook.com/s/eJJpVMsUARUJq9lYmL6t/health-and-fitness-api/data-models).

### ✏️ Writing data

* **Mechanism:** Send data from your application to Terra via specific POST API endpoints, which then attempts to write this data to the connected user's account on the source provider's platform.
* **Supported Operations (Examples):**
  * **Planned Workouts:** Upload structured workout plans that users can access and follow on their wearable devices.
* **Provider Dependency:** Only certain providers are supported - this depends on the features supported by the end provider's API. Not all data types or providers support write operations.

***

## How Terra Accesses Data: Cloud APIs vs Mobile SDKs

Understanding how Terra connects to different data sources is crucial.

<table data-full-width="true"><thead><tr><th valign="middle">Type of data source</th><th width="247.24609375">Integrations</th><th>Integration Platform</th></tr></thead><tbody><tr><td valign="middle">Web-based source</td><td><ul><li>Garmin</li><li>Fitbit</li><li>Oura</li><li>Strava</li></ul><p><em>500+ other sources</em></p></td><td>Backend Server (using the Health &#x26; Fitness API)</td></tr><tr><td valign="middle">Mobile-only source</td><td><ul><li>Apple Health</li><li>Samsung Health</li><li>Google Fit</li><li>Health Connect</li></ul><p><em>No other sources</em></p></td><td>Mobile App (using the Terra Mobile SDK)</td></tr></tbody></table>

### Web-based sources

**The majority of Terra integrations are web-based providers (e.g., Garmin, Fitbit, Oura, Strava)**

* For most providers, Terra integrates directly with their Web APIs.
* Whether you are building a web app or mobile app, you should integrate the API in your backend.
* Once a user authenticates via the API, Terra can fetch data and send **payloads** (e.g. to a webhook endpoint).

### Mobile-only **sources**

**The only mobile-only sources are: Apple Health, Samsung Health, and Health Connect.**

* These sources do not offer Web APIs for third-party developer access.
* They require a **mobile app** with a **Terra's** **Mobile SDK** on the user's device to fetch the data.
* Your mobile app, equipped with Terra's Mobile SDK, will facilitate the connection to the on-device health data store (e.g., HealthKit on iOS, Health Connect on Android).
* The Mobile SDK then securely transmits this data to Terra for processing and delivery of **payloads** to your configured Destination (e.g. to a webhook endpoints).

{% hint style="danger" %}

## Only use the Mobile SDK if you need to&#x20;

The **vast majority** of Health & Fitness API **work via Terra's Web API** (e.g., Garmin, Fitbit, Oura, Strava)**.**&#x20;

**You do&#x20;*****NOT*****&#x20;need** to use the **Mobile SDK for them.**

***

**Only use the** [**Mobile SDK**](https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources) if you want to integrate **with the following providers:**

<img src="https://464213908-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVGMJVuZnZyOtvV4b53cY%2Fuploads%2FDH2JWDtg632mUQlEdrLH%2F4p3k173m8ihe71872bi9r0292q-0af5626e815091005bacb793985c1870.png?alt=media&#x26;token=062c917e-02fe-4029-9809-fc881cf09de3" alt="" data-size="line"> **Apple Health**&#x20;

<img src="https://464213908-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVGMJVuZnZyOtvV4b53cY%2Fuploads%2F0lTv9KpldVVjBdg3JJQs%2Fimgbin_samsung-galaxy-samsung-health-samsung-electronics-android-png.png?alt=media&#x26;token=b58f3118-a2e1-4b09-9d30-4f862253adb6" alt="" data-size="line"> **Samsung Health**&#x20;

<img src="https://464213908-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVGMJVuZnZyOtvV4b53cY%2Fuploads%2FmotL0wnZKiEWOKt46zOU%2Fvecteezy_google-fit-icon-logo-symbol_22484515.png?alt=media&#x26;token=a2d0ae73-5116-49fd-8ce1-0f7b5e6f716b" alt="" data-size="line"> **Health Connect**&#x20;
{% endhint %}

### Rate Limits

* Terra **never** imposes any rate limits. Downstream providers often have their own rate limits (for example Fitbit limits developers to 150 requests/hour per user), but Terra manages everything for you, including retries with appropriate backoffs, to ensure you always get consistent data.

***

## Next steps

{% stepper %}
{% step %}

### [Quickstart](https://docs.tryterra.co/health-and-fitness-api/quickstart)

Get health data from your first user via a web-based source (e.g., Garmin, Fitbit, Oura).
{% endstep %}

{% step %}

### [Integration setup](https://docs.tryterra.co/health-and-fitness-api/integration-setup)

Learn how to setup and configure the Health & Fitness API to receive your users' data to your preferred destination (e.g. webhook, DB, etc). This includes enabling data sources, setting up data destinations, managing API access, and understanding environments.
{% endstep %}

{% step %}

### [User authentication](https://docs.tryterra.co/health-and-fitness-api/user-authentication)

Learn how to securely authenticate your users' health data sources (e.g., Fitbit, Garmin) to your application via Terra, including handling authentication flows and user IDs.
{% endstep %}

{% step %}

### [**Accessing & Managing User Health Data**](https://docs.tryterra.co/health-and-fitness-api/managing-user-health-data)

Learn how to receive automatic data updates as events, request historical information, and write data (like planned workouts) back to users' connected services.
{% endstep %}

{% step %}

### [Using SDKs for mobile-only sources](https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources)

Essential reading if you need to integrate Apple Health, Samsung Health, or Google Fit/Health Connect.
{% endstep %}
{% endstepper %}