REST API Endpoints

🕸️ API info

🔌 Authentication

💁‍♂️ User info

⏳ Historical Data retrieval

✏️ Writing data

PreviousSupported integrations NextEvent Types

Was this helpful?

Get list of available integrations

get

/integrations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/integrations'

200

{
  "status": "success",
  "providers": [
    "FITBIT"
  ],
  "sdk_resource": [
    "APPLE"
  ]
}

Returns list of all available integrations on the API

Get detailed list of integrations

Retrieve a detailed list of supported integrations, optionally filtered by the developer's enabled integrations and the requirement for SDK usage.

get

/integrations/detailed

Query parameters

sdkboolean

If true, allows SDK integrations to be included in the response.

Header parameters

dev-idstring

Developer ID to filter the integrations list based on the developer's enabled integrations.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/integrations/detailed'

200

{
  "status": "success",
  "providers": [
    {
      "provider": "MAPMYFITNESS",
      "name": "MapMyFitness",
      "icon": "https://api.tryterra.co/v2/static/assets/img/app_icons/mapmyfitness.webp",
      "setup": "API_KEYS_MANAGED",
      "enabled": true,
      "types": {
        "activity": true,
        "body": false,
        "nutrition": false,
        "daily": false,
        "sleep": false,
        "menstruation": false
      }
    }
  ]
}

Successful response containing a list of integrations.

Generate an authentication link

Creates a login link that allows end users to connect their fitness tracking account

post

/auth/authenticateUser

Authorizations

Query parameters

resourcestringrequired

resource to authenticate user with

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Body

languagestring

reference_idstring

auth_success_redirect_urlstring

auth_failure_redirect_urlstring

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.tryterra.co/v2/auth/authenticateUser?resource=text' \
  --header 'x-api-key: text' \
  --header 'dev-id: text' \
  --header 'Content-Type: application/json'

200

400

404

{
  "user_id": "23dc2540-7139-44c6-8158-f81196e2cf2e",
  "auth_url": "https://www.fitbit.com/oauth2/authorize?response_type=code&client_id=23BBG9&scope=settings+nutrition+sleep+heartrate+electrocardiogram+weight+respiratory_rate+oxygen_saturation+profile+temperature+cardio_fitness+activity+location&state=bLqqjPie9ptwoWm6VBxHCu6JkkoWJp",
  "status": "success"
}

Returned when authentication link could be successfully generated

Generate an authentication link, using the Terra Authentication Widget

Generates a link to redirect an end user to for them to select an integration and log in with their fitness data provider

post

/auth/generateWidgetSession

Authorizations

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Body

providersstring

Comma separated list of providers to display on the device selection page. This overrides your selected sources on your dashboard

Example: GARMIN,FITBIT,OURA,WITHINGS,SUUNTO

languagestring

Display language of the widget

Example: en

reference_idstring

Identifier of the end user on your system, such as a user ID or email associated with them

Example: [email protected]

auth_success_redirect_urlstring

URL the user is redirected to upon successful authentication

Example: https://myapp.com/success

auth_failure_redirect_urlstring

URL the user is redirected to upon unsuccessful authentication

Example: https://myapp.com/failure

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.tryterra.co/v2/auth/generateWidgetSession' \
  --header 'x-api-key: text' \
  --header 'dev-id: text' \
  --header 'Content-Type: application/json' \
  --data '{"providers":"GARMIN,FITBIT,OURA,WITHINGS,SUUNTO","language":"en","reference_id":"[email protected]","auth_success_redirect_url":"https://myapp.com/success","auth_failure_redirect_url":"https://myapp.com/failure"}'

200

400

{
  "session_id": "23dc2540-7139-44c6-8158-f81196e2cf2e",
  "url": "https://widget.tryterra.co/session/344d475f-296a-489a-a88c-54183671dafd",
  "expires_in": 900,
  "status": "success"
}

Returned when authentication link could be successfully generated

Deauthenticates a user and deletes any cached data for them

Deletes all records of the user on Terra's end, revoking Terra's access to their data

delete

/auth/deauthenticateUser

Authorizations

Query parameters

user_idstringrequired

user_id to deauthenticate for

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.tryterra.co/v2/auth/deauthenticateUser?user_id=text' \
  --header 'x-api-key: text' \
  --header 'dev-id: text'

200

404

{
  "status": "success"
}

Returned when authentication link could be successfully generated

Used to query for information on one Terra user ID, or to query for all registered Terra User objects under one reference ID

get

/userInfo

Authorizations

Query parameters

user_idstring

user ID to query for

reference_idstring

reference ID to query for

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/userInfo' \
  --header 'x-api-key: text' \
  --header 'dev-id: text'

200

400

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "is_authenticated": true,
  "status": "success"
}

Returned when the provided resources are found

Used to query for information for multiple Terra User IDs

post

/bulkUserInfo

Authorizations

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Body

itemsstring

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.tryterra.co/v2/bulkUserInfo' \
  --header 'x-api-key: text' \
  --header 'dev-id: text' \
  --header 'Content-Type: application/json' \
  --data '[null]'

200

400

404

[
  {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  }
]

Returned upon successful request

Retrieve user profile info for a given user ID

Fetches relevant profile info such as first & last name, birth date etc. for a given user ID

get

/athlete

Authorizations

Query parameters

user_idstringrequired

user ID to query data for

to_webhookboolean

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/athlete?user_id=text' \
  --header 'x-api-key: text' \
  --header 'dev-id: text'

200

400

401

404

{
  "type": "athlete",
  "athlete": {
    "gender": "male",
    "state": "California",
    "bio": "Passionate runner and cyclist",
    "age": "28",
    "country": "United States",
    "sex": "male",
    "date_of_birth": "1999-11-23",
    "city": "San Francisco",
    "account_creation_date": "2023-01-15",
    "email": "[email protected]",
    "last_name": "Smith",
    "first_name": "John"
  },
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  }
}

Returned upon successful data request

Retrieve activity data for a given user ID

Fetches completed workout sessions, with a defined start and end time and activity type (e.g. running, cycling, etc.)

get

/activity

Authorizations

Query parameters

user_idstringrequired

user ID to query data for

start_dateone ofrequired

start date of data to query for - either ISO8601 date or unix timestamp

end_dateone of

end date of data to query for - either ISO8601 date or unix timestamp

to_webhookboolean

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

with_samplesboolean

boolean flag specifying whether to include detailed samples in the returned payload

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/activity?user_id=text&start_date=1' \
  --header 'x-api-key: text' \
  --header 'dev-id: text'

200

400

