whoopy 0.2.1

Unofficial Client for the Whoop API

Whoop Python Client

This is an unofficial implementation of the official Whoop API.

Getting Started

First you will need to install the library:

# either from pypi
pip install whoopy
# or by local build
pip install .

For development you can install the requirements.txt or the env.yaml conda environment:

pip install -r requirements.txt
# or
conda env create -f env.yaml

In order to use the API, you will need to register your application here and enter the client_id, client_secret and redirect_uri in the config.json file (you can use the template provided in config.sample.json):

{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "YOUR_REDIRECT_URI"
}

Note: For the purposes of local use, you can simply provide http://localhost:1234 as redirect_uri in the app registration

Authorization

You can then the config to run through the client authentication and save the token:

import json
from whoopy import WhoopClient

# load the config
conf = json.load(open("config.json", "r"))

# either run through full auth process (useful in jupyter notebooks)
# note: This will open the web browser and require you to copy the code parameter from the resulting uri back
client = WhoopClient.auth_flow(conf["client_id"], conf["client_secret"], conf["redirect_uri"])

# or run through the steps manually (useful in backend)
url = WhoopClient.auth_url(conf["client_id"], conf["client_secret"], conf["redirect_uri"])
# (open here or run a redirect on your backend)
webbrowser.open(url)
# retrieve code
code = input("Auth Code")
client = WhoopClient.authorize(code, conf["client_id"], conf["client_secret"], conf["redirect_uri"])

The code can be copied from the address in the browser (marked in bold):

http://localhost:1234/?code=j54Y9X...m4&scope=offline%20read...&state=9f..05

Note If you want to know more about this, see OAuth Flows

You can also provide a scope argument to limit what your client can read.

The system also allows to store, load and refresh your token (given that the offline scope is set):

# store the token
client.store_token(".tokens/token.json")

# load the token
client_new = WhoopClient.from_token(".tokens/token.json", config["client_id"], config["client_secret"])

# refresh the current token
client.refresh()

Data Retrieval

Once you have the client registered you can retrieve the data through the different sub-functions:

# user info
user_data = client.user.profile()
print(f"Name: {user_data.first_name} {user_data.last_name}")

# other data includes recovery, workout, cycle, sleep (all share the same interface)
# retrieve by single id
item = client.cycle.single("1234")
# this retrieves a list of items
items, _ = client.cycle.collection(start="2022-05-10", end="2022-07-03")
# note: whoop paginates these items - if you want to control the page yourself you can use the token
items1, token = client.cycle.collection(start="2022-05-10", end="2022-07-03", get_all_pages=False)
items2, token = client.cycle.collection(start="2022-05-10", end="2022-07-03", next=token, get_all_pages=False)
# retrieve data as pandas dataframe
df, _ = client.cycle.collection_df(start="2022-05-10", end="2022-07-03")

For a full description of the available routes, see official docs.

Tools

The repo also contains a dashboard to explore and download your whoop data using streamlit.

To get started, simply install the requirements in the tools/explorer folder:

pip install -r requirements.txt

Then run the streamlit app:

streamlit run explorer.py

This should give you the dashboard:

It also allows you to download your data directly: