WHOOP Data Export Tool

A Python script to export your WHOOP fitness data via the official WHOOP API with OAuth2 authentication.

Features

• 🔐 Secure OAuth2 Authentication - Uses official WHOOP API with proper token management
• 📊 Comprehensive Data Export - Exports all major data types:
  • User profile and body measurements
  • Physiological cycles
  • Sleep data
  • Recovery metrics
  • Workout records
• 🇬🇧 UK Date Formatting - All dates formatted as DD/MM/YYYY
• 📁 Multiple Formats - Exports to both JSON and CSV formats
• 🔄 Automatic Token Refresh - Handles token expiration automatically
• ⚡ Rate Limiting - Respects API rate limits

Prerequisites

1. WHOOP Developer Account - Create an app at WHOOP Developer Dashboard
2. Python 3.7+ with required packages:

   pip install requests flask python-dotenv

3. ngrok (for OAuth callback) - Download from ngrok.com

Setup

1. Clone this repository:

   git clone <repository-url>
   cd whoop-backup

2. Create .env file with your WHOOP app credentials:

   WHOOP_CLIENT_ID=your_client_id_here
   WHOOP_CLIENT_SECRET=your_client_secret_here
   REDIRECT_URI=https://your-ngrok-url.ngrok-free.app/callback
   SCOPES=offline read:profile read:body_measurement read:cycles read:sleep read:recovery read:workout

3. Start ngrok (in a separate terminal):

   ngrok http 5057

   Copy the HTTPS URL and update REDIRECT_URI in your .env file.

4. Update WHOOP App Settings - Add the ngrok callback URL to your WHOOP app's redirect URIs.

Usage

1. Run the export script:

   python3 whoop_export.py

2. First-time setup:

   • Script will start a local server at http://localhost:5057/
   • Open the URL in your browser
   • Sign in to WHOOP and authorize the app
   • Script will automatically proceed to export data

3. Subsequent runs:

   • Script will use saved tokens and export data directly
   • Tokens are automatically refreshed when needed

Output

Data is exported to the ./whoop_export/ directory:

JSON Files

• user_profile.json - Basic profile information
• body_measurement.json - Height, weight, max heart rate

CSV Files (UK Date Format)

• cycles.csv - Physiological cycles with strain and heart rate data
• sleeps.csv - Sleep stages, performance, and efficiency metrics
• recoveries.csv - Recovery scores and HRV data
• workouts.csv - Workout activities with strain and heart rate

Data Privacy

• All data remains on your local machine
• Tokens are stored locally in whoop_export/tokens.json
• No data is sent to third parties
• .env and token files are excluded from git tracking

Troubleshooting

Common Issues

1. 401 Unauthorized Error:

   • Check your client ID and secret in .env
   • Ensure redirect URI matches exactly (including ngrok URL)
   • Re-authorize if tokens have expired

2. Callback URL Issues:

   • Verify ngrok is running and URL is correct
   • Check WHOOP app settings include the callback URL
   • Ensure URL uses HTTPS (not HTTP)

3. Rate Limiting:

   • Script includes automatic rate limiting
   • Large data exports may take several minutes

Re-authorization

To re-authorize (if tokens become invalid):

rm whoop_export/tokens.json
python3 whoop_export.py

API Documentation

For more information about the WHOOP API:

• WHOOP Developer Documentation
• OAuth 2.0 Guide
• API Reference

License

This project is for personal use. Please respect WHOOP's Terms of Service and API usage guidelines.