401

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "type": "text",
  "data": [
    {
      "cheat_detection": 0,
      "active_durations_data": {
        "num_continuous_inactive_periods": 3,
        "inactivity_seconds": 600,
        "vigorous_intensity_seconds": 300,
        "activity_seconds": 1800,
        "low_intensity_seconds": 900,
        "rest_seconds": 120,
        "moderate_intensity_seconds": 600,
        "activity_levels_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "activity_level": "MEDIUM_INTENSITY"
          }
        ]
      },
      "lap_data": {
        "laps": [
          {
            "calories": 50,
            "avg_hr_bpm": 145,
            "start_time": "1999-11-23T09:00:00.000000+02:00",
            "avg_speed_meters_per_second": 3.5,
            "distance_meters": 400,
            "total_strokes": 20,
            "end_time": "2022-10-28T10:00:00.000000+01:00",
            "stroke_type": "FREESTYLE"
          }
        ]
      },
      "polyline_map_data": {
        "summary_polyline": "}_p~iF~ps|U_ulLnnqC_mqNvxq`@"
      },
      "strain_data": {
        "strain_level": 8.5
      },
      "position_data": {
        "position_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 300,
            "coords_lat_lng_deg": [
              -18.4911,
              130.9123
            ]
          }
        ],
        "end_pos_lat_lng_deg": [
          -84.4911,
          -150.9123
        ],
        "center_pos_lat_lng_deg": [
          -18.4911,
          130.9123
        ],
        "start_pos_lat_lng_deg": [
          80.2394,
          102.931
        ]
      },
      "movement_data": {
        "max_pace_minutes_per_kilometer": 6.5,
        "adjusted_max_speed_meters_per_second": 4.2,
        "avg_velocity_meters_per_second": 3,
        "max_velocity_meters_per_second": 4.5,
        "avg_speed_meters_per_second": 3.2,
        "avg_torque_newton_meters": 40,
        "max_speed_meters_per_second": 4.5,
        "avg_pace_minutes_per_kilometer": 6.2,
        "avg_cadence_rpm": 85,
        "max_torque_newton_meters": 55.5,
        "normalized_speed_meters_per_second": 3.8,
        "max_cadence_rpm": 110,
        "cadence_samples": [
          {
            "timer_duration_seconds": 300,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "cadence_rpm": 85
          }
        ],
        "torque_samples": [
          {
            "torque_newton_meters": 45.5,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 300
          }
        ],
        "speed_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 300,
            "speed_meters_per_second": 3.5
          }
        ]
      },
      "oxygen_data": {
        "vo2max_ml_per_min_per_kg": 42.5,
        "avg_saturation_percentage": 97,
        "vo2_samples": [
          {
            "vo2max_ml_per_min_per_kg": 45.5,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "saturation_samples": [
          {
            "percentage": 98,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "type": 0
          }
        ]
      },
      "device_data": {
        "manufacturer": "Garmin",
        "hardware_version": "v2.1",
        "activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
        "serial_number": "GR123456789",
        "name": "Forerunner 945",
        "software_version": "5.2.1",
        "other_devices": [
          {
            "manufacturer": "Garmin",
            "hardware_version": "v2.1",
            "serial_number": "GR123456789",
            "name": "Forerunner 945",
            "software_version": "5.2.1"
          }
        ]
      },
      "energy_data": {
        "energy_planned_kilojoules": 1200,
        "energy_kilojoules": 1150
      },
      "MET_data": {
        "num_inactive_minutes": 5,
        "num_low_intensity_minutes": 15,
        "num_moderate_intensity_minutes": 25,
        "avg_level": 3.8,
        "num_high_intensity_minutes": 10,
        "MET_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "level": 4.2
          }
        ]
      },
      "power_data": {
        "avg_watts": 185,
        "max_watts": 350,
        "power_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 1800,
            "watts": 250
          }
        ]
      },
      "distance_data": {
        "summary": {
          "distance_meters": 5000,
          "steps": 6500,
          "floors_climbed": 10,
          "elevation": {
            "gain_planned_meters": 500,
            "loss_actual_meters": 450,
            "max_meters": 1200,
            "min_meters": 800,
            "gain_actual_meters": 550,
            "avg_meters": 950
          },
          "swimming": {
            "num_laps": 20,
            "num_strokes": 500,
            "pool_length_meters": 25
          }
        },
        "detailed": {
          "elevation_samples": [
            {
              "elev_meters": 925,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 1200
            }
          ],
          "distance_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "distance_meters": 2500,
              "timer_duration_seconds": 900
            }
          ],
          "floors_climbed_samples": [
            {
              "floors_climbed": 5,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 600
            }
          ],
          "step_samples": [
            {
              "steps": 3250,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 900
            }
          ]
        }
      },
      "heart_rate_data": {
        "summary": {
          "resting_hr_bpm": 65,
          "avg_hr_bpm": 145,
          "max_hr_bpm": 180,
          "avg_hrv_sdnn": 45.5,
          "min_hr_bpm": 85,
          "avg_hrv_rmssd": 35.2,
          "user_max_hr_bpm": 190,
          "hr_zone_data": [
            {
              "start_percentage": 60,
              "end_percentage": 70,
              "duration_seconds": 300,
              "name": "Aerobic",
              "zone": "ZONE_2"
            }
          ]
        },
        "detailed": {
          "hrv_samples_rmssd": [
            {
              "hrv_rmssd": 42.1,
              "timestamp": "2022-11-23T09:00:00.000000+02:00"
            }
          ],
          "hr_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "bpm": 142
            }
          ],
          "hrv_samples_sdnn": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "hrv_sdnn": 48.3
            }
          ]
        }
      },
      "TSS_data": {
        "TSS_samples": [
          {
            "intensity_factor_planned": 0.85,
            "intensity_factor_actual": 0.82,
            "normalized_power_watts": 225,
            "planned": 85,
            "actual": 82,
            "method": "HeartRate"
          }
        ]
      },
      "calories_data": {
        "BMR_calories": 1800,
        "net_activity_calories": 450,
        "total_burned_calories": 2250,
        "net_intake_calories": 200,
        "calorie_samples": [
          {
            "calories": 450,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 1800
          }
        ]
      },
      "metadata": {
        "state": "California",
        "country": "United States",
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "summary_id": "123e4567-e89b-12d3-a456-426614174000",
        "city": "San Francisco",
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "name": "Morning Run",
        "type": "RUNNING",
        "upload_type": "UNKNOWN",
        "timestamp_localization": 0
      },
      "work_data": {
        "work_kilojoules": 450.5
      }
    }
  ]
}

Returned upon successful data request

Retrieve body metrics for a given user ID

Fetches body metrics such as weight, height, body fat percentage etc. for a given user ID

get

/body

Authorizations

Query parameters

user_idstringrequired

user ID to query data for

start_dateone ofrequired

start date of data to query for - either ISO8601 date or unix timestamp

end_dateone of

end date of data to query for - either ISO8601 date or unix timestamp

to_webhookboolean

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

with_samplesboolean

boolean flag specifying whether to include detailed samples in the returned payload

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/body?user_id=text&start_date=1' \
  --header 'x-api-key: text' \
  --header 'dev-id: text'

200

400

