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)
    # You can access resources directly:
    profile = client.user.get_profile()
    # Or use method aliases for shorter syntax:
    profile = client.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).

Method Aliases

All resource methods are available directly from the client instance. This means you can use:

# Short form with method aliases
client.get_profile()
client.get_daily_activity_summary(date="2025-03-06")
client.get_sleep_log_by_date(date="2025-03-06")

Instead of the longer form:

# Standard resource access
client.user.get_profile()
client.activity.get_daily_activity_summary(date="2025-03-06")
client.sleep.get_sleep_log_by_date(date="2025-03-06")

Both approaches are equivalent, but aliases provide a more concise syntax.

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
    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 The token_cache_path parameter allows you to persist authentication tokens between sessions. If provided, the client will:

4. Load existing tokens from this file if available (avoiding re-authentication)

5. Save new or refreshed tokens to this file automatically

6. 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. Set Callback URL to "https://localhost:8080" (or your preferred local URL)
5. 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

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! 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.