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