401

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "type": "text",
  "data": [
    {
      "measurements_data": {
        "measurements": [
          {
            "weight_kg": 75.5,
            "bodyfat_percentage": 18.5,
            "BMI": 22.4,
            "water_percentage": 60.5,
            "measurement_time": "2022-11-23T09:00:00.000000+02:00",
            "lean_mass_g": 61500,
            "estimated_fitness_age": "25",
            "skin_fold_mm": 12.5,
            "height_cm": 178,
            "bone_mass_g": 3200,
            "insulin_units": 10.5,
            "muscle_mass_g": 35000,
            "BMR": 1800,
            "urine_color": "pale yellow",
            "RMR": 2000,
            "insulin_type": "rapid-acting"
          }
        ]
      },
      "ketone_data": {
        "ketone_samples": [
          {
            "ketone_mg_per_dL": 1.5,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "sample_type": "UNKNOWN"
          }
        ]
      },
      "hydration_data": {
        "hydration_amount_samples": 65.5,
        "day_total_water_consumption_ml": 2500
      },
      "device_data": {
        "manufacturer": "Garmin",
        "hardware_version": "v2.1",
        "activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
        "serial_number": "GR123456789",
        "name": "Forerunner 945",
        "software_version": "5.2.1",
        "other_devices": [
          {
            "manufacturer": "Garmin",
            "hardware_version": "v2.1",
            "serial_number": "GR123456789",
            "name": "Forerunner 945",
            "software_version": "5.2.1"
          }
        ]
      },
      "heart_data": {
        "pulse_wave_velocity_samples": [
          {
            "pulse_wave_velocity_meters_per_second": 7.2,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "afib_classification_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "afib_classification": "NORMAL"
          }
        ],
        "ecg_signal": [
          {
            "start_timestamp": "2022-11-23T09:00:00.000000+02:00",
            "avg_hr_bpm": 72.5,
            "afib_classfication": 1,
            "raw_signal": [
              {
                "potential_uV": 1250.5,
                "timestamp": "2022-11-23T09:00:00.000000+02:00"
              }
            ]
          }
        ],
        "rr_interval_samples": [
          {
            "rr_interval_ms": 850,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "hr_bpm": 72
          }
        ],
        "heart_rate_data": {
          "summary": {
            "resting_hr_bpm": 60,
            "avg_hr_bpm": 75,
            "max_hr_bpm": 180,
            "avg_hrv_sdnn": 45.5,
            "min_hr_bpm": 45,
            "avg_hrv_rmssd": 42.8,
            "user_max_hr_bpm": 190,
            "hr_zone_data": [
              {
                "start_percentage": 60,
                "end_percentage": 70,
                "duration_seconds": 300,
                "name": "Aerobic",
                "zone": "ZONE_2"
              }
            ]
          },
          "detailed": {
            "hrv_samples_rmssd": [
              {
                "hrv_rmssd": 42.1,
                "timestamp": "2022-11-23T09:00:00.000000+02:00"
              }
            ],
            "hr_samples": [
              {
                "timestamp": "2022-11-23T09:00:00.000000+02:00",
                "bpm": 142
              }
            ],
            "hrv_samples_sdnn": [
              {
                "timestamp": "2022-11-23T09:00:00.000000+02:00",
                "hrv_sdnn": 48.3
              }
            ]
          }
        }
      },
      "oxygen_data": {
        "vo2max_ml_per_min_per_kg": 42.5,
        "avg_saturation_percentage": 97,
        "vo2_samples": [
          {
            "vo2max_ml_per_min_per_kg": 45.5,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "saturation_samples": [
          {
            "percentage": 98,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "type": 0
          }
        ]
      },
      "glucose_data": {
        "day_avg_blood_glucose_mg_per_dL": 92.5,
        "detailed_blood_glucose_samples": [
          {
            "blood_glucose_mg_per_dL": 95,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "glucose_level_flag": "NORMAL",
            "trend_arrow": "FLAT"
          }
        ],
        "blood_glucose_samples": [
          {
            "blood_glucose_mg_per_dL": 95,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "glucose_level_flag": "NORMAL",
            "trend_arrow": "FLAT"
          }
        ]
      },
      "metadata": {
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "timestamp_localization": 0
      },
      "blood_pressure_data": {
        "blood_pressure_samples": [
          {
            "diastolic_bp": 80.5,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "systolic_bp": 120.5
          }
        ]
      },
      "temperature_data": {
        "body_temperature_samples": [
          {
            "temperature_celsius": 37.2,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "skin_temperature_samples": [
          {
            "temperature_celsius": 37.2,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "ambient_temperature_samples": [
          {
            "temperature_celsius": 37.2,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ]
      }
    }
  ]
}

Returned upon successful data request

Retrieve daily activity summaries for a given user ID

Fetches daily summaries of activity metrics such as steps, distance, calories burned etc. for a given user ID

get

/daily

Authorizations

Query parameters

user_idstringrequired

user ID to query data for

start_dateone ofrequired

start date of data to query for - either ISO8601 date or unix timestamp

end_dateone of

end date of data to query for - either ISO8601 date or unix timestamp

to_webhookboolean

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

with_samplesboolean

boolean flag specifying whether to include detailed samples in the returned payload

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/daily?user_id=text&start_date=1' \
  --header 'x-api-key: text' \
  --header 'dev-id: text'

200

400

401

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "type": "text",
  "data": [
    {
      "active_durations_data": {
        "num_continuous_inactive_periods": 3,
        "inactivity_seconds": 28800,
        "vigorous_intensity_seconds": 1800,
        "activity_seconds": 14400,
        "low_intensity_seconds": 7200,
        "rest_seconds": 28800,
        "moderate_intensity_seconds": 5400,
        "activity_levels_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "activity_level": "MEDIUM_INTENSITY"
          }
        ]
      },
      "scores": {
        "sleep": 85,
        "recovery": 78,
        "activity": 92
      },
      "strain_data": {
        "strain_level": 14.5
      },
      "stress_data": {
        "avg_stress_level": 45.5,
        "activity_stress_duration_seconds": 3600,
        "low_stress_duration_seconds": 28800,
        "max_stress_level": 85,
        "medium_stress_duration_seconds": 7200,
        "rest_stress_duration_seconds": 1800,
        "high_stress_duration_seconds": 900,
        "stress_duration_seconds": 5400,
        "samples": [
          {
            "steps": 3250,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 900
          }
        ]
      },
      "device_data": {
        "manufacturer": "Garmin",
        "hardware_version": "v2.1",
        "activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
        "serial_number": "GR123456789",
        "name": "Forerunner 945",
        "software_version": "5.2.1",
        "other_devices": [
          {
            "manufacturer": "Garmin",
            "hardware_version": "v2.1",
            "serial_number": "GR123456789",
            "name": "Forerunner 945",
            "software_version": "5.2.1"
          }
        ]
      },
      "tag_data": {
        "tags": [
          {
            "notes": "Felt refreshed after",
            "tag_name": "hot_shower",
            "timestamp": "1999-11-23T09:00:00.000000+02:00"
          }
        ]
      },
      "heart_rate_data": {
        "summary": {
          "resting_hr_bpm": 60,
          "avg_hr_bpm": 75,
          "max_hr_bpm": 180,
          "avg_hrv_sdnn": 45.5,
          "min_hr_bpm": 45,
          "avg_hrv_rmssd": 42.8,
          "user_max_hr_bpm": 190,
          "hr_zone_data": [
            {
              "start_percentage": 60,
              "end_percentage": 70,
              "duration_seconds": 300,
              "name": "Aerobic",
              "zone": "ZONE_2"
            }
          ]
        },
        "detailed": {
          "hrv_samples_rmssd": [
            {
              "hrv_rmssd": 42.1,
              "timestamp": "2022-11-23T09:00:00.000000+02:00"
            }
          ],
          "hr_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "bpm": 142
            }
          ],
          "hrv_samples_sdnn": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "hrv_sdnn": 48.3
            }
          ]
        }
      },
      "MET_data": {
        "num_inactive_minutes": 480,
        "num_low_intensity_minutes": 720,
        "num_moderate_intensity_minutes": 180,
        "avg_level": 1.8,
        "num_high_intensity_minutes": 60,
        "MET_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "level": 4.2
          }
        ]
      },
      "distance_data": {
        "distance_meters": 8500,
        "steps": 12000,
        "floors_climbed": 15,
        "detailed": {
          "elevation_samples": [
            {
              "elev_meters": 925,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 1200
            }
          ],
          "distance_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "distance_meters": 2500,
              "timer_duration_seconds": 900
            }
          ],
          "floors_climbed_samples": [
            {
              "floors_climbed": 5,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 600
            }
          ],
          "step_samples": [
            {
              "steps": 3250,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 900
            }
          ]
        },
        "elevation": {
          "gain_planned_meters": 150,
          "loss_actual_meters": 120,
          "max_meters": 450,
          "min_meters": 300,
          "gain_actual_meters": 130,
          "avg_meters": 375
        },
        "swimming": {
          "num_laps": 20,
          "num_strokes": 500,
          "pool_length_meters": 25
        }
      },
      "oxygen_data": {
        "vo2max_ml_per_min_per_kg": 45.5,
        "avg_saturation_percentage": 98,
        "vo2_samples": [
          {
            "vo2max_ml_per_min_per_kg": 45.5,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "saturation_samples": [
          {
            "percentage": 98,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "type": 0
          }
        ]
      },
      "calories_data": {
        "BMR_calories": 1800,
        "net_activity_calories": 500,
        "total_burned_calories": 2300,
        "net_intake_calories": 2000,
        "calorie_samples": [
          {
            "calories": 450,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 1800
          }
        ]
      },
      "metadata": {
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "upload_type": "UNKNOWN",
        "timestamp_localization": 0
      }
    }
  ]
}

