An unofficial Python client for the WHOOP API with support for both OAuth and Personal API keys. Features async/await support, automatic token refresh, and comprehensive data models.
- 🚀 Full API v2 Support - Access cycles, sleep, recovery, workouts, and user data
- ⚡ Async/Await Support - High-performance async client with synchronous wrapper
- 🔄 Automatic Token Management - Token refresh and persistence out of the box
- 📊 Pandas Integration - Export data directly to DataFrames for analysis
- 🛡️ Type Safety - Comprehensive type hints and Pydantic models
- 🔁 Retry Logic - Built-in retry with exponential backoff
- 🐍 Python 3.10+ - Modern Python with the latest features
pip install whoopyuv add whoopy# Clone the repository
git clone https://github.com/felixnext/whoopy.git
cd whoopy
# Install with uv (recommended)
uv sync --all-extras
# Or install with pip
pip install -e ".[dev]"- Go to the WHOOP Developer Dashboard
- Create a new application
- Note your
client_id,client_secret, and setredirect_uritohttp://localhost:1234
Create a config.json file:
{
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"redirect_uri": "http://localhost:1234"
}Note: The library also supports a nested config structure for backward compatibility:
{ "whoop": { "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "redirect_uri": "http://localhost:1234" } }
# Run the example script
uv run python -m tools.example
# Or if using standard Python
python -m tools.exampleNote: The redirect uri will not exist. You need to copy the entire url from your browser and paste it in the console. This will then handle the token exchange.
from whoopy import WhoopClient
from datetime import datetime, timedelta
# Initialize client (loads credentials from config.json)
client = WhoopClient.from_config()
# Get user profile
profile = client.user.get_profile()
print(f"Hello, {profile.first_name}!")
# Get recent recovery data
recoveries = client.recovery.get_all(
start=datetime.now() - timedelta(days=7),
end=datetime.now()
)
for recovery in recoveries:
print(f"Recovery: {recovery.score.recovery_score}%")
# Export to pandas DataFrame
df = client.sleep.get_dataframe(
start=datetime.now() - timedelta(days=30)
)
print(df.describe())import asyncio
from whoopy import WhoopClientV2
async def main():
# Use async context manager
async with WhoopClientV2.from_config() as client:
# Fetch multiple data types concurrently
profile, cycles, sleep = await asyncio.gather(
client.user.get_profile(),
client.cycles.get_all(limit_per_page=10),
client.sleep.get_all(limit_per_page=10)
)
print(f"User: {profile.first_name}")
print(f"Recent cycles: {len(cycles)}")
print(f"Recent sleep: {len(sleep)}")
# Run the async function
asyncio.run(main())# Option 1: Interactive OAuth flow (opens browser)
client = WhoopClient.auth_flow(
client_id="YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET",
redirect_uri="http://localhost:1234"
)
# Option 2: From existing token
client = WhoopClient.from_token(
access_token="YOUR_ACCESS_TOKEN",
refresh_token="YOUR_REFRESH_TOKEN",
client_id="YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET"
)
# Option 3: From config files (recommended)
client = WhoopClient.from_config()
# Save credentials for later use
client.save_token(".whoop_credentials.json")- Profile information
- Body measurements
- Cycles - Daily physiological cycles
- Recovery - Recovery metrics including HRV, resting heart rate
- Sleep - Sleep stages, efficiency, and performance
- Workouts - Exercise activities with strain and heart rate data
# Clone the repository
git clone https://github.com/felixnext/whoopy.git
cd whoopy
# Install with development dependencies
uv sync --all-extras# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=whoopy
# Run specific test file
uv run pytest tests/test_client.py# Run linting
uv run ruff check .
# Format code
uv run ruff format .
# Type checking
uv run mypy whoopy# Build wheel and sdist
uv build
# Install locally to test
uv pip install dist/whoopy-*.whlThe package includes a Streamlit-based data explorer for visualizing your WHOOP data:
# Install explorer dependencies
uv sync --extra explorer
# Run the explorer
cd tools/explorer && uv run streamlit run explorer.py- Interactive data visualization
- Date range filtering
- Export to CSV/Excel
- Recovery, sleep, and workout analysis
WhoopClient- Synchronous client (v2 API)WhoopClientV2- Async client (v2 API)WhoopClientV1- Legacy v1 client
# User data
profile = client.user.get_profile()
measurements = client.user.get_body_measurements()
# Cycles (daily summaries)
cycle = client.cycles.get_by_id(12345)
cycles = client.cycles.get_all(start="2024-01-01", end="2024-01-31")
# Sleep
sleep = client.sleep.get_by_id("uuid-here")
sleep_df = client.sleep.get_dataframe(start="2024-01-01")
# Recovery
recovery = client.recovery.get_for_cycle(12345)
recoveries = client.recovery.get_all()
# Workouts
workout = client.workouts.get_by_id("uuid-here")
workouts = client.workouts.get_by_sport("running", start="2024-01-01")Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Make your changes and add tests
- Run tests and linting (
uv run pytest && uv run ruff check) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
This is an unofficial client for the WHOOP API. It is not affiliated with, endorsed by, or in any way officially connected to WHOOP. Use at your own risk.
- Thanks to WHOOP for providing the official API
- Built with aiohttp and pydantic