< Blogs
Elliott

Elliott

November 22, 2022

WHOOP Integration series Part 2: Data available from the API

With WHOOP's recent announcement of their open API, we at Terra were very excited to see what we can get from their API.

API vs Device Data

WHOOP's API currently can only provide a top-level summary of the user's health data: how well they slept, how much strain they put their body through, and how well did they recover.

Sleep and Recovery: The device provides you with a detailed analysis of how you've slept for a night, providing resting heart rates, heart rate variability, respiratory rates, amount of time spent in each sleep stage, amount of wake up events, and your heart rates over the night. If we take an example here, we can see WHOOP displays the following for a night of sleep and recovery over the week.

Most of the data points above can be retrieved from the API. This would populate respective fields in Terra's sleep data payload. For example, for the night of sleep above, the payload below is returned.

  {
      "readiness_data": {
          "readiness": 76.0,
          "recovery_level": 0
      },
      "device_data": {
          "other_devices": [],
          "activation_timestamp": null,
          "manufacturer": null,
          "software_version": null,
          "serial_number": null,
          "name": null,
          "hardware_version": null
      },
      "metadata": {
          "start_time": "2022-09-11T01:08:42.703000+07:00",
          "is_nap": false,
          "end_time": "2022-09-11T10:02:11.493000+07:00",
          "upload_type": 1
      },
      "temperature_data": {
          "delta": null
      },
      "sleep_durations_data": {
          "other": {
              "duration_in_bed_seconds": null,
              "duration_unmeasurable_sleep_seconds": 0.0
          },
          "asleep": {
              "duration_asleep_state_seconds": 30086.76,
              "num_REM_events": 4,
              "duration_REM_sleep_state_seconds": 8201.357,
              "duration_deep_sleep_state_seconds": 5342.427,
              "duration_light_sleep_state_seconds": 16542.976
          },
          "sleep_efficiency": 0.9442353,
          "hypnogram_samples": [],
          "awake": {
              "num_wakeup_events": 12,
              "wake_up_latency_seconds": null,
              "num_out_of_bed_events": null,
              "duration_long_interruption_seconds": null,
              "duration_awake_state_seconds": 1776.865,
              "duration_short_interruption_seconds": null,
              "sleep_latency_seconds": null
          }
      },
      "respiration_data": {
          "breaths_data": {
              "start_time": null,
              "max_breaths_per_min": null,
              "avg_breaths_per_min": 15.058594,
              "end_time": null,
              "on_demand_reading": null,
              "samples": [],
              "min_breaths_per_min": null
          },
          "oxygen_saturation_data": {
              "start_time": null,
              "end_time": null,
              "samples": [],
              "avg_saturation_percentage": 97.63333
          },
          "snoring_data": {
              "start_time": null,
              "end_time": null,
              "total_snoring_duration_seconds": null,
              "samples": [],
              "num_snoring_events": null
          }
      },
      "heart_rate_data": {
          "summary": {
              "avg_hrv_sdnn": null,
              "user_max_hr_bpm": null,
              "resting_hr_bpm": 59.0,
              "avg_hrv_rmssd": 60.33115,
              "min_hr_bpm": null,
              "avg_hr_bpm": null,
              "max_hr_bpm": null
          },
          "detailed": {
              "hrv_samples_rmssd": [],
              "hr_samples": [],
              "hrv_samples_sdnn": []
          }
      }
  }

Strain: WHOOP also provides a detailed breakdown of how much strain the user has put on their body. This comes in a strain score going between 0 and 21. This score accumulates over the day as the user completes workouts, or simply by performing everyday tasks.

If we take a look at the device, the workout performed on the left produced a strain of 14.6 which on a corresponding day, produced a total strain of 18.1. The workout has details on how much time was spent on each HR zone along with heart rate statistics, calories and duration data.

The workout details above can be retrieved by Terra's API as shown below:

