Data models

📘 Note

All fields in all models are nullable unless explicitly stated otherwise.

🚧 Uniquely identifying payloads

Activity

Activity payloads can be uniquely identified by their summary_id field under metadata. If an activity comes in a second time, with the same summary ID, you should update the previous entries with the new data corresponding to that summary_id

Body, Daily, Sleep, Nutrition

Body, Daily, Sleep, Nutrition payloads can be uniquely identified by the combination of their start_time and end_time fields under metadata. If one of these payloads comes in again, with the same start_time and end_time, you should update the previous entries with the new data.

For example, the Daily payload can come in multiple times in one day, with updated steps field every time

🚧 Schema parser

When building a parser for the models below, please take into account that more fields may be added down the line (but no field name should ever change within a given version)

Also note that this version is equivalent to 2022_03_16

TerraUser

{
    "user_id": String,  // not nullable
    "provider": String,  // not nullable
    "last_webhook_update": String,
    "scopes": String,
    "reference_id": String
}

Core data types

Activity

{
    "movement_data": {
        "normalized_speed_meters_per_second": Number,
        "max_cadence_rpm": Number,
        "avg_speed_meters_per_second": Number,
        "avg_pace_minutes_per_kilometer": Number,
        "max_velocity_meters_per_second": Number,
        "max_pace_minutes_per_kilometer": Number,
        "max_torque_newton_meters": Number,
        "avg_cadence_rpm": Number,
        "avg_velocity_meters_per_second": Number,
        "avg_torque_newton_meters": Number,
        "cadence_samples": Array<CadenceSample>,
        "speed_samples": Array<SpeedSample>,
        "max_speed_meters_per_second": Number
    },
  	"strain_data": {
      "strain_level": Number
    },
    "power_data": {
        "max_watts": Number,
        "avg_watts": Number,
        "power_samples": Array<PowerSample>
    },
    "position_data": {
        "position_samples": Array<PositionSample>,
        "center_pos_lat_lng_deg": [Number, Number],
        "start_pos_lat_lng_deg": [Number, Number],
        "end_pos_lat_lng_deg": [Number, Number]
    },
    "oxygen_data": {
        "saturation_samples": Array<OxygenSaturationSample>,
        "avg_saturation_percentage": Number,
        "vo2_samples": Array<Vo2MaxSample>,
        "vo2max_ml_per_min_per_kg": Number
    },
    "metadata": {
        "name": String,
        "summary_id": String,
        "country": String,
        "state": String,
        "upload_type": UploadType,
        "end_time": String,
        "city": String,
        "type": ActivityType,
        "start_time": String
    },
    "TSS_data": {
        "TSS_samples": Array<TSSSample>
    },
    "device_data": {
        "name": String,
        "other_devices": Array<OtherDeviceData>,
        "hardware_version": String,
        "manufacturer": String,
        "software_version": String,
        "activation_timestamp": String,
        "serial_number": String,
      	"data_provided": Array<DeviceDataType>,
      	"last_upload_date": String
    },
    "distance_data": {
        "summary": {
            "swimming": {
                "num_strokes": Number,
                "num_laps": Number,
                "pool_length_meters": Number
            },
            "floors_climbed": Number,
            "elevation": {
                "loss_actual_meters": Number,
                "min_meters": Number,
                "avg_meters": Number,
                "gain_actual_meters": Number,
                "max_meters": Number,
                "gain_planned_meters": Number
            },
            "steps": Number,
            "distance_meters": Number
        },
        "detailed": {
          	"step_samples": Array<StepSample>,
            "distance_samples": Array<DistanceSample>,
            "elevation_samples": Array<ElevationSample>,
            "floors_climbed_samples": Array<FloorsClimbedSample>,
        }
    },
    "calories_data": {
        "net_intake_calories": Number,
        "BMR_calories": Number,
        "total_burned_calories": Number,
        "net_activity_calories": Number
    },
    "lap_data": {
        "laps": Array<LapSample>
    },
    "MET_data": {
        "MET_samples": Array<METSample>,
        "num_low_intensity_minutes": Number,
        "num_high_intensity_minutes": Number,
        "num_inactive_minutes": Number,
        "num_moderate_intensity_minutes": Number,
        "avg_level": Number
    },
    "heart_rate_data": {
        "summary": {
            "max_hr_bpm": Number,
            "resting_hr_bpm": Number,
            "avg_hrv_rmssd": Number,
            "min_hr_bpm": Number,
            "user_max_hr_bpm": Number,
            "avg_hrv_sdnn": Number,
            "avg_hr_bpm": Number,
            "hr_zone_data": Array<HeartRateZoneData>
        },
        "detailed": {
            "hr_samples": Array<HeartRateDataSample>,
            "hrv_samples_sdnn": Array<HeartRateVariabilityDataSampleSDNN>,
            "hrv_samples_rmssd": Array<HeartRateVariabilityDataSampleRMSSD>
        }
    },
    "active_durations_data": {
        "activity_seconds": Number,
        "rest_seconds": Number,
        "low_intensity_seconds": Number,
        "activity_levels_samples": Array<ActivityLevelSample>,
        "vigorous_intensity_seconds": Number,
        "num_continuous_inactive_periods": Number,
        "inactivity_seconds": Number,
        "moderate_intensity_seconds": Number,
      	"standing_seconds": Number,
      	"standing_hours_count": Number
    },
    "polyline_map_data": {
        "summary_polyline": String
    },
    "strain_data": {
        "strain_level": Number
    },
    "work_data": {
        "work_kilojoules": Number
    },
    "energy_data": {
        "energy_kilojoules": Number,
        "energy_planned_kilojoules": Number
    }
}

