whoop-py 0.1.0

Python client for the WHOOP API with OAuth 2.0 support

whoop-api

Personal WHOOP data explorer using the WHOOP API.

Structure

whoop.py      # WhoopClient (OAuth2 + API) and WhoopAPI (token persistence)
main.py       # CLI entry point
main.ipynb    # Interactive data exploration

Auth Flow

sequenceDiagram
    participant U as User
    participant A as WhoopAPI
    participant W as WHOOP OAuth

    U->>A: WhoopAPI()
    A->>A: load token from disk
    alt no token / missing scopes
        A->>W: create_authorization_url()
        W-->>U: redirect URL
        U->>W: approve access
        W-->>U: redirect with code
        U->>A: paste redirect URL
        A->>W: fetch_token(code)
        W-->>A: access + refresh token
        A->>A: save token to disk
    else token expired
        A->>W: refresh_access_token()
        W-->>A: new token
        A->>A: save token to disk
    end
    A-->>U: authenticated WhoopClient

Data Flow

flowchart LR
    E[.env\nCLIENT_ID\nCLIENT_SECRET\nREDIRECT_URI] --> API[WhoopAPI]
    T[.whoop_token.json] <-->|load / save| API
    API --> C[WhoopClient]
    C -->|GET| S[/sleep]
    C -->|GET| R[/recovery]
    C -->|GET| W[/workout]
    C -->|GET| CY[/cycle]

Setup

pip install -r requirements.txt

.env

CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
REDIRECT_URI=your_redirect_uri

Register your app at developer.whoop.com to get credentials.

Usage

Script

python main.py

Notebook

jupyter notebook main.ipynb

Library

from dotenv import load_dotenv
from whoop import WhoopAPI

load_dotenv()

with WhoopAPI() as api:
    sleep = api.get_sleep_collection(start_date="2026-06-01")
    recovery = api.get_recovery_collection()
    workouts = api.get_workout_collection()

The first run opens an interactive auth flow and saves the token to .whoop_token.json. Subsequent runs reuse or auto-refresh it.

API Reference

Method	Description
get_profile()	User profile
get_body_measurement()	Height, weight, max HR
get_sleep_collection(start, end)	All sleep records
get_sleep_by_id(id)	Single sleep record
get_sleep_stream(id)	Raw HR/temp signal stream
get_recovery_collection(start, end)	All recovery scores
get_recovery_for_cycle(cycle_id)	Recovery for a cycle
get_cycle_collection(start, end)	All physiological cycles
get_cycle_by_id(id)	Single cycle
get_workout_collection(start, end)	All workouts
get_workout_by_id(id)	Single workout

start / end are ISO date strings (e.g. "2026-06-01"). Defaults to the last 7 days.