Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,12 @@ Numbers in parentheses refer to GitHub issues and pull requests. Releases before
0.3.10 are described on the [GitHub Releases](https://github.com/cyberjunky/python-garminconnect/releases)
page.

## [Unreleased]

### Added

- **The primary wearable can be set**: new `set_primary_activity_tracker(device_id)` chooses the device Garmin uses for daily health metrics such as steps, stress and sleep (the web app's "Primary Wearable"), next to the existing `set_primary_training_device()`. It sends the request the web app's Device Priority page sends, a `PUT` to `device-service/deviceservice/device-info/{id}/primary-activity-tracker`; the device ID is in the URL and no body is needed. Tested live by switching the primary wearable from one device to another and back: Garmin answers 204, `get_primary_training_device()` shows the new device with `primaryWearableDevice: true`, and the primary training device stays unchanged. The two roles are independent: `set_primary_training_device()` alone leaves the primary wearable where it was. (#483)

## [0.3.20] - 2026-10-23

### Added
Expand Down
15 changes: 8 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
The Garmin Connect API library comes with two examples:

- **`example.py`** - Simple getting-started example showing authentication, token storage, and basic API calls
- **`demo.py`** - Comprehensive demo providing access to **270 API methods** organized into **15 categories** for easy navigation
- **`demo.py`** - Comprehensive demo providing access to **271 API methods** organized into **15 categories** for easy navigation

```bash
$ ./demo.py
Expand Down Expand Up @@ -51,7 +51,7 @@ Make your selection:

## API Coverage Statistics

- **Total API Methods**: 348 methods; every method with a one-line description is listed in the [Method Reference](#-method-reference)
- **Total API Methods**: 349 methods; every method with a one-line description is listed in the [Method Reference](#-method-reference)
- **Categories**: 15 organized sections
- **Web-app endpoint map**: the endpoints the Garmin Connect web app uses documented with the exact request it sends and whether it was verified live, in [docs/API_ENDPOINTS.md](docs/API_ENDPOINTS.md); the dashboard's GraphQL operations are in [docs/graphql_operations.md](docs/graphql_operations.md)
- **User & Profile**: 8 methods (basic user info, settings)
Expand All @@ -61,7 +61,7 @@ Make your selection:
- **Activities & Workouts**: 37 methods (comprehensive activity, workout management, typed workout uploads including strength and swim CSS targets, in-place edit, scheduling, push to device, import, activity type/subtype filtering, earliest-upcoming-workout lookup, activity photos)
- **Body Composition & Weight**: 11 methods (weight tracking, body composition)
- **Goals & Achievements**: 24 methods (challenges, badges, goals)
- **Device & Technical**: 13 methods (device info, settings)
- **Device & Technical**: 14 methods (device info, settings)
- **Gear & Equipment**: 13 methods (gear management, tracking, creation)
- **Hydration & Wellness**: 30 methods (hydration, nutrition, blood pressure, menstrual reads and writes, Jet Lag Adviser trips)
- **System & Export**: 5 methods (reporting, logout, GraphQL, health snapshot download)
Expand Down Expand Up @@ -131,15 +131,15 @@ source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -e ".[example]"

python3 ./example.py # simple getting-started example
python3 ./demo.py # comprehensive demo (270 API methods)
python3 ./demo.py # comprehensive demo (271 API methods)
```

## 📚 Method Reference

<!-- METHODS:START -->
348 public methods on `Garmin`, generated from the code by `scripts/gen_method_reference.py`. Click a section to expand it.
349 public methods on `Garmin`, generated from the code by `scripts/gen_method_reference.py`. Click a section to expand it.

<details><summary><b>Login, profile & account</b> (21)</summary>
<details><summary><b>Login, profile & account</b> (22)</summary>

| Method | Description |
| --- | --- |
Expand All @@ -161,6 +161,7 @@ python3 ./demo.py # comprehensive demo (270 API methods)
| `query_garmin_graphql(query)` | Run a query against Garmin's GraphQL gateway. |
| `request_reload(cdate, device_id=None)` | Request reload of data for a specific date. |
| `resume_login(client_state, mfa_code)` | Finish a login that is waiting for an MFA code. |
| `set_primary_activity_tracker(device_id)` | Choose which device Garmin treats as the primary wearable. |
| `set_primary_training_device(device_id)` | Choose which device Garmin treats as the primary training device. |
| `today()` | Return today's calendar date in the user's Garmin timezone. |
| `update_user_settings(settings)` | Write user settings (units, formats, sleep times, training days, ...). |
Expand Down Expand Up @@ -1042,7 +1043,7 @@ activity has photos attached.

### Additional Resources
- **Simple Example**: [example.py](https://raw.githubusercontent.com/cyberjunky/python-garminconnect/master/example.py) - Getting started guide
- **Comprehensive Demo**: [demo.py](https://raw.githubusercontent.com/cyberjunky/python-garminconnect/master/demo.py) - All 270 API methods
- **Comprehensive Demo**: [demo.py](https://raw.githubusercontent.com/cyberjunky/python-garminconnect/master/demo.py) - All 271 API methods
- **API Documentation**: Comprehensive method documentation in source code
- **Test Cases**: Real-world usage examples in `tests/` directory

Expand Down
27 changes: 27 additions & 0 deletions demo.py
Original file line number Diff line number Diff line change
Expand Up @@ -735,6 +735,10 @@ def month_start(self) -> datetime.date:
"desc": "Set primary training device (interactive)",
"key": "set_primary_training_device",
},
"d": {
"desc": "Set primary wearable (interactive)",
"key": "set_primary_activity_tracker",
},
},
},
"9": {
Expand Down Expand Up @@ -5339,6 +5343,26 @@ def set_primary_training_device_data(api: Garmin) -> None:
print(f"❌ Error setting primary training device: {e}")


def set_primary_activity_tracker_data(api: Garmin) -> None:
"""Choose the primary wearable (source of steps, stress and sleep)."""
try:
device = _pick(
api.get_devices(),
"device",
lambda d: f"{d.get('productDisplayName')} (id {d.get('deviceId')})",
)
if not device:
return
call_and_display(
api.set_primary_activity_tracker,
device["deviceId"],
method_name="set_primary_activity_tracker",
api_call_desc=f"api.set_primary_activity_tracker({device['deviceId']})",
)
except Exception as e:
print(f"❌ Error setting primary wearable: {e}")


def update_activity_name_data(api: Garmin) -> None:
"""Rename the latest activity through the generic update call."""
try:
Expand Down Expand Up @@ -6010,6 +6034,9 @@ def execute_api_call(api: Garmin, key: str) -> None:
"set_primary_training_device": lambda: set_primary_training_device_data(
api
),
"set_primary_activity_tracker": lambda: set_primary_activity_tracker_data(
api
),
"update_activity": lambda: update_activity_name_data(api),
# Endpoints the Garmin Connect web app uses, see docs/API_ENDPOINTS.md
"get_max_metrics_latest": _web(api, "get_max_metrics_latest"),
Expand Down
1 change: 1 addition & 0 deletions docs/API_ENDPOINTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -188,6 +188,7 @@ feature get a 404.
| `get_usage_indicators()` | `GET /web-gateway/snapshot/usageIndicators` | Which features the account's devices support. | yes |
| `update_user_settings(settings)` | `PUT /userprofile-service/userprofile/user-settings/` with the settings object | Overlaid on `get_user_profile()`; `userData` merged one level deep. | yes (unchanged object) |
| `set_primary_training_device(device_id)` | `PUT /userprofile-service/userprofile/user-settings/primary-training-device` `{"deviceId"}` | | yes |
| `set_primary_activity_tracker(device_id)` | `PUT /device-service/deviceservice/device-info/{deviceId}/primary-activity-tracker` (no body needed) | The web app's "Primary Wearable": source of steps, stress and sleep. Independent of the primary training device. Read back with `get_primary_training_device()` (`primaryWearableDevice`). | yes |
| `get_jetlag_status(cdate=None)` | `GET /jetlag-service/jetlag/status/daily/{date}` | Empty without a trip. | yes (empty) |

## Activities (`activitylist-service`, `activity-service`, `segment-service`)
Expand Down
23 changes: 23 additions & 0 deletions garminconnect/api/base.py
Original file line number Diff line number Diff line change
Expand Up @@ -849,6 +849,29 @@ def set_primary_training_device(self, device_id: int | str) -> Any:
self.client.put("connectapi", url, json={"deviceId": device_id})
)

def set_primary_activity_tracker(self, device_id: int | str) -> Any:
"""Choose which device Garmin treats as the primary wearable.

The primary wearable (the web app's "Primary Wearable", called primary
activity tracker in the API) is the source of daily health metrics such
as steps, stress and sleep. PUT
/device-service/deviceservice/device-info/{id}/primary-activity-tracker,
the request the web app's Device Priority page sends; the device ID is
part of the URL and no body is needed. Garmin answers 204, so the
method returns ``None``.
``get_primary_training_device()`` shows the result: the chosen device
carries ``primaryWearableDevice: true`` under ``WearableDevices``. The
primary training device is a separate setting and stays unchanged.
Verified live by switching between two devices and reading back.
"""
device_id = _coerce_positive_id(device_id, "device_id")
url = (
f"{self.garmin_connect_device_url}/device-info/{device_id}"
"/primary-activity-tracker"
)
logger.debug("Setting primary activity tracker %s", device_id)
return self._json_or_none(self.client.put("connectapi", url))

def request_reload(
self, cdate: str, device_id: int | str | None = None
) -> dict[str, Any]:
Expand Down
13 changes: 13 additions & 0 deletions tests/test_web_endpoints.py
Original file line number Diff line number Diff line change
Expand Up @@ -404,6 +404,19 @@ def test_user_settings_merge_and_primary_device(writer, monkeypatch):
assert calls[-1][2]["json"] == {"deviceId": 123}


def test_primary_activity_tracker(writer):
g, calls = writer
g.set_primary_activity_tracker("123")
assert calls[-1][:2] == (
"PUT",
"/device-service/deviceservice/device-info/123/primary-activity-tracker",
)
assert calls[-1][2] == {} # no body of any kind
for bad in (0, -1, "abc", 1.9, None):
with pytest.raises(ValueError):
g.set_primary_activity_tracker(bad)


def test_calendar_notes(writer):
g, calls = writer
g.create_calendar_note("2026-10-20", "Race day", "Easy jog in the morning")
Expand Down