adaptationio/terra-data

Terra Data Retrieval

Fetch and manage health data from 150+ wearable devices via Terra API.

Data Types Overview

| Type | Description | Update Frequency | |------|-------------|------------------| | Activity | Workout sessions with metrics | Per workout completion | | Sleep | Sleep stages, duration, HRV | Per sleep session | | Body | Weight, body composition, glucose | Multiple times/day | | Daily | Aggregated daily summaries | Multiple times/day | | Nutrition | Meals, macros, calories | Per meal logged | | Menstruation | Cycle tracking, symptoms | Per update | | Athlete | User profile, demographics | On change |

Quick Start

from terra import Terra
from datetime import datetime, timedelta

client = Terra(
    dev_id=os.environ["TERRA_DEV_ID"],
    api_key=os.environ["TERRA_API_KEY"]
)

# Get last 7 days of activity data
end_date = datetime.now()
start_date = end_date - timedelta(days=7)

response = client.activity.get(
    user_id="terra_user_abc123",
    start_date=start_date,
    end_date=end_date
)

for activity in response.data:
    print(f"{activity.metadata.type}: {activity.calories_data.total_burned_calories} cal")

Operations

get-activity

Retrieve completed workout sessions.

def get_activity(
    client: Terra,
    user_id: str,
    start_date: datetime,
    end_date: datetime,
    to_webhook: bool = False
) -> list:
    """
    Get activity/workout data.

    Returns sessions with:
    - Duration, calories burned
    - Heart rate (avg, max, min, samples)
    - Distance, steps, floors
    - GPS position/polyline
    - Power, cadence (cycling)
    """
    response = client.activity.get(
        user_id=user_id,
        start_date=start_date,
        end_date=end_date,
        to_webhook=to_webhook  # True for async processing
    )

    return response.data

Sample Activity Response:

{
  "data": [{
    "metadata": {
      "start_time": "2025-12-05T07:00:00Z",
      "end_time": "2025-12-05T08:00:00Z",
      "type": "running"
    },
    "calories_data": {
      "total_burned_calories": 450,
      "net_activity_calories": 350
    },
    "heart_rate_data": {
      "summary": { "avg_hr_bpm": 145, "max_hr_bpm": 175 }
    },
    "distance_data": { "distance_meters": 8500 },
    "movement_data": { "steps_count": 8500 }
  }]
}

get-sleep

Retrieve sleep sessions with stages.

def get_sleep(
    client: Terra,
    user_id: str,
    start_date: datetime,
    end_date: datetime
) -> list:
    """
    Get sleep data.

    Returns sessions with:
    - Sleep stages (deep, light, REM, awake)
    - Duration in bed vs asleep
    - Sleep efficiency
    - HRV, respiratory rate
    - Temperature deviation
    """
    response = client.sleep.get(
        user_id=user_id,
        start_date=start_date,
        end_date=end_date
    )

    return response.data

Sample Sleep Response:

{
  "data": [{
    "metadata": {
      "start_time": "2025-12-04T22:30:00Z",
      "end_time": "2025-12-05T06:30:00Z"
    },
    "sleep_durations_data": {
      "duration_in_bed_seconds": 28800,
      "duration_asleep_seconds": 26400,
      "sleep_efficiency": 0.92
    },
    "asleep": {
      "duration_deep_sleep_state_seconds": 5400,
      "duration_light_sleep_state_seconds": 14400,
      "duration_REM_sleep_state_seconds": 6600
    },
    "awake": {
      "num_wakeup_events": 2,
      "sleep_latency_seconds": 600
    },
    "heart_rate_data": {
      "summary": { "resting_hr_bpm": 52 }
    }
  }]
}

get-daily

Retrieve aggregated daily summaries.

def get_daily(
    client: Terra,
    user_id: str,
    start_date: datetime,
    end_date: datetime
) -> list:
    """
    Get daily aggregated data.

    Returns summaries with:
    - Steps, calories, distance
    - Active minutes, floors
    - Resting heart rate, HRV
    - Recovery scores
    - Stress data

    Note: Sent multiple times/day - always OVERWRITE previous data.
    """
    response = client.daily.get(
        user_id=user_id,
        start_date=start_date,
        end_date=end_date
    )

    return response.data

