README.md

Python API Client for Fitbit™

Fitbit Client

A fully-typed Python client for interacting with the Fitbit API, featuring OAuth2 PKCE authentication and resource-based API interactions.

Installation

This package requires Python 3.13 or later.

Once published, install like this:

pdm add fitbit-client-python # or your dependency manager of choice

For now, you can use it from Github.

Quick Start

from fitbit_client import FitbitClient
from json import dumps

# Initialize client
client = FitbitClient(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    redirect_uri="https://localhost:8080"
)

try:
    # Authenticate (opens browser automatically)
    client.authenticate()
    
    # Make a request (e.g., get user profile)
    profile = client.user.get_profile()
    print(dumps(profile, indent=2))
    
except Exception as e:
    print(f"Error: {str(e)}")

The response will always be the body of the API response, and is almost always a Dict, List or None. nutrition.get_activity_tcx is the exception. It returns XML (as a str).

Authentication Methods

1. Automatic (Recommended)

Uses a local callback server to automatically handle the OAuth2 flow:

client = FitbitClient(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    redirect_uri="https://localhost:8080",
    use_callback_server=True  # default is True
)

# Will open browser and handle callback automatically
client.authenticate()

2. Manual URL Copy/Paste

If you prefer not to use a local server:

client = FitbitClient(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    redirect_uri="YOUR_REGISTERED_REDIRECT_URI",
    token_cache_path="/tmp/fb_tokens.json",
    use_callback_server=True
)

# Will open a browser and start a server to complete the flow (default), or 
# prompt you on the command line to copy/paste the callback URL from the 
# browser (see `use_callback_server`)
client.authenticate()

Setting Up Your Fitbit App

1. Go to dev.fitbit.com and create a new application
2. Set OAuth 2.0 Application Type to "Personal"
3. Set Callback URL to:
   • For automatic method: "https://localhost:8080"
   • For manual method: Your preferred redirect URI
4. Copy your Client ID and Client Secret

Additional documentation:

• To understand the logging implemementation, see LOGGING
• To understand validations and the exception hierarchy, see VALIDATIONS_AND_EXCEPTIONS
• It's work checking out Fitbit's Best Practices
• For some general development guidelines, see DEVELOPMENT.
• For style guidelines (mostly enforced through varius linters and formatters) see STYLE.

Important Note - Subscription Support

This client does not currently support the creation and deletion of webhook subscrptions. The methods are implemented in comments and should work, but I have not had a chance to verify a user confirm this.

License

Copyright (C) 2025 Jon Stroop

This program is licensed under the GNU Affero General Public License Version 3.0 (AGPL-3.0). See the LICENSE file for details.

Disclaimer

Fitbit™ is a trademark of Google LLC. This project is designed for use with the Fitbit API but is not endorsed, certified, or otherwise approved by Google or Fitbit.