Returned upon successful data request

Retrieve menstruation data for a given user ID

Fetches menstruation data such as cycle length, period length, ovulation date etc. for a given user ID

get

/menstruation

Authorizations

Query parameters

user_idstringrequired

user ID to query data for

start_dateone ofrequired

start date of data to query for - either ISO8601 date or unix timestamp

end_dateone of

end date of data to query for - either ISO8601 date or unix timestamp

to_webhookboolean

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

with_samplesboolean

boolean flag specifying whether to include detailed samples in the returned payload

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/menstruation?user_id=text&start_date=1' \
  --header 'x-api-key: text' \
  --header 'dev-id: text'

200

400

401

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "type": "text",
  "data": [
    {
      "metadata": {
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "timestamp_localization": 0
      },
      "menstruation_data": {
        "length_of_current_phase_days": 5,
        "period_length_days": 5,
        "cycle_length_days": "28",
        "days_until_next_phase": 23,
        "is_predicted_cycle": "true",
        "last_updated_time": "2022-12-12T14:03:05.000000-05:00",
        "current_phase": 1,
        "period_start_date": "2022-11-28",
        "predicted_cycle_length_days": 28,
        "day_in_cycle": 24,
        "menstruation_flow": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "flow": "UNKNOWN"
          }
        ]
      }
    }
  ]
}

Returned upon successful data request

Retrieve nutrition log data for a given user ID

Fetches nutrition log data such as meal type, calories, macronutrients etc. for a given user ID

get

/nutrition

Authorizations

Query parameters

user_idstringrequired

user ID to query data for

start_dateone ofrequired

start date of data to query for - either ISO8601 date or unix timestamp

end_dateone of

end date of data to query for - either ISO8601 date or unix timestamp

to_webhookboolean

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

with_samplesboolean

boolean flag specifying whether to include detailed samples in the returned payload

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/nutrition?user_id=text&start_date=1' \
  --header 'x-api-key: text' \
  --header 'dev-id: text'

200

400

401

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "type": "text",
  "data": [
    {
      "drink_samples": [
        {
          "drink_unit": "ml",
          "timestamp": "2022-11-23T09:00:00.000000+02:00",
          "drink_name": "Water",
          "drink_volume": "250"
        }
      ],
      "meals": [
        {
          "id": "food_123",
          "timestamp": "2022-12-12T08:53:00.000000+02:00",
          "name": "Oatmeal",
          "type": "BREAKFAST",
          "micros": {
            "iron_mg": 8.5,
            "magnesium_mg": 320,
            "vitamin_A_mg": 0.9,
            "vitamin_B12_mg": 0.0024,
            "biotin_mg": 0.03,
            "cystine_g": 0.3,
            "phenylalanine_g": 0.9,
            "chloride_mg": 2300,
            "vitamin_D3_mg": 0.015,
            "isoleucine_g": 0.8,
            "calcium_mg": 1000,
            "iodine_mg": 0.15,
            "histidine_g": 0.6,
            "chromium_mg": 0.035,
            "vitamin_K_mg": 0.12,
            "manganese_mg": 2.3,
            "folic_acid_mg": 0.4,
            "leucine_g": 1.2,
            "caffeine_mg": 95,
            "potassium_mg": 3500,
            "molybdenum_mg": 0.045,
            "lysine_g": 0.9,
            "tyrosine_g": 0.7,
            "valine_g": 0.8,
            "omega6_g": 17,
            "omega3_g": 1.6,
            "vitamin_C_mg": 90,
            "zinc_mg": 11,
            "vitamin_D2_mg": 0.01,
            "vitamin_E_mg": 15,
            "pantothenic_acid_mg": 5,
            "riboflavin_mg": 1.3,
            "phosphorus_mg": 1000,
            "vitamin_D_mg": 0.02,
            "tryptophan_g": 0.3,
            "niacin_mg": 16,
            "copper_mg": 0.9,
            "threonine_g": 0.5,
            "monounsaturated_fat_g": 15,
            "folate_mg": 0.4,
            "selenium_mg": 0.055,
            "vitamin_B6_mg": 1.7,
            "thiamin_mg": 1.2,
            "polyunsaturated_fat_g": 13,
            "methionine_g": 0.6,
            "starch_g": 25
          },
          "quantity": {
            "unit": "grams",
            "amount": 100
          },
          "macros": {
            "fiber_g": 25,
            "calories": 2000,
            "fat_g": 65,
            "sodium_mg": 2300,
            "alcohol_g": 14,
            "trans_fat_g": 2,
            "carbohydrates_g": 300,
            "protein_g": 50,
            "saturated_fat_g": 20,
            "sugar_g": 25,
            "cholesterol_mg": 300,
            "net_carbohydrates_g": 275
          }
        }
      ],
      "summary": {
        "water_ml": 2000,
        "micros": {
          "iron_mg": 8.5,
          "magnesium_mg": 320,
          "vitamin_A_mg": 0.9,
          "vitamin_B12_mg": 0.0024,
          "biotin_mg": 0.03,
          "cystine_g": 0.3,
          "phenylalanine_g": 0.9,
          "chloride_mg": 2300,
          "vitamin_D3_mg": 0.015,
          "isoleucine_g": 0.8,
          "calcium_mg": 1000,
          "iodine_mg": 0.15,
          "histidine_g": 0.6,
          "chromium_mg": 0.035,
          "vitamin_K_mg": 0.12,
          "manganese_mg": 2.3,
          "folic_acid_mg": 0.4,
          "leucine_g": 1.2,
          "caffeine_mg": 95,
          "potassium_mg": 3500,
          "molybdenum_mg": 0.045,
          "lysine_g": 0.9,
          "tyrosine_g": 0.7,
          "valine_g": 0.8,
          "omega6_g": 17,
          "omega3_g": 1.6,
          "vitamin_C_mg": 90,
          "zinc_mg": 11,
          "vitamin_D2_mg": 0.01,
          "vitamin_E_mg": 15,
          "pantothenic_acid_mg": 5,
          "riboflavin_mg": 1.3,
          "phosphorus_mg": 1000,
          "vitamin_D_mg": 0.02,
          "tryptophan_g": 0.3,
          "niacin_mg": 16,
          "copper_mg": 0.9,
          "threonine_g": 0.5,
          "monounsaturated_fat_g": 15,
          "folate_mg": 0.4,
          "selenium_mg": 0.055,
          "vitamin_B6_mg": 1.7,
          "thiamin_mg": 1.2,
          "polyunsaturated_fat_g": 13,
          "methionine_g": 0.6,
          "starch_g": 25
        },
        "macros": {
          "fiber_g": 25,
          "calories": 2000,
          "fat_g": 65,
          "sodium_mg": 2300,
          "alcohol_g": 14,
          "trans_fat_g": 2,
          "carbohydrates_g": 300,
          "protein_g": 50,
          "saturated_fat_g": 20,
          "sugar_g": 25,
          "cholesterol_mg": 300,
          "net_carbohydrates_g": 275
        }
      },
      "metadata": {
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "timestamp_localization": 0
      }
    }
  ]
}