Athlete

{
    "age": Number,
    "country": String,
    "bio": String,
    "state": String,
    "last_name": String,
    "sex": String,
    "city": String,
    "email": String,
    "date_of_birth": String,
    "first_name": String,
    "gender": String,
    "joined_provider": String,
    "devices": Array<device_data>
}

Body

{
    "oxygen_data": {
        "saturation_samples": Array<OxygenSaturationSample>,
        "avg_saturation_percentage": Number,
        "vo2_samples": Array<Vo2MaxSample>,
        "vo2max_ml_per_min_per_kg": Number
    },
    "metadata": {
        "end_time": String,
        "start_time": String
    },
    "hydration_data": {
        "hydration_amount_samples": Array<HydrationLevelSample>,
        "hydration_level_samples": Array<HydrationMeasurementSample>,
        "day_total_water_consumption_ml": Number
    },
    "device_data": {
        "name": String,
        "other_devices": Array<OtherDeviceData>,
        "hardware_version": String,
        "manufacturer": String,
        "software_version": String,
        "activation_timestamp": String,
        "sensor_state": String,
        "serial_number": String,
      	"last_upload_date": String
    },
    "blood_pressure_data": {
        "blood_pressure_samples": Array<BloodPressureSample>
    },
    "temperature_data": {
        "body_temperature_samples": Array<TemperatureSample>,
        "ambient_temperature_samples": Array<TemperatureSample>,
        "skin_temperature_samples": Array<TemperatureSample>
    },
    "measurements_data": {
        "measurements": Array<MeasurementDataSample>
    },
    "heart_data": {
        "afib_classification_samples": Array<AFibClassificationSample>,
        "ecg_signal": Array<ECGReading>,
      	"rr_interval_samples": Array<RRInterval>,
        "heart_rate_data": {
            "summary": {
                "max_hr_bpm": Number,
                "resting_hr_bpm": Number,
                "avg_hrv_rmssd": Number,
                "min_hr_bpm": Number,
                "user_max_hr_bpm": Number,
                "avg_hrv_sdnn": Number,
                "avg_hr_bpm": Number
            },
            "detailed": {
                "hr_samples": Array<HeartRateDataSample>,
                "hrv_samples_sdnn": Array<HeartRateVariabilityDataSampleSDNN>,
                "hrv_samples_rmssd": Array<HeartRateVariabilityDataSampleRMSSD>
            }
        },
        "pulse_wave_velocity_samples": Array<PulseVelocitySample>
    },
    "glucose_data": {
        "blood_glucose_samples": Array<GlucoseDataSample>,
        "detailed_blood_glucose_samples": Array<GlucoseDataSample>,
        "day_avg_blood_glucose_mg_per_dL": Number,
      	"gmi": Number,
      	"time_in_range": Number,
      	"sensor_usage": Number,
      	"daily_patterns": Array<DailyPatternSample>,
    }
}

