README

PHP: Garmin Connect

A comprehensive PHP API wrapper for Garmin Connect, providing access to health, fitness, and device data. Works standalone or with Laravel.

About

This library enables developers to programmatically access Garmin Connect data including:

Health Metrics: Heart rate, sleep, stress, body battery, SpO2, HRV, respiration
Activity Data: Workouts, exercises, training status, performance metrics
Device Information: Connected devices, settings, alarms, solar data
Goals & Achievements: Personal records, badges, challenges
Body Composition: Weight tracking, blood pressure, hydration
Historical Data: Trends, progress tracking, date range queries

Based on the Python garminconnect library with OAuth authentication ported from garth.

Requirements

PHP 8.4+
ext-json
Guzzle ^7.5 (installed automatically)

Installation

composer require alexoid/laravel-garmin

Quick Start (Standalone)

use Alexoid\GarminConnect\GarminConnect;

// Login with credentials
$garmin = new GarminConnect(
    email: 'your@email.com',
    password: 'yourpassword',
);
$garmin->login('~/.garminconnect');

// Subsequent runs — tokens are reused automatically
$garmin = new GarminConnect();
$garmin->login('~/.garminconnect');

// Get data
$summary = $garmin->getUserSummary('2026-03-02');
echo "Steps: " . $summary['totalSteps'];

$hr = $garmin->getHeartRates('2026-03-02');
echo "Resting HR: " . $hr['restingHeartRate'];

$activities = $garmin->getActivities(0, 10);

MFA (Two-Factor Authentication)

If your account has MFA enabled, use the non-blocking mode:

$garmin = new GarminConnect(
    email: 'your@email.com',
    password: 'yourpassword',
    returnOnMfa: true,
);

[$status, $clientState] = $garmin->login();

if ($status === 'needs_mfa') {
    $mfaCode = readline('MFA code: '); // or get from your UI
    $garmin->resumeLogin($clientState, $mfaCode, '~/.garminconnect');
}

// Now authenticated
$summary = $garmin->getUserSummary(date('Y-m-d'));

Or use the blocking MfaHandler interface for CLI apps:

use Alexoid\GarminConnect\Auth\MfaHandler;

class CliMfaHandler implements MfaHandler
{
    public function promptMfaCode(): string
    {
        echo "Enter MFA code: ";
        return trim(fgets(STDIN));
    }
}

$garmin = new GarminConnect(
    email: 'your@email.com',
    password: 'yourpassword',
    mfaHandler: new CliMfaHandler(),
);
$garmin->login('~/.garminconnect');

Quick Start (Laravel)

Publish the config:

php artisan vendor:publish --tag=garminconnect-config

Set environment variables:

GARMIN_EMAIL=your@email.com
GARMIN_PASSWORD=yourpassword
GARMIN_DOMAIN=garmin.com
GARMIN_TOKEN_STORE=file
GARMIN_TOKEN_PATH=/path/to/tokens

php artisan garmin:login

Use the Facade:

use Alexoid\GarminConnect\Laravel\GarminConnect;

GarminConnect::login();

$stats = GarminConnect::getUserSummary(now()->format('Y-m-d'));
$hr = GarminConnect::getHeartRates(now()->format('Y-m-d'));

Token Storage

Tokens are persisted so you don't need to re-authenticate on every request.

Store	Class	Use Case
File (default)	`FileTokenStore`	JSON files in `~/.garminconnect`
Laravel Cache	`LaravelCacheTokenStore`	Redis, Memcached, etc.
Null	`NullTokenStore`	In-memory only, no persistence
Custom	Implement `TokenStoreInterface`	Database, S3, etc.

Examples

The examples/ directory contains working code you can run or copy into your project:

File	Description
`example.php`	Standalone CLI — run `php examples/example.php` for an interactive demo of login, MFA, and all major API calls
`laravel-mfa-login.php`	Laravel controller — copy to `app/Http/Controllers/`, add a route, and get a two-step login endpoint with MFA support (auth state saved in session between requests)
`laravel-activity-sync.php`	Artisan command — copy to `app/Console/Commands/`, run `php artisan garmin:sync {user_id}` to sync strength training workouts into your database (paginated fetch, exercise set parsing, incremental sync, transaction import)

Available Methods (105)

Profile (6 methods)