Returned upon successful data request

Retrieve sleep sessions for a given user ID

Fetches sleep data such as sleep duration, sleep stages, sleep quality etc. for a given user ID, for sleep sessions with a defined start and end time

get

/sleep

Authorizations

Query parameters

user_idstringrequired

user ID to query data for

start_dateone ofrequired

start date of data to query for - either ISO8601 date or unix timestamp

end_dateone of

end date of data to query for - either ISO8601 date or unix timestamp

to_webhookboolean

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

with_samplesboolean

boolean flag specifying whether to include detailed samples in the returned payload

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/sleep?user_id=text&start_date=1' \
  --header 'x-api-key: text' \
  --header 'dev-id: text'

200

400

401

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "type": "text",
  "data": [
    {
      "respiration_data": {
        "snoring_data": {
          "start_time": "1999-11-23T22:00:00.000000+02:00",
          "total_snoring_duration_seconds": 3600,
          "end_time": "2022-11-24T08:00:00.000000+01:00",
          "num_snoring_events": 12,
          "samples": [
            {
              "duration_seconds": 120,
              "timestamp": "2022-11-23T09:00:00.000000+02:00"
            }
          ]
        },
        "breaths_data": {
          "avg_breaths_per_min": 14,
          "max_breaths_per_min": 18,
          "start_time": "1999-11-23T22:00:00.000000+02:00",
          "min_breaths_per_min": 10,
          "on_demand_reading": false,
          "end_time": "2022-11-24T08:00:00.000000+01:00",
          "samples": [
            {
              "breaths_per_min": 16,
              "timestamp": "2022-11-23T09:00:00.000000+02:00"
            }
          ]
        },
        "oxygen_saturation_data": {
          "start_time": "1999-11-23T22:00:00.000000+02:00",
          "avg_saturation_percentage": 97,
          "end_time": "2022-11-24T08:00:00.000000+01:00",
          "samples": [
            {
              "percentage": 98,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "type": 0
            }
          ]
        }
      },
      "sleep_durations_data": {
        "sleep_efficiency": 87.5,
        "hypnogram_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "level": "UNKNOWN"
          }
        ],
        "awake": {
          "duration_short_interruption_seconds": 180,
          "duration_awake_state_seconds": 1200,
          "wake_up_latency_seconds": 300,
          "num_wakeup_events": 3,
          "duration_long_interruption_seconds": 600,
          "sleep_latency_seconds": 900,
          "num_out_of_bed_events": 1
        },
        "asleep": {
          "num_REM_events": 4,
          "duration_asleep_state_seconds": 25200,
          "duration_REM_sleep_state_seconds": 5400,
          "duration_light_sleep_state_seconds": 14400,
          "duration_deep_sleep_state_seconds": 5400
        },
        "other": {
          "duration_unmeasurable_sleep_seconds": 300,
          "duration_in_bed_seconds": 28800
        }
      },
      "device_data": {
        "manufacturer": "Garmin",
        "hardware_version": "v2.1",
        "activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
        "serial_number": "GR123456789",
        "name": "Forerunner 945",
        "software_version": "5.2.1",
        "other_devices": [
          {
            "manufacturer": "Garmin",
            "hardware_version": "v2.1",
            "serial_number": "GR123456789",
            "name": "Forerunner 945",
            "software_version": "5.2.1"
          }
        ]
      },
      "heart_rate_data": {
        "summary": {
          "resting_hr_bpm": 55,
          "avg_hr_bpm": 60,
          "max_hr_bpm": 75,
          "avg_hrv_sdnn": 45,
          "min_hr_bpm": 48,
          "avg_hrv_rmssd": 35,
          "user_max_hr_bpm": 185
        },
        "detailed": {
          "hrv_samples_rmssd": [
            {
              "hrv_rmssd": 42.1,
              "timestamp": "2022-11-23T09:00:00.000000+02:00"
            }
          ],
          "hr_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "bpm": 142
            }
          ],
          "hrv_samples_sdnn": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "hrv_sdnn": 48.3
            }
          ]
        }
      },
      "metadata": {
        "is_nap": false,
        "start_time": "1999-11-23T22:00:00.000000+02:00",
        "upload_type": 1,
        "end_time": "2022-11-24T08:00:00.000000+01:00",
        "timestamp_localization": 0
      },
      "readiness_data": {
        "readiness": 85,
        "recovery_level": 4
      },
      "temperature_data": {
        "delta": 0.5
      }
    }
  ]
}

Returned upon successful data request

Retrieve workout plans for a given user ID

Used to get workout plans the user has registered on their account. This can be stregnth workouts (sets, reps, weight lifted) or cardio workouts (warmup, intervals of different intensities, cooldown etc)