Daily

{
    "oxygen_data": {
        "saturation_samples": Array<OxygenSaturationSample>,
        "avg_saturation_percentage": Number,
        "vo2_samples": Array<Vo2MaxSample>,
        "vo2max_ml_per_min_per_kg": Number
    },
  	"stress_data": {
      "stress_duration_seconds": Number,
      "rest_stress_duration_seconds": Number,
      "activity_stress_duration_seconds": Number,
			"low_stress_duration_seconds": Number,
			"medium_stress_duration_seconds": Number,
			"high_stress_duration_seconds": Number,
			"avg_stress_level": Number,
			"max_stress_level": Number,
			"stress_rating": Number,
			"samples": Array<StressSample>,
    },
    "metadata": {
        "end_time": String,
        "start_time": String,
        "upload_type": UploadType
    },
    "tag_data": {
        "tags": Array<TagEntry>,
    },
    "device_data": {
        "name": String,
        "other_devices": Array<OtherDeviceData>,
        "hardware_version": String,
        "manufacturer": String,
        "software_version": String,
        "activation_timestamp": String,
        "serial_number": String,
      	"last_upload_date": String
    },
    "scores": {
      "recovery": Number,
      "activity": Number,
      "sleep": Number,
    }
    "distance_data": {
        "swimming": {
            "num_strokes": Number,
            "num_laps": Number,
            "pool_length_meters": Number
        },
        "floors_climbed": Number,
        "elevation": {
            "loss_actual_meters": Number,
            "min_meters": Number,
            "avg_meters": Number,
            "gain_actual_meters": Number,
            "max_meters": Number,
            "gain_planned_meters": Number
        },
        "steps": Number,
        "detailed": {
            "step_samples": Array<StepSample>,
            "distance_samples": Array<DistanceSample>,
            "elevation_samples": Array<ElevationSample>
          	"floors_climbed_samples": Array<FloorsClimbedSample>
        },
        "distance_meters": Number
    },
    "MET_data": {
        "MET_samples": Array<METSample>,
        "num_low_intensity_minutes": Number,
        "num_high_intensity_minutes": Number,
        "num_inactive_minutes": Number,
        "num_moderate_intensity_minutes": Number,
        "avg_level": Number
    },
    "calories_data": {
        "net_intake_calories": Number,
        "BMR_calories": Number,
        "total_burned_calories": Number,
        "net_activity_calories": Number,
        "calorie_samples": Array<CalorieSample>
    },
    "heart_rate_data": {
        "summary": {
            "max_hr_bpm": Number,
            "resting_hr_bpm": Number,
            "avg_hrv_rmssd": Number,
            "min_hr_bpm": Number,
            "user_max_hr_bpm": Number,
            "avg_hrv_sdnn": Number,
            "avg_hr_bpm": Number
        },
        "detailed": {
            "hr_samples": Array<HeartRateDataSample>,
            "hrv_samples_sdnn": Array<HeartRateVariabilityDataSampleSDNN>,
            "hrv_samples_rmssd": Array<HeartRateVariabilityDataSampleRMSSD>
    		}
    },
    "active_durations_data": {
        "activity_seconds": Number,
        "rest_seconds": Number,
        "low_intensity_seconds": Number,
        "activity_levels_samples": Array<ActivityLevelSample>,
        "vigorous_intensity_seconds": Number,
        "num_continuous_inactive_periods": Number,
        "inactivity_seconds": Number,
        "moderate_intensity_seconds": Number,
      	"standing_seconds": Number,
      	"standing_hours_count": Number
    },
    "stress_data": {
        "rest_stress_duration_seconds": Number,
        "stress_duration_seconds": Number,
        "activity_stress_duration_seconds": Number,
        "avg_stress_level": StressLevel,
        "low_stress_duration_seconds": Number,
        "medium_stress_duration_seconds": Number,
        "samples": Array<StressSample>,
      	"body_battery_samples": Array<BodyBatterySample>,
        "high_stress_duration_seconds": Number,
        "max_stress_level": StressLevel
    }
}

