< Blogs
Elliott

Elliott

November 21, 2022

WHOOP Integration series Part 1: Getting started with Rest APIs

For years, Garmin, Fitbit, Polar, and other fitness tracking companies have allowed their developer enthusiasts to access their data through (mainly) REST APIs. This has allowed these companies' user base to grow as more and more apps and tools are developed around their data.

After about six months since WHOOP started syncing its data outside of its ecosystem (exclusively to Apple Health), WHOOP has followed suit and started exposing its API endpoints to allow other developers to access and play with their data.

Getting Started

Like Terra's API, WHOOP's API is a REST API that allows you to gather data using HTTP requests in a specific format.

Typically REST APIs that allow you to gather data from users will have to follow a series of the same steps:

  • Authentication
  • Data Gathering
  • Data Processing

Authentication: Like a lot of recent APIs, WHOOP's authentication system is done through OAuth2. However, everyone's OAuth2 system is always slightly different. This would cause a hassle if you integrated with WHOOP and other OAuth2 authentication systems yourself.

Terra has abstracted this system away from you and allows you to follow a single auth flow for every provider there is. However, you were to integrate to WHOOP through OAuth2, you will have to keep track of ACCESS TOKENs and REFRESH TOKENs internally.

The user_id the parameter is linked to one user per wearable (for example, WHOOP).

Data Gathering: After authentication, you could typically request data from the REST API using the credentials retrieved (in OAuth2, this would be the Access Token). However, every company has its own access token for each user with different expiry times. Terra has abstracted this requirement away and allows you to simply request data using the user_id returned by the authentication process through Terra (regardless of the data provider company)

Now through Terra, you can request data from WHOOP's API endpoints using the user_id. If you are interested in the user's workout data, you can use the following endpoint: https://api.tryterra.co/activity

The request could be made as such:

curl --location --request GET 'https://api.tryterra.co/activity?user_id=USER_ID&start_date=2022-10-01&end_date=2022-10-30' \
--header 'dev-id: DEV-ID'
--header 'x-api-key: X-API-KEY'

This method is usually useful if you wish to retrieve historical data. If you wish to continuously receive data on update, you can open a webhook endpoint to accept Terra's webhook events. This will reduce the load on your servers to continuously make HTTP requests as well as making sure you get the most updated events from WHOOP (or any other integrations).

Data Processing: finally, after gathering the data, you will need to process it. Every REST API sends data differently; thus, you must write a parser for every datatype and wearable. Terra has again abstracted this away and only sends data in one format regardless of the data provider.

The request above returns JSON format data for the specific user_id WHOOP activity. For another company, for example, FITBIT, the only difference in this payload would be that the provider field will be FITBIT .

{
  "status": "success",
  "data": [
      "metadata": {
        "state": null,
        "upload_type": 0,
        "start_time": "2022-11-18T08:58:21.958766+00:00",
        "type": 18,
        "name": "Cross Country Skiing",
        "summary_id": "229630376069",
        "city": null,
        "country": null,
        "end_time": "2022-11-18T09:47:21.958766+00:00"
      },
      "strain_data": {
        "strain_level": 6.149371915562675
      },
      "heart_rate_data": {
        "summary": {
          "min_hr_bpm": null,
          "hr_zone_data": [
            {
              "start_percentage": 0,
              "duration_seconds": 390,
              "name": "Resting",
              "zone": 0,
              "end_percentage": 50
            },
            {
              "start_percentage": 50,
              "duration_seconds": 504,
              "name": "Very light",
              "zone": 1,
              "end_percentage": 60
            },
            ...
          ],
          "avg_hr_bpm": 118.42194006578433,
          "max_hr_bpm": 158.16932189285052,
          "avg_hrv_rmssd": null,
          "resting_hr_bpm": null,
          "avg_hrv_sdnn": null,
          "user_max_hr_bpm": null
        },
        "detailed": {
          "hr_samples": [],
          "hrv_samples_sdnn": [],
          "hrv_samples_rmssd": []
        }
      },
      "active_durations_data": {
        "activity_seconds": null,
        "inactivity_seconds": 2643.4844720203464,
        "rest_seconds": null,
        "moderate_intensity_seconds": 2101.2303060321888,
        "activity_levels_samples": [],
        "vigorous_intensity_seconds": 2342.994113043535,
        "low_intensity_seconds": 549.4035406958508,
        "num_continuous_inactive_periods": null
      },
      ...
    }
  ],
  "user": {
    "provider": "WHOOP",
    "last_webhook_update": null,
    "user_id": "013a6120-ea0f-4973-ad3b-4ac11112617e",
    "scopes": null
  },
  "type": "activity"
}

Using this data, you can take anything from WHOOP's API (and any other fitness companies' data) and display or manipulate it for special features in your app.

Continue On

This is a game changer from WHOOP's side, allowing developers to access data through their REST API. As the fitness and health sector continuously grows globally, more companies are looking to develop with fitness data. This allows them to add one more integration (rather than a big one) to their platform.

If you are integrated with Terra already, your infrastructure just got another integration overnight!


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.