get

/plannedWorkout

Authorizations

Query parameters

user_idstringrequired

user ID to query data for

start_dateone ofrequired

start date of data to query for - either ISO8601 date or unix timestamp

end_dateone of

end date of data to query for - either ISO8601 date or unix timestamp

to_webhookboolean

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.tryterra.co/v2/plannedWorkout?user_id=text&start_date=1' \
  --header 'x-api-key: text' \
  --header 'dev-id: text'

200

400

401

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "type": "text",
  "data": [
    {
      "steps": {},
      "metadata": {
        "estimated_energy_kj": 1,
        "estimated_speed_meters_per_second": 1,
        "estimated_elevation_gain_meters": 1,
        "estimated_tss": 1,
        "estimated_calories": 1,
        "created_date": "2022-11-23T09:00:00.000000+02:00",
        "planned_date": "2022-11-24T09:00:00.000000+02:00",
        "id": null,
        "estimated_duration_seconds": 1,
        "estimated_pace_minutes_per_kilometer": 1,
        "provider": "text",
        "estimated_tscore": 1,
        "description": "text",
        "name": "text",
        "estimated_distance_meters": 1,
        "estimated_if": 1,
        "pool_length_meters": 1,
        "type": "IN_VEHICLE"
      }
    }
  ]
}

Returned upon successful data request

Used to post activity data to a provider. Available for Wahoo

post

/activity

Authorizations

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Body

dataobject[]required

List of user-tracked workouts to post to data provider

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.tryterra.co/v2/activity' \
  --header 'x-api-key: text' \
  --header 'dev-id: text' \
  --header 'Content-Type: application/json' \
  --data '{"data":[{"cheat_detection":0,"active_durations_data":{"num_continuous_inactive_periods":3,"inactivity_seconds":600,"vigorous_intensity_seconds":300,"activity_seconds":1800,"low_intensity_seconds":900,"rest_seconds":120,"moderate_intensity_seconds":600,"activity_levels_samples":[{"timestamp":"2022-11-23T09:00:00.000000+02:00","activity_level":"MEDIUM_INTENSITY"}]},"lap_data":{"laps":[{"calories":50,"avg_hr_bpm":145,"start_time":"1999-11-23T09:00:00.000000+02:00","avg_speed_meters_per_second":3.5,"distance_meters":400,"total_strokes":20,"end_time":"2022-10-28T10:00:00.000000+01:00","stroke_type":"FREESTYLE"}]},"polyline_map_data":{"summary_polyline":"}_p~iF~ps|U_ulLnnqC_mqNvxq`@"},"strain_data":{"strain_level":8.5},"position_data":{"position_samples":[{"timestamp":"2022-11-23T09:00:00.000000+02:00","timer_duration_seconds":300,"coords_lat_lng_deg":[-18.4911,130.9123]}],"end_pos_lat_lng_deg":[-84.4911,-150.9123],"center_pos_lat_lng_deg":[-18.4911,130.9123],"start_pos_lat_lng_deg":[80.2394,102.931]},"movement_data":{"max_pace_minutes_per_kilometer":6.5,"adjusted_max_speed_meters_per_second":4.2,"avg_velocity_meters_per_second":3,"max_velocity_meters_per_second":4.5,"avg_speed_meters_per_second":3.2,"avg_torque_newton_meters":40,"max_speed_meters_per_second":4.5,"avg_pace_minutes_per_kilometer":6.2,"avg_cadence_rpm":85,"max_torque_newton_meters":55.5,"normalized_speed_meters_per_second":3.8,"max_cadence_rpm":110,"cadence_samples":[{"timer_duration_seconds":300,"timestamp":"2022-11-23T09:00:00.000000+02:00","cadence_rpm":85}],"torque_samples":[{"torque_newton_meters":45.5,"timestamp":"2022-11-23T09:00:00.000000+02:00","timer_duration_seconds":300}],"speed_samples":[{"timestamp":"2022-11-23T09:00:00.000000+02:00","timer_duration_seconds":300,"speed_meters_per_second":3.5}]},"oxygen_data":{"vo2max_ml_per_min_per_kg":42.5,"avg_saturation_percentage":97,"vo2_samples":[{"vo2max_ml_per_min_per_kg":45.5,"timestamp":"2022-11-23T09:00:00.000000+02:00"}],"saturation_samples":[{"percentage":98,"timestamp":"2022-11-23T09:00:00.000000+02:00","type":0}]},"device_data":{"manufacturer":"Garmin","hardware_version":"v2.1","activation_timestamp":"2022-12-25T00:00:00.000000+05:00","serial_number":"GR123456789","name":"Forerunner 945","software_version":"5.2.1","other_devices":[{"manufacturer":"Garmin","hardware_version":"v2.1","serial_number":"GR123456789","name":"Forerunner 945","software_version":"5.2.1"}]},"energy_data":{"energy_planned_kilojoules":1200,"energy_kilojoules":1150},"MET_data":{"num_inactive_minutes":5,"num_low_intensity_minutes":15,"num_moderate_intensity_minutes":25,"avg_level":3.8,"num_high_intensity_minutes":10,"MET_samples":[{"timestamp":"2022-11-23T09:00:00.000000+02:00","level":4.2}]},"power_data":{"avg_watts":185,"max_watts":350,"power_samples":[{"timestamp":"2022-11-23T09:00:00.000000+02:00","timer_duration_seconds":1800,"watts":250}]},"distance_data":{"summary":{"distance_meters":5000,"steps":6500,"floors_climbed":10,"elevation":{"gain_planned_meters":500,"loss_actual_meters":450,"max_meters":1200,"min_meters":800,"gain_actual_meters":550,"avg_meters":950},"swimming":{"num_laps":20,"num_strokes":500,"pool_length_meters":25}},"detailed":{"elevation_samples":[{"elev_meters":925,"timestamp":"2022-11-23T09:00:00.000000+02:00","timer_duration_seconds":1200}],"distance_samples":[{"timestamp":"2022-11-23T09:00:00.000000+02:00","distance_meters":2500,"timer_duration_seconds":900}],"floors_climbed_samples":[{"floors_climbed":5,"timestamp":"2022-11-23T09:00:00.000000+02:00","timer_duration_seconds":600}],"step_samples":[{"steps":3250,"timestamp":"2022-11-23T09:00:00.000000+02:00","timer_duration_seconds":900}]}},"heart_rate_data":{"summary":{"resting_hr_bpm":65,"avg_hr_bpm":145,"max_hr_bpm":180,"avg_hrv_sdnn":45.5,"min_hr_bpm":85,"avg_hrv_rmssd":35.2,"user_max_hr_bpm":190,"hr_zone_data":[{"start_percentage":60,"end_percentage":70,"duration_seconds":300,"name":"Aerobic","zone":"ZONE_2"}]},"detailed":{"hrv_samples_rmssd":[{"hrv_rmssd":42.1,"timestamp":"2022-11-23T09:00:00.000000+02:00"}],"hr_samples":[{"timestamp":"2022-11-23T09:00:00.000000+02:00","bpm":142}],"hrv_samples_sdnn":[{"timestamp":"2022-11-23T09:00:00.000000+02:00","hrv_sdnn":48.3}]}},"TSS_data":{"TSS_samples":[{"intensity_factor_planned":0.85,"intensity_factor_actual":0.82,"normalized_power_watts":225,"planned":85,"actual":82,"method":"HeartRate"}]},"calories_data":{"BMR_calories":1800,"net_activity_calories":450,"total_burned_calories":2250,"net_intake_calories":200,"calorie_samples":[{"calories":450,"timestamp":"2022-11-23T09:00:00.000000+02:00","timer_duration_seconds":1800}]},"metadata":{"state":"California","country":"United States","start_time":"1999-11-23T09:00:00.000000+02:00","summary_id":"123e4567-e89b-12d3-a456-426614174000","city":"San Francisco","end_time":"2022-10-28T10:00:00.000000+01:00","name":"Morning Run","type":"RUNNING","upload_type":"UNKNOWN","timestamp_localization":0},"work_data":{"work_kilojoules":450.5}}]}'

