In this post of the WHOOP Developer Platform series, readers that are interested in developing applications with WHOOP learn how to use physiological cycles, rather than calendar days, to provide the best experience for their users.
Around this time last year, I was fortunate to travel to Hawaii for vacation. I left in the morning from Boston, where WHOOP is headquartered. After a long layover, my wristwatch reported 1:11 AM when I touched down at my final destination, but my phone’s screen reported 7:11 PM on the previous day.
I thought to myself, “Do I even know what day it is?”. Of course, the day on my calendar said authoritatively October 2, but the next morning’s red recovery showed that my body felt like it was October 3 or maybe some day between the two that didn’t exist on a calendar (October 2 ½?).
Your body doesn’t know what day it is.
While days that start and end at 12:00 AM are useful for calendars, your body runs on its own internal clock. Your circadian rhythm resets about every twenty-four hours and sets in motion changes in your body, such as making you feel sleepy or feel awake. Circadian rhythm is an evolutionary process that humans adapted long before modern life and trans-oceanic airplane flights. But your internal clock can reset using environmental cues such as increases and decreases in light (e.g., sunrises and sunsets), which is why your body eventually recovers from jetlag.
WHOOP members do incredible work at all hours of their lives – whether that’s taking the night shift at work and sleeping during the day, staying awake for thirty-six hours straight, or traveling to other timezones of the world. Forcing these members into a calendar system that resets at 12:00 AM would make any representation of their physiological data incorrect. Therefore, we avoid using calendar days at WHOOP and instead center around the concept of physiological cycles.
How does WHOOP determine Physiological Cycles?
Knowing when a user is asleep or awake allows WHOOP to best determine the member’s physiological cycle boundaries. WHOOP leverages advanced machine learning algorithms to continuously analyze biometric data from a member’s WHOOP device to understand when they are sleeping and even their current stage of sleep. This helps WHOOP define a cycle from sleep onset to sleep onset.
WHOOP uses your sleep onset to place boundaries around your physiological cycle.
One challenge is handling situations where a member does not sleep for an extended period. A naive approach is to add 24 hours to the end of the previous day’s sleep. But Dr. Matthew Walker highlights in his book Why We Sleep,
Instead, WHOOP algorithms use the member’s historical behavior to make an educated decision about their highly personal internal clock and retroactively correct the decision as future behavior is learned.
What does this mean for you?
As a developer on the WHOOP Developer Platform, we encourage you to think about how the experience you are creating for your users can benefit all lifestyles by centering around a physiological cycle rather than a calendar day. The WHOOP API provides you with the data you need to get started building with cycles.
- The Cycle data model helps you understand when a member’s cycle starts and ends. This model also provides summary statistics like how much WHOOP Strain the member experienced during the cycle.
- A cycle with a start but no end time means the member is currently in that cycle.
- Past cycle start and end times may change for a few days as WHOOP learns more about what the member is doing and
retroactively update past decisions. If you want notifications when these changes occur, you can subscribe to
recovery.updatedwebhooks and introspect the cycle start and end time. You can learn more about webhooks here. - The WHOOP Recovery score is tied to a specific
cycle (represented by
cycle_idon the Recovery data model). This score tells you how prepared the member’s body is to take on Strain when entering that cycle. - If you want to understand all the workouts a member performed during a cycle, query the Workout Collection and set the start and end time query parameters using the same time bounds from the Cycle object.
Develop with WHOOP
Want to integrate WHOOP with your app? Check out the Developer Platform at developer.whoop.com to get started – we can’t wait to see what you build!
If you are interested in building infrastructure at WHOOP check out our open positions.