{
    "oxygen_data": {
        "avg_saturation_percentage": null,
        "vo2max_ml_per_min_per_kg": null,
        "vo2_samples": [],
        "saturation_samples": []
    },
    "polyline_map_data": {
        "summary_polyline": null
    },
    "metadata": {
        "type": 108,
        "country": null,
        "summary_id": 510541643,
        "state": null,
        "start_time": "2022-09-15T12:59:50.889000+08:00",
        "name": "Activity",
        "end_time": "2022-09-15T14:45:33.507000+08:00",
        "city": null,
        "upload_type": 1
    },
    "strain_data": {
        "strain_level": 14.604
    },
    "distance_data": {
        "summary": {
            "swimming": {
                "num_laps": null,
                "pool_length_meters": null,
                "num_strokes": null
            },
            "steps": null,
            "floors_climbed": null,
            "elevation": {
                "avg_meters": null,
                "gain_planned_meters": null,
                "loss_actual_meters": null,
                "gain_actual_meters": 0.0,
                "min_meters": null,
                "max_meters": null
            },
            "distance_meters": 0.0
        },
        "detailed": {
            "distance_samples": [],
            "floors_climbed_samples": [],
            "elevation_samples": [],
            "step_samples": []
        }
    },
    "heart_rate_data": {
        "summary": {
            "user_max_hr_bpm": null,
            "min_hr_bpm": null,
            "max_hr_bpm": 167,
            "hr_zone_data": [
                {
                    "end_percentage": 50,
                    "duration_seconds": 0.0,
                    "name": "Resting",
                    "start_percentage": 0,
                    "zone": 0
                },
                {
                    "end_percentage": 60,
                    "duration_seconds": 339.38,
                    "name": "Very light",
                    "start_percentage": 50,
                    "zone": 1
                },
                {
                    "end_percentage": 70,
                    "duration_seconds": 2058.107,
                    "name": "Light",
                    "start_percentage": 60,
                    "zone": 2
                },
                {
                    "end_percentage": 80,
                    "duration_seconds": 2552.245,
                    "name": "Moderate",
                    "start_percentage": 70,
                    "zone": 3
                },
                {
                    "end_percentage": 90,
                    "duration_seconds": 1392.925,
                    "name": "Hard",
                    "start_percentage": 80,
                    "zone": 4
                },
                {
                    "end_percentage": 100,
                    "duration_seconds": 0.0,
                    "name": "Maximum",
                    "start_percentage": 90,
                    "zone": 5
                }
            ],
            "avg_hr_bpm": 134,
            "avg_hrv_sdnn": null,
            "avg_hrv_rmssd": null,
            "resting_hr_bpm": null
        },
        "detailed": {
            "hrv_samples_rmssd": [],
            "hrv_samples_sdnn": [],
            "hr_samples": []
        }
    },
    "power_data": {
        "avg_watts": null,
        "power_samples": [],
        "max_watts": null
    },
    "active_durations_data": {
        "low_intensity_seconds": 2058.107,
        "activity_levels_samples": [],
        "activity_seconds": null,
        "rest_seconds": null,
        "moderate_intensity_seconds": 2552.245,
        "inactivity_seconds": 339.38,
        "num_continuous_inactive_periods": null,
        "vigorous_intensity_seconds": 1392.925
    },
    "energy_data": {
        "energy_kilojoules": 4064.4888,
        "energy_planned_kilojoules": null
    }
    ...
}

Left Out

From the data points analyzed above, you may have noticed two very important fields missing that are shown on the device but not retrieved by the API:

Heart Rates

WHOOP provides a dashboard with all the user's heart rates measured by the device (at 1 minute intervals). This information are used by many developers to make in-depth analytics on their users' health profile.

Sleep Samples

WHOOP provides in detail the times the user goes from awake to light sleep, light sleep to deep sleep, deep sleep to rem sleep and etc. This information is essential for apps that wish to track sleep closely for their users. Knowing when they go from light sleep to deep sleep allows the developer to further suggest how to maximize the time spent in deep sleep (for better recovery).

API Potentials

The device data left out of the API are common data fields provided by fitness wearable companies such as GARMIN, FITBIT, and OURA in their APIs. They are what enable developers to make truly personalized apps that can change the health and fitness market.

We at Terra enable our developers to do so already by providing as much data as possible from every integration we do, from our fitness API.


In 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

More Topics

All Blogs
Team Spotlight
Startup Spotlight
How To
Blog
Podcast
Product Updates
Wearables
See All >
CEO and Co-Founder of Veri - Anttoni Aniebonam

CEO and Co-Founder of Veri - Anttoni Aniebonam

In this podcast with Kyriakos the CEO of Terra, Anttoni Aniebonam shares his journey founding Veri, and his decision in the acquisition by Oura to further his vision.

Terra APITerra API
September 27, 2024
CEO and Founder of Prenuvo - Andrew Lacy

CEO and Founder of Prenuvo - Andrew Lacy

In this podcast with Kyriakos the CEO of Terra, Andrew Lacy shares his journey with Prenuvo which began from a personal health crisis.

Terra APITerra API
August 28, 2024
MedHacks: Using Wearables To Predict Heart Attacks

MedHacks: Using Wearables To Predict Heart Attacks

A few weeks ago we met Vishal, a recent engineering graduate who wanted to use Terra API as part of his MedHacks hackathon project, Cardio Clarity.

Gursukh SembiGursukh Sembi
August 19, 2024
July 2024 updates

July 2024 updates

Teams API adds Kinexon integration & new webhooks. Terra Health Scores now include Respiratory & Stress metrics. Eight Sleep integration returns with enhanced data.

Alex VenetidisAlex Venetidis
August 2, 2024
Vice President of Teamworks - Sean Harrington

Vice President of Teamworks - Sean Harrington

In this podcast with Kyriakos the CEO of Terra, Sean Harrington shares his journey from founding NoteMeal to becoming the VP of Teamworks.

Terra APITerra API
August 2, 2024
next ventures
pioneer fund
samsung next
y combinator
general catalyst

Cookie Preferences

Essential CookiesAlways On
Advertisement Cookies
Analytics Cookies

Crunch Time: Embrace the Cookie Monster Within!

We use cookies to enhance your browsing experience and analyse our traffic. By clicking “Accept All”, you consent to our use of cookies according to our Cookie Policy. You can change your mind any time by visiting out cookie policy.