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

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="YOUR_REGISTERED_REDIRECT_URI",
    token_cache_path="/tmp/fb_tokens.json"  # Optional: saves tokens between sessions
)

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

The token_cache_path parameter allows you to persist authentication tokens between sessions. If provided, the client will:

1. Load existing tokens from this file if available (avoiding re-authentication)
2. Save new or refreshed tokens to this file automatically
3. Handle token refresh when expired tokens are detected

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 "https://localhost:8080" (or your preferred local URL)
4. Copy your Client ID and Client Secret

Additional Documentation

For API Library Users

• LOGGING.md: Understanding the dual-logger system
• TYPES.md: JSON type system and method return types
• NAMING.md: API method naming conventions
• VALIDATIONS.md: Input parameter validation
• ERROR_HANDLING.md: Exception hierarchy and handling

It's also worth reviewing Fitbit's Best Practices for API usage.

Project Best Practices

• DEVELOPMENT.md: Development environment and guidelines
• STYLE.md: Code style and formatting standards

Important Note - Subscription Support

This client does not currently support the creation and deletion of webhook subscriptions. The methods are implemented in comments and should work, but I have not had a chance to verify them since this requires a publicly accessible server to receive webhook notifications.

If you're using this library with subscriptions and would like to help test and implement this functionality, please open an issue or pull request!

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.