Method	Description
`getUserProfile()`	Get user settings
`getSocialProfile()`	Get social profile (displayName, fullName)
`getUserprofileSettings()`	Get profile settings
`getPersonalRecord()`	Get personal records
`requestReload(string $cdate)`	Request data reload for date
`queryGarminGraphql(array $query)`	Execute GraphQL query

User Stats (10 methods)

Method	Description
`getUserSummary(string $cdate)`	Daily summary (steps, calories, distance)
`getStats(string $cdate)`	Alias for getUserSummary
`getStepsData(string $cdate)`	Detailed step data
`getFloors(string $cdate)`	Floor climbing data
`getDailySteps(string $start, string $end)`	Steps for date range
`getWeeklySteps(string $end, int $weeks = 52)`	Weekly step aggregation
`getWeeklyStress(string $end, int $weeks = 52)`	Weekly stress aggregation
`getWeeklyIntensityMinutes(string $start, string $end)`	Weekly intensity minutes
`getStatsAndBody(string $cdate)`	Combined stats + body data
`getProgressSummaryBetweenDates(string $startdate, string $enddate)`	Progress summary

Heart Rate (3 methods)

Method	Description
`getHeartRates(string $cdate)`	Daily heart rate data
`getRhrDay(string $cdate)`	Resting heart rate
`getHrvData(string $cdate)`	Heart rate variability

Wellness (10 methods)

Method	Description
`getSleepData(string $cdate)`	Sleep duration, quality, score
`getStressData(string $cdate)`	Daily stress data
`getAllDayStress(string $cdate)`	All day stress with values array
`getAllDayEvents(string $cdate)`	All day wellness events
`getBodyBattery(string $startdate, ?string $enddate = null)`	Body battery levels
`getBodyBatteryEvents(string $cdate)`	Body battery events
`getRespirationData(string $cdate)`	Breathing rate
`getSpo2Data(string $cdate)`	Blood oxygen saturation
`getIntensityMinutesData(string $cdate)`	Intensity minutes
`getLifestyleLoggingData(string $cdate)`	Lifestyle logging

Activities (10 methods)

Method	Description
`countActivities()`	Total activity count
`getActivities(int $start = 0, int $limit = 20, ?string $activityType = null)`	List activities (paginated)
`getActivitiesForDate(string $fordate)`	Activities for specific date
`getActivitiesByDate(string $startdate, ?string $enddate = null, ?string $activityType = null, ?string $sortOrder = null)`	Activities in date range
`getLastActivity()`	Most recent activity
`setActivityName(string $activityId, string $title)`	Rename activity
`setActivityType(string $activityId, int $typeId, string $typeKey, int $parentTypeId)`	Change activity type
`getActivityTypes()`	Available activity types
`createManualActivity(string $startDatetime, string $timeZone, string $typeKey, float $distanceKm, int $durationMin, string $activityName)`	Create manual activity
`createManualActivityFromJson(array $payload)`	Create from JSON payload

Activity Details (9 methods)

Method	Description
`getActivity(string $activityId)`	Full activity data
`getActivityDetails(string $activityId, int $maxChartSize = 1000, int $maxPolylineSize = 4000)`	Detailed metrics
`getActivitySplits(string $activityId)`	Activity splits
`getActivityTypedSplits(string $activityId)`	Typed splits
`getActivitySplitSummaries(string $activityId)`	Split summaries
`getActivityWeather(string $activityId)`	Weather during activity
`getActivityHrInTimezones(string $activityId)`	HR in time zones
`getActivityPowerInTimezones(string $activityId)`	Power in time zones
`getActivityExerciseSets(string\|int $activityId)`	Exercise sets

Downloads (2 methods)

Method	Description
`downloadActivity(string $activityId, ActivityDownloadFormat $format = TCX)`	Download activity file (TCX, GPX, KML, CSV, ORIGINAL)
`downloadWorkout(string\|int $workoutId)`	Download workout FIT file

Devices (6 methods)

Method	Description
`getDevices()`	List connected devices
`getDeviceSettings(string $deviceId)`	Device settings
`getPrimaryTrainingDevice()`	Primary training device
`getDeviceSolarData(string $deviceSerial, string $end, int $weeks = 52)`	Solar charging data
`getDeviceAlarms()`	Device alarms
`getDeviceLastUsed()`	Last used device

Health (13 methods)

