PHPackages                             jinchun/php-garmin-connect-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. jinchun/php-garmin-connect-api

ActiveLibrary

jinchun/php-garmin-connect-api
==============================

PHP library to connect and use garmin wellness api

08PHP

Since Sep 22Pushed 7mo agoCompare

[ Source](https://github.com/jinchun/php-garmin-connect-api)[ Packagist](https://packagist.org/packages/jinchun/php-garmin-connect-api)[ RSS](/packages/jinchun-php-garmin-connect-api/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Table of contents
=================

[](#table-of-contents)

- [Table of contents](#table-of-contents)
- [Description](#description)
- [Installtion](#installtion)
- [Version Support](#version-support)
- [HTTP Client Configuration](#http-client-configuration)
- [Example](#example)
- [Usage](#usage)
    - [Get authorization link](#get-authorization-link)
    - [Get token credentials](#get-token-credentials)
    - [Get Garmin user id](#get-garmin-user-id)
    - [Backfill activities](#backfill-activities)
    - [Deregistration](#deregistration)
    - [Avalaible methods (for the moment)](#avalaible-methods-for-the-moment)
        - [Get summary activities](#get-summary-activities)
        - [Backfill activities](#backfill-activities-1)

Description
===========

[](#description)

PHP library to connect and use garmin wellness api

Version Support
===============

[](#version-support)

This library now supports both **Chinese** and **International** versions of Garmin Connect API:

- **International Version** (default): Uses `connectapi.garmin.com` and `healthapi.garmin.com`
- **Chinese Version**: Uses `connectapi.garmin.cn` (OAuth) and `gcs-wellness.garmin.cn` (Health REST API)

Version Usage Examples
----------------------

[](#version-usage-examples)

### Creating API instances for different versions

[](#creating-api-instances-for-different-versions)

```
use Stoufa\GarminApi\GarminApi;

$config = [
    'identifier' => getenv('GARMIN_KEY'),
    'secret' => getenv('GARMIN_SECRET'),
    'callback_uri' => getenv('GARMIN_CALLBACK_URI')
];

// International version (default)
$internationalApi = new GarminApi($config, GarminApi::VERSION_INTERNATIONAL);

// Chinese version
$chineseApi = new GarminApi($config, GarminApi::VERSION_CHINESE);
```

### Dynamic version switching

[](#dynamic-version-switching)

```
$api = new GarminApi($config);

// Switch to Chinese version
$api->useChineseVersion();

// Switch to International version
$api->useInternationalVersion();

// Get current configuration
echo "Current version: " . $api->getVersion();
echo "API URL: " . $api->getApiUrl();
echo "User API URL: " . $api->getUserApiUrl();
echo "Auth URL: " . $api->getAuthUrl();
```

### Version-specific endpoints

[](#version-specific-endpoints)

- **Chinese Version**:

    - OAuth API URL: `https://connectapi.garmin.cn/` (for request/access token)
    - Health REST API URL: `https://gcs-wellness.garmin.cn/wellness-api/rest/` (for activities and user data)
    - Auth URL: `http://connect.garmin.cn/oauthConfirm`
    - Tools URL: `https://healthtools.garmin.cn/tools/login` (Data Viewer / Backfill / Ping)
- **International Version**:

    - API URL: `https://connectapi.garmin.com/`
    - User API URL: `https://healthapi.garmin.com/wellness-api/rest/`
    - Auth URL: `http://connect.garmin.com/oauthConfirm`

### Backward Compatibility

[](#backward-compatibility)

Existing code will continue to work without any changes, as the international version is used by default.

HTTP Client Configuration
=========================

[](#http-client-configuration)

This library supports custom HTTP client configuration to handle various network scenarios, including proxy settings, timeouts, SSL verification, and custom headers.

Configuration Options
---------------------

[](#configuration-options)

You can configure the HTTP client using any of the following Guzzle HTTP client options:

- `timeout` - Request timeout in seconds (default: 30)
- `connect_timeout` - Connection timeout in seconds (default: 10)
- `proxy` - Proxy server configuration
- `verify` - SSL certificate verification (default: true)
- `headers` - Default headers to apply to all requests
- `allow_redirects` - Controls redirect behavior
- `cookies` - Cookie jar configuration
- `debug` - Enable debug output

Usage Examples
--------------

[](#usage-examples)

### 1. Configure via constructor

[](#1-configure-via-constructor)

```
use Stoufa\GarminApi\GarminApi;

$config = [
    'identifier' => getenv('GARMIN_KEY'),
    'secret' => getenv('GARMIN_SECRET'),
    'callback_uri' => getenv('GARMIN_CALLBACK_URI')
];

$httpConfig = [
    'timeout' => 60,
    'connect_timeout' => 15,
    'proxy' => 'http://proxy.example.com:8080',
    'verify' => false,
    'headers' => [
        'User-Agent' => 'My Custom App/1.0'
    ]
];

$server = new GarminApi($config, GarminApi::VERSION_INTERNATIONAL, $httpConfig);
```

### 2. Configure using setter method

[](#2-configure-using-setter-method)

```
$server = new GarminApi($config);
$server->setHttpClientConfig([
    'timeout' => 45,
    'proxy' => 'http://proxy.example.com:8080',
    'headers' => [
        'User-Agent' => 'My Custom App/1.0'
    ]
]);
```

### 3. Get current configuration

[](#3-get-current-configuration)

```
$currentConfig = $server->getHttpClientConfig();
print_r($currentConfig);
```

### 4. Common use cases

[](#4-common-use-cases)

#### Set custom timeout for slow networks

[](#set-custom-timeout-for-slow-networks)

```
$server->setHttpClientConfig([
    'timeout' => 120,
    'connect_timeout' => 30
]);
```

#### Configure proxy server

[](#configure-proxy-server)

```
$server->setHttpClientConfig([
    'proxy' => 'http://username:password@proxy.example.com:8080'
]);
```

#### Disable SSL verification (for development)

[](#disable-ssl-verification-for-development)

```
$server->setHttpClientConfig([
    'verify' => false
]);
```

#### Set custom User-Agent

[](#set-custom-user-agent)

```
$server->setHttpClientConfig([
    'headers' => [
        'User-Agent' => 'MyApp/1.0 (contact@example.com)'
    ]
]);
```

#### Enable debug mode

[](#enable-debug-mode)

```
$server->setHttpClientConfig([
    'debug' => true
]);
```

All HTTP requests made by the library (OAuth authentication, API calls, etc.) will use the custom configuration.

Installtion
===========

[](#installtion)

```
composer require jinchun/php-garmin-connect-api

```

Example
=======

[](#example)

Please take a look at [examples](./examples/README.md) folder for complete usage examples, including [version switching examples](./examples/version_switching_example.php).

Usage
=====

[](#usage)

Get authorization link
----------------------

[](#get-authorization-link)

```
use Stoufa\GarminApi\GarminApi;

try
{

    $config = array(
        'identifier'     => getenv('GARMIN_KEY'),
        'secret'         => getenv('GARMIN_SECRET'),
        'callback_uri'   => getenv('GARMIN_CALLBACK_URI')
    );

    $server = new GarminApi($config);

    // Retreive temporary credentials from server
    $temporaryCredentials = $server->getTemporaryCredentials();

    // Save temporary crendentials in session to use later to retreive authorization token
    $_SESSION['temporaryCredentials'] = $temporaryCredentials;

    // Get authorization link
    $link = $server->getAuthorizationUrl($temporaryCredentials);
}
catch (\Throwable $th)
{
    // catch your exception here
}
```

Get token credentials
---------------------

[](#get-token-credentials)

After the user connects his garmin account successfully it will redirect to callback\_uri. "oauth\_token" and "oauth\_verifier" should be available in $\_GET.

```
try
{
    $config = array(
        'identifier'     => getenv('GARMIN_KEY'),
        'secret'         => getenv('GARMIN_SECRET'),
        'callback_uri'   => getenv('GARMIN_CALLBACK_URI')
    );

    $server = new GarminApi($config);

    // Retrieve the temporary credentials we saved before
    $temporaryCredentials = $_SESSION['temporaryCredentials'];

    // We will now retrieve token credentials from the server.
    $tokenCredentials = $server->getTokenCredentials($temporaryCredentials, $_GET['oauth_token'], $_GET['oauth_verifier']);

}
catch (\Throwable $th)
{
    // catch your exception here
}
```

Get Garmin user id
------------------

[](#get-garmin-user-id)

```
$userId = $server->getUserUid($tokenCredentials);
```

Backfill activities
-------------------

[](#backfill-activities)

When you connect garmin account and get token credentials first time, you won't be able to get previous activities because garmin does not give you activities older than your token credentials. Instead you need to use backfill method to fullfull your token with previous activities (no more than one month).

```
// backfill activities for last 7 days ago
$params = [
    'summaryStartTimeInSeconds' => strtotime("-7 days", time()),
    'summaryEndTimeInSeconds' => time()
];
$server->backfillActivitySummary($tokenCredentials, $params);
```

Deregistration
--------------

[](#deregistration)

```
$server->deleteUserAccessToken($tokenCredentials);
```

Avalaible methods (for the moment)
----------------------------------

[](#avalaible-methods-for-the-moment)

### Get summary activities

[](#get-summary-activities)

```
$params = [
    'uploadStartTimeInSeconds' => 1598814036, // time in seconds utc
    'uploadEndTimeInSeconds' => 1598900435 // time in seconds utc
];

// Activity summaries
$server->getActivitySummary($tokenCredentials, $params);

// Manually activity summaries
$server->getManuallyActivitySummary($tokenCredentials, $params);

// Activity details summaries
$server->getActivityDetailsSummary($tokenCredentials, $params);

// User metrics (including VO2 max and fitness age)
$server->getUserMetrics($tokenCredentials, $params);
```

### Backfill activities

[](#backfill-activities-1)

```
// For backfill params can be with upload start time
$params = [
    'uploadStartTimeInSeconds' => 1598814036, // time in seconds utc
    'uploadEndTimeInSeconds' => 1598900435 // time in seconds utc
];
// or with summary start time
$params = [
    'summaryStartTimeInSeconds' => 1598814036, // time in seconds utc
    'summaryEndTimeInSeconds' => 1598900435 // time in seconds utc
];

// Backfill activity summaries
$server->backfillActivitySummary($tokenCredentials, $params);

// Backfill daily activity summaries
$server->backfillDailySummary($tokenCredentials, $params);

// Backfill epoch summaries
$server->backfillEpochSummary($tokenCredentials, $params);

// Backfill activity details summaries
$server->backfillActivityDetailsSummary($tokenCredentials, $params);

// Backfill sleep summaries
$server->backfillSleepSummary($tokenCredentials, $params);

// Backfill body composition summaries
$server->backfillBodyCompositionSummary($tokenCredentials, $params);

// Backfill stress details summaries
$server->backfillStressDetailsSummary($tokenCredentials, $params);

// Backfill user metrics summaries
$server->backfillUserMetricsSummary($tokenCredentials, $params);

// Backfill pulse ox summaries
$server->backfillPulseOxSummary($tokenCredentials, $params);

// Backfill respiration summaries
$server->backfillRespirationSummary($tokenCredentials, $params);
```

### Get User Metrics (VO2 Max)

[](#get-user-metrics-vo2-max)

The `getUserMetrics` method retrieves user fitness metrics including VO2 max and fitness age. This method requires both `uploadStartTimeInSeconds` and `uploadEndTimeInSeconds` parameters with a maximum 24-hour window.

```
// Get user metrics for a specific 24-hour period
$params = [
    'uploadStartTimeInSeconds' => 1726876800, // Unix timestamp
    'uploadEndTimeInSeconds' => 1726963200    // Unix timestamp (max 24 hours later)
];

$userMetrics = $server->getUserMetrics($tokenCredentials, $params);

// The response will include VO2 max data and other fitness metrics
// Example response structure:
// {
//   "userMetrics": [
//     {
//       "vo2Max": 45.2,
//       "fitnessAge": 28,
//       "timestamp": "2023-09-21T12:00:00Z"
//     }
//   ]
// }
```

**Important**: The time window for user metrics queries cannot exceed 24 hours.

###  Health Score

18

—

LowBetter than 8% of packages

Maintenance46

Moderate activity, may be stable

Popularity4

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity13

Early-stage or recently created project

 Bus Factor1

Top contributor holds 81.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/3a6f54cdd8ed605f25e9354e157c2486ff2af22f1c1cc97065c927ec2b3cd364?d=identicon)[jinchun](/maintainers/jinchun)

---

Top Contributors

[![stoufa06](https://avatars.githubusercontent.com/u/3877384?v=4)](https://github.com/stoufa06 "stoufa06 (36 commits)")[![jinchun](https://avatars.githubusercontent.com/u/2932388?v=4)](https://github.com/jinchun "jinchun (7 commits)")[![COil](https://avatars.githubusercontent.com/u/177844?v=4)](https://github.com/COil "COil (1 commits)")

### Embed Badge

![Health badge](/badges/jinchun-php-garmin-connect-api/health.svg)

```
[![Health](https://phpackages.com/badges/jinchun-php-garmin-connect-api/health.svg)](https://phpackages.com/packages/jinchun-php-garmin-connect-api)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)