201

400

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "message": "Activity successfully logged",
  "log_ids": [
    "text"
  ]
}

Returned when activity was successfully created on the provider

Used to post nutrition logs to a provider. Available for Fitbit

post

/nutrition

Authorizations

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Body

dataobject[]required

Nutrition entry to post to data provider

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.tryterra.co/v2/nutrition' \
  --header 'x-api-key: text' \
  --header 'dev-id: text' \
  --header 'Content-Type: application/json' \
  --data '{"data":[{"drink_samples":[{"drink_unit":"ml","timestamp":"2022-11-23T09:00:00.000000+02:00","drink_name":"Water","drink_volume":"250"}],"meals":[{"id":"food_123","timestamp":"2022-12-12T08:53:00.000000+02:00","name":"Oatmeal","type":"BREAKFAST","micros":{"iron_mg":8.5,"magnesium_mg":320,"vitamin_A_mg":0.9,"vitamin_B12_mg":0.0024,"biotin_mg":0.03,"cystine_g":0.3,"phenylalanine_g":0.9,"chloride_mg":2300,"vitamin_D3_mg":0.015,"isoleucine_g":0.8,"calcium_mg":1000,"iodine_mg":0.15,"histidine_g":0.6,"chromium_mg":0.035,"vitamin_K_mg":0.12,"manganese_mg":2.3,"folic_acid_mg":0.4,"leucine_g":1.2,"caffeine_mg":95,"potassium_mg":3500,"molybdenum_mg":0.045,"lysine_g":0.9,"tyrosine_g":0.7,"valine_g":0.8,"omega6_g":17,"omega3_g":1.6,"vitamin_C_mg":90,"zinc_mg":11,"vitamin_D2_mg":0.01,"vitamin_E_mg":15,"pantothenic_acid_mg":5,"riboflavin_mg":1.3,"phosphorus_mg":1000,"vitamin_D_mg":0.02,"tryptophan_g":0.3,"niacin_mg":16,"copper_mg":0.9,"threonine_g":0.5,"monounsaturated_fat_g":15,"folate_mg":0.4,"selenium_mg":0.055,"vitamin_B6_mg":1.7,"thiamin_mg":1.2,"polyunsaturated_fat_g":13,"methionine_g":0.6,"starch_g":25},"quantity":{"unit":"grams","amount":100},"macros":{"fiber_g":25,"calories":2000,"fat_g":65,"sodium_mg":2300,"alcohol_g":14,"trans_fat_g":2,"carbohydrates_g":300,"protein_g":50,"saturated_fat_g":20,"sugar_g":25,"cholesterol_mg":300,"net_carbohydrates_g":275}}],"summary":{"water_ml":2000,"micros":{"iron_mg":8.5,"magnesium_mg":320,"vitamin_A_mg":0.9,"vitamin_B12_mg":0.0024,"biotin_mg":0.03,"cystine_g":0.3,"phenylalanine_g":0.9,"chloride_mg":2300,"vitamin_D3_mg":0.015,"isoleucine_g":0.8,"calcium_mg":1000,"iodine_mg":0.15,"histidine_g":0.6,"chromium_mg":0.035,"vitamin_K_mg":0.12,"manganese_mg":2.3,"folic_acid_mg":0.4,"leucine_g":1.2,"caffeine_mg":95,"potassium_mg":3500,"molybdenum_mg":0.045,"lysine_g":0.9,"tyrosine_g":0.7,"valine_g":0.8,"omega6_g":17,"omega3_g":1.6,"vitamin_C_mg":90,"zinc_mg":11,"vitamin_D2_mg":0.01,"vitamin_E_mg":15,"pantothenic_acid_mg":5,"riboflavin_mg":1.3,"phosphorus_mg":1000,"vitamin_D_mg":0.02,"tryptophan_g":0.3,"niacin_mg":16,"copper_mg":0.9,"threonine_g":0.5,"monounsaturated_fat_g":15,"folate_mg":0.4,"selenium_mg":0.055,"vitamin_B6_mg":1.7,"thiamin_mg":1.2,"polyunsaturated_fat_g":13,"methionine_g":0.6,"starch_g":25},"macros":{"fiber_g":25,"calories":2000,"fat_g":65,"sodium_mg":2300,"alcohol_g":14,"trans_fat_g":2,"carbohydrates_g":300,"protein_g":50,"saturated_fat_g":20,"sugar_g":25,"cholesterol_mg":300,"net_carbohydrates_g":275}},"metadata":{"start_time":"1999-11-23T09:00:00.000000+02:00","end_time":"2022-10-28T10:00:00.000000+01:00","timestamp_localization":0}}]}'

201

400

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "message": "Nutrition successfully logged",
  "log_ids": [
    "text"
  ]
}

Returned when activity was successfully created on the provider

Used to post body data to a provider. Available for Google Fit

post

/body

Authorizations

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Body

dataobject[]required