Menstruation

{
    "metadata": {
        "end_time": String,
        "start_time": String
    },
    "menstruation_data": {
        "period_length_days": Number,
        "current_phase": MenstruationFlow,
        "length_of_current_phase_days": Number,
        "days_until_next_phase": Number,
        "period_start_date": String,
        "predicted_cycle_length_days": Number,
        "day_in_cycle": Number,
        "last_updated_time": String,
        "cycle_length_days": Number,
        "is_predicted_cycle": String,
				"menstruation_flow": Array<MenstruationFlow>
    }
}

Nutrition

{
    "metadata": {
        "end_time": String,
        "start_time": String
    },
    "summary": {
        "macros": {
            "fat_g": Number,
            "trans_fat_g": Number,
            "fiber_g": Number,
            "carbohydrates_g": Number,
            "protein_g": Number,
            "cholesterol_mg": Number,
            "sodium_mg": Number,
            "calories": Number,
            "sugar_g": Number,
            "alcohol_g": Number
        },
        "micros": {
            "selenium_mg": Number,
            "niacin_mg": Number,
            "magnesium_mg": Number,
            "copper_mg": Number,
            "vitamin_B12_mg": Number,
            "vitamin_B6_mg": Number,
            "vitamin_C_mg": Number,
            "zinc_mg": Number,
            "vitamin_E_mg": Number,
            "manganese_mg": Number,
            "vitamin_D_mg": Number,
            "iodine_mg": Number,
            "chloride_mg": Number,
            "folate_mg": Number,
            "calcium_mg": Number,
            "molybdenum_mg": Number,
            "vitamin_A_mg": Number,
            "riboflavin_mg": Number,
            "folic_acid_mg": Number,
            "iron_mg": Number,
            "thiamin_mg": Number,
            "pantothenic_acid_mg": Number,
            "caffeine_mg": Number,
            "vitamin_K_mg": Number,
            "chromium_mg": Number,
            "potassium_mg": Number,
            "biotin_mg": Number,
            "phosphorus_mg": Number
        },
        "water_ml": Number
    },
    "meals": Array<Meal>
}

Sleep

