garmer

Garmer - Garmin Data Extraction Skill

This skill enables extraction of health and fitness data from Garmin Connect for analysis and insights.

Prerequisites

1. A Garmin Connect account with health data
2. The garmer CLI tool installed (see installation options in metadata)

Authentication (One-Time Setup)

Before using garmer, authenticate with Garmin Connect:

garmer login

This will prompt for your Garmin Connect email and password. Tokens are saved to ~/.garmer/garmin_tokens for future use.

To check authentication status:

garmer status

Available Commands

Daily Summary

Get today's health summary (steps, calories, heart rate, stress):

garmer summary
# For a specific date:
garmer summary --date 2025-01-15
# Include last night's sleep data:
garmer summary --with-sleep
garmer summary -s
# JSON output for programmatic use:
garmer summary --json
# Combine flags:
garmer summary --date 2025-01-15 --with-sleep --json

Sleep Data

Get sleep analysis (duration, phases, score, HRV):

garmer sleep
# For a specific date:
garmer sleep --date 2025-01-15

Activities

List recent fitness activities:

garmer activities
# Limit number of results:
garmer activities --limit 5
# Filter by specific date:
garmer activities --date 2025-01-15
# JSON output for programmatic use:
garmer activities --json

Activity Detail

Get detailed information for a single activity:

# Latest activity:
garmer activity
# Specific activity by ID:
garmer activity 12345678
# Include lap data:
garmer activity --laps
# Include heart rate zone data:
garmer activity --zones
# JSON output:
garmer activity --json
# Combine flags:
garmer activity 12345678 --laps --zones --json

Health Snapshot

Get comprehensive health data for a day:

garmer snapshot
# For a specific date:
garmer snapshot --date 2025-01-15
# As JSON for programmatic use:
garmer snapshot --json

Export Data

Export multiple days of data to JSON:

# Last 7 days (default)
garmer export

# Custom date range
garmer export --start-date 2025-01-01 --end-date 2025-01-31 --output my_data.json

# Last N days
garmer export --days 14

Utility Commands

# Update garmer to latest version (git pull):
garmer update

# Show version information:
garmer version

Python API Usage

For more complex data processing, use the Python API:

from garmer import GarminClient
from datetime import date, timedelta

# Use saved tokens
client = GarminClient.from_saved_tokens()

# Or login with credentials
client = GarminClient.from_credentials(email="user@example.com", password="pass")

User Profile

# Get user profile
profile = client.get_user_profile()
print(f"User: {profile.display_name}")

# Get registered devices
devices = client.get_user_devices()

Daily Summary

# Get daily summary (defaults to today)
summary = client.get_daily_summary()
print(f"Steps: {summary.total_steps}")

# Get for specific date
summary = client.get_daily_summary(date(2025, 1, 15))

# Get weekly summary
weekly = client.get_weekly_summary()

Sleep Data

# Get sleep data (defaults to today)
sleep = client.get_sleep()
print(f"Sleep: {sleep.total_sleep_hours:.1f} hours")

# Get last night's sleep
sleep = client.get_last_night_sleep()

# Get sleep for date range
sleep_data = client.get_sleep_range(
    start_date=date(2025, 1, 1),
    end_date=date(2025, 1, 7)
)

Activities

# Get recent activities
activities = client.get_recent_activities(limit=5)
for activity in activities:
    print(f"{activity.activity_name}: {activity.distance_km:.1f} km")

# Get activities with filters
activities = client.get_activities(
    start_date=date(2025, 1, 1),
    end_date=date(2025, 1, 31),
    activity_type="running",
    limit=20
)

# Get single activity by ID
activity = client.get_activity(12345678)

Heart Rate

# Get heart rate data for a day
hr = client.get_heart_rate()
print(f"Resting HR: {hr.resting_heart_rate} bpm")

# Get just resting heart rate
resting_hr = client.get_resting_heart_rate(date(2025, 1, 15))

Stress & Body Battery

# Get stress data
stress = client.get_stress()
print(f"Avg stress: {stress.avg_stress_level}")

# Get body battery data
battery = client.get_body_battery()

Steps

# Get detailed step data
steps = client.get_steps()
print(f"Total: {steps.total_steps}, Goal: {steps.step_goal}")

# Get just total steps
total = client.get_total_steps(date(2025, 1, 15))

Body Composition

# Get latest weight
weight = client.get_latest_weight()
print(f"Weight: {weight.weight_kg} kg")

# Get weight for specific date
weight = client.get_weight(date(2025, 1, 15))

# Get full body composition
body = client.get_body_composition()

Hydration & Respiration

# Get hydration data
hydration = client.get_hydration()
print(f"Intake: {hydration.total_intake_ml} ml")

# Get respiration data
resp = client.get_respiration()
print(f"Avg breathing: {resp.avg_waking_respiration} breaths/min")

Comprehensive Reports

# Get health snapshot (all metrics for a day)
snapshot = client.get_health_snapshot()
# Returns: daily_summary, sleep, heart_rate, stress, steps, hydration, respiration

# Get weekly health report with trends
report = client.get_weekly_health_report()
# Returns: activities summary, sleep stats, steps stats, HR trends, stress trends

# Export data for date range
data = client.export_data(
    start_date=date(2025, 1, 1),
    end_date=date(2025, 1, 31),
    include_activities=True,
    include_sleep=True,
    include_daily=True
)

Common Workflows

Health Check Query

When a user asks "How did I sleep?" or "What's my health summary?":

garmer snapshot --json

Activity Analysis

When a user asks about workouts or exercise:

garmer activities --limit 10

Trend Analysis

When analyzing health trends over time:

garmer export --days 30 --output health_data.json

Then process the JSON file with Python for analysis.

Data Types Available

• Activities: Running, cycling, swimming, strength training, etc.
• Sleep: Duration, phases (deep, light, REM), score, HRV
• Heart Rate: Resting HR, samples, zones
• Stress: Stress levels, body battery
• Steps: Total steps, distance, floors
• Body Composition: Weight, body fat, muscle mass
• Hydration: Water intake tracking
• Respiration: Breathing rate data

Error Handling

If not authenticated:

Not logged in. Use 'garmer login' first.

If session expired, re-authenticate:

garmer login

Environment Variables

• GARMER_TOKEN_DIR: Custom directory for token storage
• GARMER_LOG_LEVEL: Set logging level (DEBUG, INFO, WARNING, ERROR)
• GARMER_CACHE_ENABLED: Enable/disable data caching (true/false)

References

For detailed API documentation and MoltBot integration examples, see references/REFERENCE.md.