Quickstart

Learn how to receive data for a user's account in just 2 API requests

Learn how to receive data for an example user in two API requests.

It’s best to use your own device as an example, so you can go test with your own data. In the first step, you will connect your device provider through an authentication link (think of it like a "log in with google" link, but for Fitbit, Garmin, etc..). In the second step, you will retrieve your device’s data.

1. Connect a User

To begin, you'll need to authenticate your first example user by generating an authentication link. This link allows your end users to connect their health & fitness accounts to your application.

i) Create the Authentication URL: Use the /auth endpoint to generate a link for the user.

ii) Redirect your user: Access the auth_url to complete the authentication process and enter your device credentials to mimic your user authentication.

You'll need your API Key & Developer ID set in the headers to successfully authenticate requests.

For now, omit all body parameters and leave them empty

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

apiKeyAuthdevIdAuth

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

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

{
  "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

Once you have completed the authentication as an example user, the user_id returned in the response above will be activated. This ID is crucial for managing user connections and retrieving their device data.

2. Retrieve the user's data

With the user_id, you can now retrieve user data using the /daily endpoint (or any other endpoint your fitness data account may support).

As an example, try retrieving the user's daily activity summary data using the endpoint below, using the user_id from the response above,

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

apiKeyAuthdevIdAuth

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

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

{
  "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

You're all set! 🎉

Keep going to learn how to integrate Terra into your existing environment