Sample Daily Response:

{
  "data": [{
    "metadata": {
      "start_time": "2025-12-05T00:00:00Z",
      "end_time": "2025-12-05T23:59:59Z"
    },
    "calories_data": {
      "total_burned_calories": 2400,
      "BMR_calories": 1600,
      "net_activity_calories": 800
    },
    "movement_data": {
      "steps_count": 10500,
      "floors_climbed": 12
    },
    "heart_rate_data": {
      "summary": { "resting_hr_bpm": 58 }
    },
    "scores": {
      "recovery": { "score": 82 },
      "activity": { "score": 75 },
      "sleep": { "score": 88 }
    }
  }]
}

get-body

Retrieve body metrics and biometrics.

def get_body(
    client: Terra,
    user_id: str,
    start_date: datetime,
    end_date: datetime
) -> list:
    """
    Get body metrics data.

    Returns measurements including:
    - Weight, height, BMI
    - Body fat %, muscle mass
    - Blood glucose (CGM)
    - Blood pressure
    - Temperature
    - SpO2

    Note: Sent multiple times/day - always OVERWRITE previous data.
    """
    response = client.body.get(
        user_id=user_id,
        start_date=start_date,
        end_date=end_date
    )

    return response.data

Sample Body Response:

{
  "data": [{
    "metadata": {
      "start_time": "2025-12-05T00:00:00Z",
      "end_time": "2025-12-05T23:59:59Z"
    },
    "body_metrics": {
      "weight_kg": 75.5,
      "height_cm": 178,
      "BMI": 23.8,
      "body_fat_percentage": 18.5
    },
    "blood_glucose_data": {
      "blood_glucose_samples": [
        { "glucose_mg_per_dL": 95, "timestamp": "2025-12-05T07:00:00Z" },
        { "glucose_mg_per_dL": 120, "timestamp": "2025-12-05T08:30:00Z" }
      ]
    },
    "blood_pressure_data": {
      "systolic_bp_mmHg": 120,
      "diastolic_bp_mmHg": 80
    }
  }]
}

get-nutrition

Retrieve nutrition and meal data.

def get_nutrition(
    client: Terra,
    user_id: str,
    start_date: datetime,
    end_date: datetime
) -> list:
    """
    Get nutrition data.

    Returns meal logs with:
    - Calories, macros (protein, carbs, fat)
    - Micronutrients
    - Individual food items
    - Meal timestamps
    """
    response = client.nutrition.get(
        user_id=user_id,
        start_date=start_date,
        end_date=end_date
    )

    return response.data

Sample Nutrition Response:

{
  "data": [{
    "metadata": {
      "start_time": "2025-12-05T00:00:00Z",
      "end_time": "2025-12-05T23:59:59Z"
    },
    "summary": {
      "macros": {
        "calories": 2200,
        "protein_g": 120,
        "carbohydrates_g": 250,
        "fat_g": 70,
        "fiber_g": 30
      }
    },
    "meals": [
      {
        "name": "Breakfast",
        "timestamp": "2025-12-05T08:00:00Z",
        "macros": { "calories": 450, "protein_g": 25 }
      }
    ]
  }]
}

get-menstruation

Retrieve menstrual cycle data.

def get_menstruation(
    client: Terra,
    user_id: str,
    start_date: datetime,
    end_date: datetime
) -> list:
    """
    Get menstruation/cycle data.

    Returns tracking data including:
    - Cycle phase, day in cycle
    - Flow level, symptoms
    - Predictions
    """
    response = client.menstruation.get(
        user_id=user_id,
        start_date=start_date,
        end_date=end_date
    )

    return response.data

get-athlete

Retrieve user profile information.

def get_athlete(
    client: Terra,
    user_id: str
) -> dict:
    """
    Get user profile/athlete data.

    Returns profile including:
    - Name, email (if available)
    - Date of birth, age
    - Sex, gender
    - Location
    - Connected devices
    """
    response = client.athlete.get(user_id=user_id)
    return response.data

Bulk Data Retrieval

Get All Data Types