Body measurement metrics to post to data provider

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.tryterra.co/v2/body' \
  --header 'x-api-key: text' \
  --header 'dev-id: text' \
  --header 'Content-Type: application/json' \
  --data '{"data":[{"measurements_data":{"measurements":[{"weight_kg":75.5,"bodyfat_percentage":18.5,"BMI":22.4,"water_percentage":60.5,"measurement_time":"2022-11-23T09:00:00.000000+02:00","lean_mass_g":61500,"estimated_fitness_age":"25","skin_fold_mm":12.5,"height_cm":178,"bone_mass_g":3200,"insulin_units":10.5,"muscle_mass_g":35000,"BMR":1800,"urine_color":"pale yellow","RMR":2000,"insulin_type":"rapid-acting"}]},"ketone_data":{"ketone_samples":[{"ketone_mg_per_dL":1.5,"timestamp":"2022-11-23T09:00:00.000000+02:00","sample_type":"UNKNOWN"}]},"hydration_data":{"hydration_amount_samples":65.5,"day_total_water_consumption_ml":2500},"device_data":{"manufacturer":"Garmin","hardware_version":"v2.1","activation_timestamp":"2022-12-25T00:00:00.000000+05:00","serial_number":"GR123456789","name":"Forerunner 945","software_version":"5.2.1","other_devices":[{"manufacturer":"Garmin","hardware_version":"v2.1","serial_number":"GR123456789","name":"Forerunner 945","software_version":"5.2.1"}]},"heart_data":{"pulse_wave_velocity_samples":[{"pulse_wave_velocity_meters_per_second":7.2,"timestamp":"2022-11-23T09:00:00.000000+02:00"}],"afib_classification_samples":[{"timestamp":"2022-11-23T09:00:00.000000+02:00","afib_classification":"NORMAL"}],"ecg_signal":[{"start_timestamp":"2022-11-23T09:00:00.000000+02:00","avg_hr_bpm":72.5,"afib_classfication":1,"raw_signal":[{"potential_uV":1250.5,"timestamp":"2022-11-23T09:00:00.000000+02:00"}]}],"rr_interval_samples":[{"rr_interval_ms":850,"timestamp":"2022-11-23T09:00:00.000000+02:00","hr_bpm":72}],"heart_rate_data":{"summary":{"resting_hr_bpm":60,"avg_hr_bpm":75,"max_hr_bpm":180,"avg_hrv_sdnn":45.5,"min_hr_bpm":45,"avg_hrv_rmssd":42.8,"user_max_hr_bpm":190,"hr_zone_data":[{"start_percentage":60,"end_percentage":70,"duration_seconds":300,"name":"Aerobic","zone":"ZONE_2"}]},"detailed":{"hrv_samples_rmssd":[{"hrv_rmssd":42.1,"timestamp":"2022-11-23T09:00:00.000000+02:00"}],"hr_samples":[{"timestamp":"2022-11-23T09:00:00.000000+02:00","bpm":142}],"hrv_samples_sdnn":[{"timestamp":"2022-11-23T09:00:00.000000+02:00","hrv_sdnn":48.3}]}}},"oxygen_data":{"vo2max_ml_per_min_per_kg":42.5,"avg_saturation_percentage":97,"vo2_samples":[{"vo2max_ml_per_min_per_kg":45.5,"timestamp":"2022-11-23T09:00:00.000000+02:00"}],"saturation_samples":[{"percentage":98,"timestamp":"2022-11-23T09:00:00.000000+02:00","type":0}]},"glucose_data":{"day_avg_blood_glucose_mg_per_dL":92.5,"detailed_blood_glucose_samples":[{"blood_glucose_mg_per_dL":95,"timestamp":"2022-11-23T09:00:00.000000+02:00","glucose_level_flag":"NORMAL","trend_arrow":"FLAT"}],"blood_glucose_samples":[{"blood_glucose_mg_per_dL":95,"timestamp":"2022-11-23T09:00:00.000000+02:00","glucose_level_flag":"NORMAL","trend_arrow":"FLAT"}]},"metadata":{"start_time":"1999-11-23T09:00:00.000000+02:00","end_time":"2022-10-28T10:00:00.000000+01:00","timestamp_localization":0},"blood_pressure_data":{"blood_pressure_samples":[{"diastolic_bp":80.5,"timestamp":"2022-11-23T09:00:00.000000+02:00","systolic_bp":120.5}]},"temperature_data":{"body_temperature_samples":[{"temperature_celsius":37.2,"timestamp":"2022-11-23T09:00:00.000000+02:00"}],"skin_temperature_samples":[{"temperature_celsius":37.2,"timestamp":"2022-11-23T09:00:00.000000+02:00"}],"ambient_temperature_samples":[{"temperature_celsius":37.2,"timestamp":"2022-11-23T09:00:00.000000+02:00"}]}}]}'

201

400

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "message": "Body data successfully logged",
  "log_ids": [
    "text"
  ]
}

Returned when activity was successfully created on the provider

Used to post workout plans users can follow on their wearable. This can be stregnth workouts (sets, reps, weight lifted) or cardio workouts (warmup, intervals of different intensities, cooldown etc)

post

/plannedWorkout

Authorizations

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Body

dataobject[]required

PlannedWorkout entry to post to data provider

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.tryterra.co/v2/plannedWorkout' \
  --header 'x-api-key: text' \
  --header 'dev-id: text' \
  --header 'Content-Type: application/json' \
  --data '{"data":[{"steps":{},"metadata":{"estimated_energy_kj":1,"estimated_speed_meters_per_second":1,"estimated_elevation_gain_meters":1,"estimated_tss":1,"estimated_calories":1,"created_date":"2022-11-23T09:00:00.000000+02:00","planned_date":"2022-11-24T09:00:00.000000+02:00","id":null,"estimated_duration_seconds":1,"estimated_pace_minutes_per_kilometer":1,"provider":"text","estimated_tscore":1,"description":"text","name":"text","estimated_distance_meters":1,"estimated_if":1,"pool_length_meters":1,"type":"IN_VEHICLE"}}]}'

201

400

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "message": "Nutrition successfully logged",
  "log_ids": [
    "text"
  ]
}

Returned when activity was successfully created on the provider

Used to delete nutrition logs the user has registered on their account

delete

/nutrition

Authorizations

Query parameters

user_idstringrequired

user ID to query data for

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Body

log_idsstring[]

List of identifiers for nutrition entries to be deleted

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.tryterra.co/v2/nutrition?user_id=text' \
  --header 'x-api-key: text' \
  --header 'dev-id: text' \
  --header 'Content-Type: application/json' \
  --data '{"log_ids":[null]}'

200

207

400

401

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "processed_data": [
    {
      "id": "text",
      "response_code": 1
    }
  ]
}

Returned when all records were deleted successfully

Used to delete Body metrics the user has registered on their account

delete

/body

Authorizations

Query parameters

user_idstringrequired

user ID to query data for

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Body

log_idsstring[]

List of identifiers for body metrics entries to be deleted

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.tryterra.co/v2/body?user_id=text' \
  --header 'x-api-key: text' \
  --header 'dev-id: text' \
  --header 'Content-Type: application/json' \
  --data '{"log_ids":[null]}'

200

207

400

401

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "processed_data": [
    {
      "id": "text",
      "response_code": 1
    }
  ]
}

Returned when all records were deleted successfully

Used to delete workout plans the user has registered on their account. This can be stregnth workouts (sets, reps, weight lifted) or cardio workouts (warmup, intervals of different intensities, cooldown etc)

delete

/plannedWorkout

Authorizations

Query parameters

user_idstringrequired

user ID to query data for

Header parameters

dev-idstringrequired

your developer ID

Example: testingTerra

x-api-keystringrequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Body

log_idsstring[]

List of identifiers for planned workout entries to be deleted

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.tryterra.co/v2/plannedWorkout?user_id=text' \
  --header 'x-api-key: text' \
  --header 'dev-id: text' \
  --header 'Content-Type: application/json' \
  --data '{"log_ids":[null]}'

200

207

400

401

404

{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT"
  },
  "processed_data": [
    {
      "id": "text",
      "response_code": 1
    }
  ]
}

Returned when all records were deleted successfully