{
    "sleep_durations_data": {
        "other": {
            "duration_in_bed_seconds": Number,
            "duration_unmeasurable_sleep_seconds": Number
        },
        "sleep_efficiency": Number,
        "hypnogram_samples": Array<SleepHypnogramSample>,
        "awake": {
            "duration_short_interruption_seconds": Number,
            "duration_awake_state_seconds": Number,
            "duration_long_interruption_seconds": Number,
            "num_wakeup_events": Number,
            "wake_up_latency_seconds": Number,
            "num_out_of_bed_events": Number,
            "sleep_latency_seconds": Number
        },
        "asleep": {
            "duration_light_sleep_state_seconds": Number,
            "duration_asleep_state_seconds": Number,
            "num_REM_events": Number,
            "duration_REM_sleep_state_seconds": Number,
            "duration_deep_sleep_state_seconds": Number
        }
    },
    "device_data": {
        "name": String,
        "other_devices": Array<OtherDeviceData>,
        "hardware_version": String,
        "manufacturer": String,
        "software_version": String,
        "activation_timestamp": String,
        "serial_number": String
    },
    "metadata": {
        "end_time": String,
        "start_time": String,
        "upload_type": SleepUploadType,
        "summary_id": String
    },
    "heart_rate_data": {
        "summary": {
            "max_hr_bpm": Number,
            "avg_hrv_rmssd": Number,
            "min_hr_bpm": Number,
            "user_max_hr_bpm": Number,
            "avg_hr_bpm": Number,
            "avg_hrv_sdnn": Number,
            "resting_hr_bpm": Number
        },
        "detailed": {
            "hr_samples": Array<HeartRateDataSample>,
            "hrv_samples_sdnn": Array<HeartRateVariabilityDataSampleSDNN>,
            "hrv_samples_rmssd": Array<HeartRateVariabilityDataSampleRMSSD>
        }
    },
    "temperature_data": {
        "delta": Number
    },
    "readiness_data": {
        "readiness": Number,
        "recovery_level": RecoveryLevel
    },
    "respiration_data": {
        "breaths_data": {
            "min_breaths_per_min": Number,
            "avg_breaths_per_min": Number,
            "max_breaths_per_min": Number,
            "on_demand_reading": Boolean,
            "end_time": String,
            "samples": Array<BreathSample>,
            "start_time": String
        },
        "snoring_data": {
            "num_snoring_events": Number,
            "total_snoring_duration_seconds": Number,
            "end_time": String,
            "samples": Array<SnoringSample>,
            "start_time": String
        },
        "oxygen_saturation_data": {
            "start_time": String,
            "end_time": String,
            "avg_saturation_percentage": Number,
            "samples": Array<OxygenSaturationSample>
        }
    }
}

Enums

DeviceDataType

Represents data types that a certain device contributed to

Name	Value
Steps	STEPS
Active minutes	ACTIVE_MINUTES
BMR	BMR
Calories	CALORIES
Distance	DISTANCE
Heart Rate	HEART_RATE
Oxygen Saturation (SpO2)	OXYGEN_SATURATION
Sleep type classification	SLEEP_TYPE
Speed	SPEED
Cadence	CADENCE

AFibFlag

Name	Value
Negative (AFib not present)	0
Positive (AFib present)	1
Inconclusive	2

ActivityType

Name	Value
In Vehicle	0
Biking	1
Still	3
Unknown	4
Tilting	5
Walking	7
Running	8
Aerobics	9
Badminton	10
Baseball	11
Basketball	12
Biathlon	13
Handbiking	14
Mountain Biking	15
Road Biking	16
Spinning	17
Stationary Biking	18
Utility Biking	19
Boxing	20
Calisthenics	21
Circuit Training	22
Cricket	23
Dancing	24
Elliptical	25
Fencing	26
American Football	27
Australian Football	28
English Football	29
Frisbee	30
Gardening	31
Golf	32
Gymnastics	33
Handball	34
Hiking	35
Hockey	36
Horseback Riding	37
Housework	38
Jumping Rope	39
Kayaking	40
Kettlebell Training	41
Kickboxing	42
Kitesurfing	43
Martial Arts	44
Meditation	45
Mixed Martial Arts	46
P90X Exercises	47
Paragliding	48
Pilates	49
Polo	50
Racquetball	51
Rock Climbing	52
Rowing	53
Rowing Machine	54
Rugby	55
Jogging	56
Running On Sand	57
Treadmill Running	58
Sailing	59
Scuba Diving	60
Skateboarding	61
Skating	62
Cross Skating	63
Indoor Rollerblading	64
Skiing	65
Back Country Skiing	66
Cross Country Skiing	67
Downhill Skiing	68
Kite Skiing	69
Roller Skiing	70
Sledding	71
Snowboarding	73
Snowmobile	74
Snowshoeing	75
Squash	76
Stair Climbing	77
Stair Climbing Machine	78
Stand Up Paddleboarding	79
Strength Training	80
Surfing	81
Swimming	82
Swimming In Pool	83
Open Water Swimming	84
Table Tennis	85
Team Sport	86
Tennis	87
Treadmill	88
Volleyball	89
Beach Volleyball	90
Indoor Volleyball	91
Wakeboarding	92
Walking Fitness	93
Nording Walking	94
Walking Treadmill	95
Waterpolo	96
Weightlifting	97
Wheelchair	98
Windsurfing	99
Yoga	100
Zumba	101
Diving	102
Ergometer	103
Ice Skating	104
Indoor Skating	105
Curling	106
Other	108
Crossfit	113
HIIT	114
Interval Training	115
Walkin Stroller	116
Elevator	117
Escalator	118
Archery	119
Softball	120
Guided Breathing	122
Cardio Training	123
Lacrosse	124
Stretching	125
Triathlon	126
INLINE_SKATING	127
SKY_DIVING	128
PADDLING	129
MOUNTAINEERING	130
FISHING	131
WATER_SKIING	132
INDOOR_RUNNING	133
PADEL_TENNIS	134
DRIVING	135
OFF_ROAD_DRIVING	136
MOTORBIKING	137
MOTOR_RACING	138
ENDURO	139
CANOEING	140
ORIENTEERING	141
HANG_GLIDING	142
FLYING	143
HOT_AIR_BALLOONING	144
JET_SKIING	145
POWER_BOATING	146
GAELIC_FOOTBALL	147
HURLING	148