async def get_all_user_data(
    client: Terra,
    user_id: str,
    start_date: datetime,
    end_date: datetime
) -> dict:
    """Fetch all data types for a user."""

    return {
        "activity": client.activity.get(user_id, start_date, end_date).data,
        "sleep": client.sleep.get(user_id, start_date, end_date).data,
        "daily": client.daily.get(user_id, start_date, end_date).data,
        "body": client.body.get(user_id, start_date, end_date).data,
        "nutrition": client.nutrition.get(user_id, start_date, end_date).data,
    }

Historical Backfill

def backfill_user_data(
    client: Terra,
    user_id: str,
    days_back: int = 90
) -> dict:
    """
    Backfill historical data for newly connected user.

    Note: Requests >28 days are processed asynchronously
    and results sent via webhook.
    """
    end_date = datetime.now()
    start_date = end_date - timedelta(days=days_back)

    # For requests >28 days, use to_webhook=True
    if days_back > 28:
        # Async - results via webhook
        client.activity.get(user_id, start_date, end_date, to_webhook=True)
        client.sleep.get(user_id, start_date, end_date, to_webhook=True)
        client.daily.get(user_id, start_date, end_date, to_webhook=True)
        return {"status": "processing", "message": "Results via webhook"}
    else:
        # Sync - immediate response
        return get_all_user_data(client, user_id, start_date, end_date)

Provider Historical Data Limits

| Provider | Max Historical Data | |----------|---------------------| | Garmin | 5 years | | Fitbit | 10 years | | Oura | 3 years | | WHOOP | 2 years | | Polar | 30 days | | COROS | 3 months | | Withings | 2 years |

Data Normalization

Terra normalizes all provider data into consistent schemas:

Unique Identifiers

• Activity/Sleep: start_time + end_time = unique session
• Daily/Body/Nutrition: Date-based, OVERWRITE on updates

Update Strategy

def handle_data_update(data_type: str, payload: dict):
    """Handle incoming data with proper update strategy."""

    unique_key = f"{payload['user']['user_id']}:{payload['metadata']['start_time']}:{payload['metadata']['end_time']}"

    if data_type in ["daily", "body", "nutrition"]:
        # OVERWRITE - these update multiple times per day
        db.upsert(unique_key, payload)
    else:
        # INSERT OR IGNORE - sessions are unique
        db.insert_if_not_exists(unique_key, payload)

Writing Data (Limited Providers)

Some providers support writing data back:

# Post activity to Wahoo
client.activity.post(
    user_id="terra_user_abc123",
    data={
        "type": "cycling",
        "start_time": "2025-12-05T10:00:00Z",
        "end_time": "2025-12-05T11:00:00Z",
        "calories": 500,
        "distance_meters": 25000
    }
)

# Post nutrition to Fitbit
client.nutrition.post(
    user_id="terra_user_abc123",
    data={
        "meals": [{
            "name": "Lunch",
            "calories": 650,
            "protein_g": 35
        }]
    }
)

# Post planned workout to Apple Health
client.planned_workout.post(
    user_id="terra_user_abc123",
    data={
        "name": "5K Training",
        "type": "running",
        "phases": [
            {"type": "warmup", "duration_seconds": 300},
            {"type": "interval", "duration_seconds": 600}
        ]
    }
)

Database Schema

-- Activity sessions
CREATE TABLE terra_activities (
    id SERIAL PRIMARY KEY,
    terra_user_id VARCHAR(255),
    start_time TIMESTAMP,
    end_time TIMESTAMP,
    activity_type VARCHAR(50),
    calories INTEGER,
    distance_meters FLOAT,
    avg_heart_rate INTEGER,
    data JSONB,
    UNIQUE(terra_user_id, start_time, end_time)
);

-- Daily summaries (UPSERT)
CREATE TABLE terra_daily (
    id SERIAL PRIMARY KEY,
    terra_user_id VARCHAR(255),
    date DATE,
    steps INTEGER,
    calories INTEGER,
    distance_meters FLOAT,
    resting_heart_rate INTEGER,
    data JSONB,
    updated_at TIMESTAMP DEFAULT NOW(),
    UNIQUE(terra_user_id, date)
);

Related Skills

• terra-auth: Authentication setup
• terra-connections: Connect users
• terra-webhooks: Real-time data delivery
• terra-sdk: SDK integration