# Whoop Python Client
This is an unofficial implementation of the [official Whoop API](https://developer.whoop.com/docs/introduction).
## Getting Started
First you will need to install the library:
```bash
# 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:
```bash
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](https://developer-dashboard.whoop.com/) 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`):
```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:
```python
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](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow)
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):
```python
# 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:
```python
# 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](https://developer.whoop.com/api).
## 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:
```bash
pip install -r requirements.txt
```
Then run the streamlit app:
```bash
streamlit run explorer.py
```
This should give you the dashboard:
It also allows you to download your data directly:
Raw data
{
"_id": null,
"home_page": "https://github.com/felixnext/whoopy",
"name": "whoopy",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "whoop api",
"author": "Felix Geilert",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/cc/4a/3e0596697464008b8500a3bae1ead2b32c57a2aee420a40c3d6f188d960a/whoopy-0.2.1.tar.gz",
"platform": null,
"description": "# Whoop Python Client\n\nThis is an unofficial implementation of the [official Whoop API](https://developer.whoop.com/docs/introduction).\n\n## Getting Started\n\nFirst you will need to install the library:\n\n```bash\n# either from pypi\npip install whoopy\n# or by local build\npip install .\n```\n\nFor development you can install the `requirements.txt` or the `env.yaml` conda environment:\n\n```bash\npip install -r requirements.txt\n# or\nconda env create -f env.yaml\n```\n\nIn order to use the API, you will need to register your application [here](https://developer-dashboard.whoop.com/) and\nenter the `client_id`, `client_secret` and `redirect_uri` in the `config.json` file (you can use the template provided in `config.sample.json`):\n\n```json\n{\n \"client_id\": \"YOUR_CLIENT_ID\",\n \"client_secret\": \"YOUR_CLIENT_SECRET\",\n \"redirect_uri\": \"YOUR_REDIRECT_URI\"\n}\n```\n\n> Note: For the purposes of local use, you can simply provide `http://localhost:1234` as redirect_uri in the app registration\n\n### Authorization\n\nYou can then the config to run through the client authentication and save the token:\n\n```python\nimport json\nfrom whoopy import WhoopClient\n\n# load the config\nconf = json.load(open(\"config.json\", \"r\"))\n\n# either run through full auth process (useful in jupyter notebooks)\n# note: This will open the web browser and require you to copy the code parameter from the resulting uri back\nclient = WhoopClient.auth_flow(conf[\"client_id\"], conf[\"client_secret\"], conf[\"redirect_uri\"])\n\n# or run through the steps manually (useful in backend)\nurl = WhoopClient.auth_url(conf[\"client_id\"], conf[\"client_secret\"], conf[\"redirect_uri\"])\n# (open here or run a redirect on your backend)\nwebbrowser.open(url)\n# retrieve code\ncode = input(\"Auth Code\")\nclient = WhoopClient.authorize(code, conf[\"client_id\"], conf[\"client_secret\"], conf[\"redirect_uri\"])\n```\n\nThe code can be copied from the address in the browser (marked in bold):\n\n`http://localhost:1234/?code=`**`j54Y9X...m4`**`&scope=offline%20read...&state=9f..05`\n\n> **Note** If you want to know more about this, see [OAuth Flows](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow)\n\nYou can also provide a `scope` argument to limit what your client can read.\n\nThe system also allows to store, load and refresh your token (given that the `offline` scope is set):\n\n```python\n# store the token\nclient.store_token(\".tokens/token.json\")\n\n# load the token\nclient_new = WhoopClient.from_token(\".tokens/token.json\", config[\"client_id\"], config[\"client_secret\"])\n\n# refresh the current token\nclient.refresh()\n```\n\n### Data Retrieval\n\nOnce you have the client registered you can retrieve the data through the different sub-functions:\n\n```python\n# user info\nuser_data = client.user.profile()\nprint(f\"Name: {user_data.first_name} {user_data.last_name}\")\n\n# other data includes recovery, workout, cycle, sleep (all share the same interface)\n# retrieve by single id\nitem = client.cycle.single(\"1234\")\n# this retrieves a list of items\nitems, _ = client.cycle.collection(start=\"2022-05-10\", end=\"2022-07-03\")\n# note: whoop paginates these items - if you want to control the page yourself you can use the token\nitems1, token = client.cycle.collection(start=\"2022-05-10\", end=\"2022-07-03\", get_all_pages=False)\nitems2, token = client.cycle.collection(start=\"2022-05-10\", end=\"2022-07-03\", next=token, get_all_pages=False)\n# retrieve data as pandas dataframe\ndf, _ = client.cycle.collection_df(start=\"2022-05-10\", end=\"2022-07-03\")\n```\n\nFor a full description of the available routes, see [official docs](https://developer.whoop.com/api).\n\n## Tools\n\nThe repo also contains a dashboard to explore and download your whoop data using streamlit.\n\nTo get started, simply install the requirements in the `tools/explorer` folder:\n\n```bash\npip install -r requirements.txt\n```\n\nThen run the streamlit app:\n\n```bash\nstreamlit run explorer.py\n```\n\nThis should give you the dashboard:\n\n\nIt also allows you to download your data directly:\n\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Unofficial Client for the Whoop API",
"version": "0.2.1",
"project_urls": {
"Download": "https://github.com/felixnext/whoopy/releases/tag/v0.2.1",
"Homepage": "https://github.com/felixnext/whoopy"
},
"split_keywords": [
"whoop",
"api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "04ece0384c9e263b8e88aa1bd50fb3b95eedd79e0f7f24d317690265ec5640ef",
"md5": "a7e00c21988c4c82df7c04e04322e5e8",
"sha256": "07a1755c998fcabd2717421702e77cf208624b65790abb6dd11e78540be92fe9"
},
"downloads": -1,
"filename": "whoopy-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a7e00c21988c4c82df7c04e04322e5e8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 17509,
"upload_time": "2024-06-16T13:17:35",
"upload_time_iso_8601": "2024-06-16T13:17:35.554140Z",
"url": "https://files.pythonhosted.org/packages/04/ec/e0384c9e263b8e88aa1bd50fb3b95eedd79e0f7f24d317690265ec5640ef/whoopy-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cc4a3e0596697464008b8500a3bae1ead2b32c57a2aee420a40c3d6f188d960a",
"md5": "655a3e6a2d0af7eaf52f45775cf663e1",
"sha256": "8bbb96ec84d3a77cc8244dc7d61a1b279a3aa050a4bee2553488c7696775bdba"
},
"downloads": -1,
"filename": "whoopy-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "655a3e6a2d0af7eaf52f45775cf663e1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 18375,
"upload_time": "2024-06-16T13:17:37",
"upload_time_iso_8601": "2024-06-16T13:17:37.931713Z",
"url": "https://files.pythonhosted.org/packages/cc/4a/3e0596697464008b8500a3bae1ead2b32c57a2aee420a40c3d6f188d960a/whoopy-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-16 13:17:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "felixnext",
"github_project": "whoopy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pydantic",
"specs": [
[
">=",
"1.10.2"
]
]
},
{
"name": "python_dateutil",
"specs": [
[
">=",
"2.8.2"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.28.1"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.4.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.23.0"
]
]
},
{
"name": "time_helper",
"specs": [
[
">=",
"0.1.4"
]
]
}
],
"lcname": "whoopy"
}
JSON