ActivityLevel

Name	Value
Unknown	0
Rest	1
Inactive	2
Low Intensity	3
Medium Intensity	4
High Intensity	5

HeartRateZone

Name	Value
Zone 0	0
Zone 1	1
Zone 2	2
Zone 3	3
Zone 4	4
Zone 5	5
Other/custom classification	6

SleepLevel

Name	Value
Unknown	0
Awake	1
Sleeping	2
Out of Bed	3
Light	4
Deep	5
REM	6

UploadType

Name	Value
Unknown	0
Automatic	1
Manual	2
Update	3
Delete	4
Pending	5
Third party upload	6

SleepUploadType

Name	Value
Unknown	0
Manual	1
Automatic	2
Tentative	3
Indeterminate	4

StrokeType

Name	Value
OTHER	other
FREESTYLE	freestyle
BACKSTROKE	backstroke
BREASTSTROKE	breaststroke
BUTTERFLY	butterfly

GlucoseFlag

Name	Value
Normal	0
High	1
Low	2

NutritionUnits

Name	Value
Unknown	0
Gram	1
Teaspoon	2
Tablespoon	3
Cup	4
Medium Egg	5
Large Egg	6
Small Egg	7
Milliliter	8
Ounce	9
Count	10
Scoop	11
Fluid Ounce	12

RecoveryLevel

Name	Value
Unknown	0
Very Poor	1
Poor	2
Compromised	3
Ok	4
Good	5
Very Good	6

TrendArrow

Name	Value
UNKNOWN	0
FALLING_QUICKLY	1
FALLING	2
FLAT	3
RISING	4
RISING_QUICKLY	5

MenstruationFlow

Name	Value
UNKNOWN	0
NONE	1
LIGHT	2
MEDIUM	3
HEAVY	4
HAD	5

MealType

Name	Value
UNKNOWN	0
BREAKFAST	1
MORNING_SNACK	2
LUNCH	3
AFTERNOON_SNACK	4
DINNER	5
SNACK	6

StressLevel

Name	Value
NOT_ENOUGH_DATA	-1
REST	1 - 25
LOW	26 - 50
MEDIUM	51 - 75
HIGH	76 - 100

HeartRateContext

Name	Value
NOT_SET	0
ACTIVE	1
NOT_ACTIVE	2

MenstrualPhase

Name	Value
MENSTRUAL	menstrual
FOLLICULAR	follicular
OVULATION	ovulation
LUTEAL	luteal
PMS	pms
FERTILE	fertile
FIRST_TRIMESTER	first_trimester
SECOND_TRIMESTER	second_trimester
THIRD_TRIMESTER	third_trimester
UNKNOWN	unknown