aiogarmin

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

Features

• Fully async using the native Garmin Connect API
• 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 aiogarmin

Optional: install with improved browser UA generation:

pip install aiogarmin[ua]

Usage

import asyncio
import aiohttp
from datetime import date
from aiogarmin import GarminClient, GarminAuth

async def main():
    async with aiohttp.ClientSession() as session:
        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(session, 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

from homeassistant.helpers.aiohttp_client import async_get_clientsession

session = async_get_clientsession(hass)

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

client = GarminClient(session, 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