WHOOP Integration series Part 4: Data from TERRA API

Continuing our Integration series on WHOOP, we are discussing the data available from our API when fetching data from WHOOP.

As a reminder, the WHOOP series contains:

• Part 1: Getting started with Rest APIs
• Part 2: Data available from the API
• Part 3: Integrating with Terra API
• Part 4: Data from TERRA API

As WHOOP users may know, WHOOP provides a graph with their users' heart rate 24/7 at one-minute intervals. However, did you know that WHOOP's sampling frequency is among the highest in the wearables space?

As quoted by WHOOP:

"A key differentiator of WHOOP is that its sensors collect data 100 times per second, 24 hours a day! The high sampling rate allows it to dish out statistics with great accuracy." - @HFGEnthusiast

WHOOP's API

As accurate or abundant as the data from WHOOP may be, they have removed many granular details from their API. Currently, only summarised or calculated statistical data such as max, min, and average heart rate are available from their API.

However, to compensate for the lack of sampled data, WHOOP allows for integrating webhooks with their API. This means that when you integrate, you will always get the most updated events/activities for your users.

Terra Webhooks

Like every integration, Terra provides, Terra provides on update webhooks for WHOOP integration.

This means after authentication, you simply need to start listening to Terra webhook events in your backend to receive the most up-to-date data for your users. For example, your user completes a workout:

Once this information is logged to WHOOP's server, your backend will receive a payload with all the information shown on the device.

{
    "heart_rate_data": {
        "summary": {
            "hr_zone_data": [
                {
                    "duration_seconds": 440.262,
                    "zone": 0,
                    "start_percentage": 0,
                    "end_percentage": 50,
                    "name": "Resting"
                },
                {
                    "duration_seconds": 812.341,
                    "zone": 1,
                    "start_percentage": 50,
                    "end_percentage": 60,
                    "name": "Very light"
                },
                {
                    "duration_seconds": 147.079,
                    "zone": 2,
                    "start_percentage": 60,
                    "end_percentage": 70,
                    "name": "Light"
                },
                {
                    "duration_seconds": 0.0,
                    "zone": 3,
                    "start_percentage": 70,
                    "end_percentage": 80,
                    "name": "Moderate"
                },
                {
                    "duration_seconds": 0.0,
                    "zone": 4,
                    "start_percentage": 80,
                    "end_percentage": 90,
                    "name": "Hard"
                },
                {
                    "duration_seconds": 0.0,
                    "zone": 5,
                    "start_percentage": 90,
                    "end_percentage": 100,
                    "name": "Maximum"
                }
            ],
            "max_hr_bpm": 127,
            "user_max_hr_bpm": null,
            "resting_hr_bpm": null,
            "min_hr_bpm": null,
            "avg_hrv_sdnn": null,
            "avg_hrv_rmssd": null,
            "avg_hr_bpm": 94
        },
        "detailed": {
            "hrv_samples_sdnn": [],
            "hr_samples": [],
            "hrv_samples_rmssd": []
        }
    },
    "metadata": {
        "summary_id": 553531533,
        "upload_type": 1,
        "end_time": "2022-11-23T17:55:55.731000+00:00",
        "city": null,
        "country": null,
        "start_time": "2022-11-23T17:32:35.887000+00:00",
        "state": null,
        "name": "Functional Fitness",
        "type": 113
    },
    "calories_data": {
        "net_activity_calories": 71.7,
        "net_intake_calories": null,
        "calorie_samples": [],
        "BMR_calories": null,
        "total_burned_calories": null
    },
    "distance_data": {
        "summary": {
            "steps": null,
            "elevation": {
                "gain_planned_meters": null,
                "min_meters": null,
                "loss_actual_meters": null,
                "avg_meters": null,
                "gain_actual_meters": 0.0,
                "max_meters": null
            },
            "distance_meters": 0.0,
            "floors_climbed": null,
            "swimming": {
                "num_strokes": null,
                "num_laps": null,
                "pool_length_meters": null
            }
        },
        "detailed": {
            "step_samples": [],
            "floors_climbed_samples": [],
            "elevation_samples": [],
            "distance_samples": []
        }
    },
    "active_durations_data": {
        "activity_seconds": null,
        "moderate_intensity_seconds": 0.0,
        "activity_levels_samples": [],
        "vigorous_intensity_seconds": 0.0,
        "inactivity_seconds": 812.341,
        "num_continuous_inactive_periods": null,
        "rest_seconds": null,
        "low_intensity_seconds": 147.079
    },
    "energy_data": {
        "energy_planned_kilojoules": null,
        "energy_kilojoules": 300.11462
    },
    "strain_data": {
        "strain_level": 4.7311
    }
}

Which contains the majority of the details returned by the WHOOP device. You can then process this in your server and perform necessary operations before displaying or giving your users insights on the workout.

Integration

Terra provides one integration solution for all wearable companies out there. Imagine if you were to integrate with WHOOP finding out they support webhooks, then you move to another provider such as OURA and find out that they don't. This means you will have to adapt your systems to retrieve and receive the most up-to-date data from OURA and WHOOP differently.

Integration with Terra would solve all the mismatches and inconsistent REST API designs for you so that you can focus on building the core of your product!