Method	Description
`getBodyComposition(string $startdate, ?string $enddate = null)`	Body composition data
`getWeighIns(string $startdate, string $enddate)`	Weight measurements
`getDailyWeighIns(string $cdate)`	Daily weigh-ins
`addWeighIn(int\|float $weight, string $unitKey = 'kg', string $timestamp = '')`	Add weight entry
`deleteWeighIn(string $weightPk, string $cdate)`	Delete weight entry
`getBloodPressure(string $startdate, ?string $enddate = null)`	Blood pressure data
`setBloodPressure(int $systolic, int $diastolic, int $pulse, string $timestamp = '', string $notes = '')`	Record blood pressure
`deleteBloodPressure(string $version, string $cdate)`	Delete BP reading
`getHydrationData(string $cdate)`	Hydration intake
`addHydrationData(float $valueInMl, ?string $timestamp = null, ?string $cdate = null)`	Add hydration entry
`getMenstrualDataForDate(string $fordate)`	Menstrual cycle data
`getMenstrualCalendarData(string $startdate, string $enddate)`	Menstrual calendar
`getPregnancySummary()`	Pregnancy summary

Metrics (7 methods)

Method	Description
`getMaxMetrics(string $cdate)`	VO2Max, fitness metrics
`getLactateThreshold(bool $latest = true, ?string $startDate = null, ?string $endDate = null, string $aggregation = 'daily')`	Lactate threshold data
`getEnduranceScore(string $cdate, int $branch = 1)`	Endurance score
`getRacePredictions()`	Race predictions (latest)
`getHillScore(string $cdate, int $branch = 1)`	Hill score
`getCyclingFtp(string $activityId)`	Cycling FTP
`getFitnessAgeData(string $cdate)`	Fitness age

Training (6 methods)

Method	Description
`getTrainingReadiness(string $cdate)`	Training readiness
`getMorningTrainingReadiness(string $cdate)`	Morning readiness
`getTrainingStatus(string $cdate)`	Training status
`getTrainingPlans()`	All training plans
`getTrainingPlanById(string\|int $planId)`	Specific training plan
`getAdaptiveTrainingPlanById(string\|int $planId)`	Adaptive training plan

Badges & Challenges (8 methods)

Method	Description
`getEarnedBadges()`	Earned badges
`getAvailableBadges()`	Available badges
`getInProgressBadges()`	In-progress badges
`getAdhocChallenges(int $start = 1, int $limit = 100)`	Ad-hoc challenges
`getBadgeChallenges(int $start = 1, int $limit = 100)`	Badge challenges
`getAvailableBadgeChallenges(int $start = 1, int $limit = 100)`	Available badge challenges
`getNonCompletedBadgeChallenges(int $start = 1, int $limit = 100)`	Non-completed challenges
`getInProgressVirtualChallenges(int $start = 1, int $limit = 100)`	In-progress virtual challenges

Gear (8 methods)

Method	Description
`getGear(string $userProfileNumber)`	Get all gear
`getGearStats(string $gearUUID)`	Gear statistics
`getGearDefaults(string $userProfileNumber)`	Default gear
`setGearDefault(string $userProfileNumber, string $gearUUID, string $equipmentCategory)`	Set default gear
`getActivityGear(string\|int $activityId)`	Gear used in activity
`getGearActivities(string $gearUUID, int $start = 0, int $limit = 100)`	Activities with gear
`addGearToActivity(string $activityId, string $gearUUID)`	Add gear to activity
`removeGearFromActivity(string $activityId, string $gearUUID)`	Remove gear from activity

Goals (1 method)

Method	Description
`getGoals(string $status = 'active', int $start = 1, int $limit = 50)`	Goals by status (active, future, past)

Uploads (6 methods)

Method	Description
`uploadActivity(string $activityPath)`	Upload FIT/GPX/TCX activity
`deleteActivity(string $activityId)`	Delete activity
`uploadWorkout(array\|string $workoutJson)`	Upload workout
`deleteWorkout(string\|int $workoutId)`	Delete workout
`getWorkouts(int $start = 0, int $limit = 100)`	List workouts
`getWorkoutById(string\|int $workoutId)`	Get specific workout

Testing

vendor/bin/phpunit
vendor/bin/phpunit --testdox  # verbose output

Development

# Install dependencies
composer install

# Run tests
vendor/bin/phpunit

# Static analysis
vendor/bin/phpstan analyse

# Code formatting
vendor/bin/php-cs-fixer fix

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/new-endpoint)
Make your changes
Run tests (vendor/bin/phpunit)
Submit a pull request

License

MIT License. See LICENSE for details.

alexoid / laravel-garmin

Maintainers

Details