ha-garmin

Python client for Garmin Connect API, designed for Home Assistant integration.

Features

• Native Garmin Connect API integration
• Robust authentication with multiple login strategies and automatic fallback
• MFA support with automatic endpoint fallback
• Token persistence - save and restore sessions to avoid re-login
• Automatic token refresh - proactively refreshes before expiry
• Retry with backoff for rate limits (429) and server errors (5xx)
• Midnight fallback - automatically uses yesterday's data when today isn't ready yet
• Coordinator-based fetch - optimized data fetching for Home Assistant multi-coordinator pattern
• Data transformations - automatic unit conversions (seconds→minutes, grams→kg)

Installation

pip install ha-garmin

Optional: install with improved browser UA generation:

pip install ha-garmin[ua]

Usage

from datetime import date
from ha_garmin import GarminClient, GarminAuth

async def main():
    auth = GarminAuth()

    # Load saved session from disk
    if not auth.load_session(".garmin_tokens.json"):
        await auth.login("email@example.com", "password")

        # Handle MFA if required
        if not auth.is_authenticated:
            mfa_code = input("Enter MFA code: ")
            await auth.complete_mfa(mfa_code)

        auth.save_session(".garmin_tokens.json")

    client = GarminClient(auth)

    today = date.today()
    core_data     = await client.fetch_core_data(today)      # Steps, HR, sleep, stress
    body_data     = await client.fetch_body_data(today)      # Weight, body composition, fitness age
    activity_data = await client.fetch_activity_data(today)  # Activities, workouts
    training_data = await client.fetch_training_data(today)  # HRV, training status
    goals_data    = await client.fetch_goals_data()          # Goals, badges
    gear_data     = await client.fetch_gear_data()           # Gear, device alarms

For Home Assistant

auth = GarminAuth()
auth.load_session(config_dir / "garmin_tokens.json")

client = GarminClient(auth)

core_data = await client.fetch_core_data(target_date=date.today())
body_data = await client.fetch_body_data(target_date=date.today())

Coordinator Fetch Methods

Optimized methods that group related API calls for Home Assistant coordinators:

Individual API Methods

Data Transformations

The library automatically adds computed fields for convenience:

• Time conversions: sleepTimeSeconds → sleepTimeMinutes
• Activity time: highlyActiveSeconds → highlyActiveMinutes
• Weight: weight (grams) → weightKg
• Stress: stressQualifier → stressQualifierText (capitalized)
• Nested flattening: HRV status, training readiness, scores

License

MIT