garmin-connect-personal-api-python 1.0.0__py3-none-any.whl

garmin_personal_api/client.py

@@ -0,0 +1,288 @@
+"""Endpoint wrappers for the Garmin Personal API."""
+
+# Copyright 2026 Garmin Ltd. or its subsidiaries.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Mapping
+from datetime import date
+from typing import Any
+from urllib.parse import urlencode
+
+import requests
+
+from .constants import BASE_URL_ENV_VAR, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_SECONDS
+from .errors import GarminPersonalApiError, HttpError
+
+JsonValue = dict[str, Any] | list[Any] | str | int | float | bool | None
+QueryParams = Mapping[str, str | int | float | bool]
+_LOGGER = logging.getLogger(__name__)
+
+
+class GarminPersonalApiClient:
+    """Read Garmin data using an already-issued bearer token."""
+
+    def __init__(
+        self,
+        bearer_token: str,
+        *,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        session: requests.Session | None = None,
+    ) -> None:
+        if timeout <= 0:
+            raise GarminPersonalApiError("timeout must be greater than zero")
+        self.base_url = os.environ.get(BASE_URL_ENV_VAR, DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self._session = session or requests.Session()
+        self.update_bearer_token(bearer_token)
+
+    def close(self) -> None:
+        """Close the underlying HTTP session."""
+        self._session.close()
+
+    def __enter__(self) -> GarminPersonalApiClient:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(base_url={self.base_url!r}, timeout={self.timeout!r})"
+
+    def update_bearer_token(self, bearer_token: str) -> None:
+        """Replace the token used for subsequent requests."""
+        self._headers = {
+            "Accept": "application/json",
+            "Authorization": f"Bearer {bearer_token}",
+        }
+
+    def get_daily_stress(self, start_date: str | date, end_date: str | date) -> JsonValue:
+        """Return daily stress statistics for an inclusive calendar date range."""
+        return self.get(
+            f"/usersummary-service/stats/stress/daily/{_iso(start_date)}/{_iso(end_date)}"
+        )
+
+    def get_daily_steps(self, start_date: str | date, end_date: str | date) -> JsonValue:
+        """Return daily step statistics for an inclusive calendar date range."""
+        return self.get(
+            f"/usersummary-service/stats/steps/daily/{_iso(start_date)}/{_iso(end_date)}"
+        )
+
+    def get_daily_hydration(self, start_date: str | date, end_date: str | date) -> JsonValue:
+        """Return daily hydration statistics for an inclusive calendar date range."""
+        return self.get(
+            f"/usersummary-service/stats/hydration/daily/{_iso(start_date)}/{_iso(end_date)}"
+        )
+
+    def get_effective_weight_goals(
+        self,
+        start_date: str | date,
+        end_date: str | date,
+    ) -> JsonValue:
+        """Return effective weight goals for an inclusive calendar date range."""
+        return self.get(
+            f"/goal-service/goal/user/effective/weightgoal/{_iso(start_date)}/{_iso(end_date)}"
+        )
+
+    def get_weight_measurements(self, start_date: str | date, end_date: str | date) -> JsonValue:
+        """Return all weight data for an inclusive calendar date range."""
+        return self.get(
+            f"/weight-service/weight/range/{_iso(start_date)}/{_iso(end_date)}",
+            params={"includeAll": "true"},
+        )
+
+    def get_daily_food_logs(self, calendar_date: str | date) -> JsonValue:
+        """Return nutrition food logs for a calendar date."""
+        return self.get(f"/nutrition-service/food/logs/{_iso(calendar_date)}")
+
+    def get_user_profile_settings(self) -> JsonValue:
+        """Return the current user's profile settings."""
+        return self.get("/userprofile-service/userprofile/settings")
+
+    def get_daily_sleep(self, calendar_date: str | date) -> JsonValue:
+        """Return daily sleep data for a calendar date."""
+        return self.get(
+            "/sleep-service/sleep/dailySleep",
+            params={"date": _iso(calendar_date)},
+        )
+
+    def get_daily_sleep_summaries(
+        self,
+        start_date: str | date,
+        end_date: str | date,
+    ) -> JsonValue:
+        """Return daily sleep summaries for an inclusive calendar date range."""
+        return self.get(
+            "/sleep-service/sleep/dailySleepSummariesByDate",
+            params={"startDate": _iso(start_date), "endDate": _iso(end_date)},
+        )
+
+    def get_daily_body_battery(
+        self,
+        start_date: str | date,
+        end_date: str | date,
+        *,
+        chunks: int | None = None,
+    ) -> JsonValue:
+        """Return daily Body Battery data for an inclusive calendar date range."""
+        params: dict[str, str | int] = {"startDate": _iso(start_date), "endDate": _iso(end_date)}
+        if chunks is not None:
+            params["chunks"] = chunks
+        return self.get("/wellness-service/wellness/bodyBattery/reports/daily", params=params)
+
+    def get_daily_summaries(
+        self,
+        start_date: str | date,
+        end_date: str | date,
+    ) -> JsonValue:
+        """Return user daily summaries for an inclusive calendar date range.
+
+        Use the same start and end date for a single day. The response preserves
+        the endpoint's object containing a data array, even for one day.
+        """
+        return self.get(
+            "/usersummary-service/v2/dailysummaries",
+            params={"startDate": _iso(start_date), "endDate": _iso(end_date)},
+        )
+
+    def get_daily_hrv(self, calendar_date: str | date) -> JsonValue:
+        """Return heart rate variability (HRV) summary and readings for a calendar date."""
+        return self.get(f"/hrv-service/hrv/{_iso(calendar_date)}")
+
+    def get_daily_hrv_summaries(self, start_date: str | date, end_date: str | date) -> JsonValue:
+        """Return daily heart rate variability (HRV) summaries for an inclusive date range."""
+        return self.get(f"/hrv-service/hrv/daily/{_iso(start_date)}/{_iso(end_date)}")
+
+    def get_heart_rate_zones(self) -> JsonValue:
+        """Return the current user's heart rate zones."""
+        return self.get("/biometric-service/heartRateZones/v2")
+
+    def get_fitness_age(self, calendar_date: str | date) -> JsonValue:
+        """Return fitness age data for a calendar date."""
+        return self.get(f"/fitnessage-service/fitnessage/v2/{_iso(calendar_date)}")
+
+    def get_daily_heart_rate(self, calendar_date: str | date) -> JsonValue:
+        """Return daily heart rate data for a calendar date."""
+        return self.get(
+            "/wellness-service/wellness/dailyHeartRate",
+            params={"date": _iso(calendar_date)},
+        )
+
+    def get_menstrual_cycle_summary(self, calendar_date: str | date) -> JsonValue:
+        """Return menstrual-cycle summary data for a calendar date."""
+        return self.get(f"/periodichealth-service/menstrualcycle/summary/{_iso(calendar_date)}")
+
+    def get_menstrual_cycle_day_view(
+        self,
+        calendar_date: str | date,
+        today_date: str | date,
+    ) -> JsonValue:
+        """Return the menstrual-cycle day view for a calendar date."""
+        return self.get(
+            f"/periodichealth-service/menstrualcycle/dayview/{_iso(calendar_date)}",
+            params={"todayDate": _iso(today_date)},
+        )
+
+    def get_daily_spo2(self, calendar_date: str | date) -> JsonValue:
+        """Return daily SpO2 and acclimation data for a calendar date."""
+        return self.get(f"/wellness-service/wellness/daily/spo2acclimation/{_iso(calendar_date)}")
+
+    def get_wellness_activity_summaries(
+        self,
+        start_date: str | date,
+        end_date: str | date,
+    ) -> JsonValue:
+        """Return wellness activity summaries for an inclusive calendar date range."""
+        return self.get(
+            f"/wellnessactivity-service/activity/summary/range/{_iso(start_date)}/{_iso(end_date)}"
+        )
+
+    def search_activities(
+        self,
+        *,
+        start: int = 0,
+        limit: int = 20,
+        start_date: str | date | None = None,
+        end_date: str | date | None = None,
+        activity_type: str | None = None,
+    ) -> JsonValue:
+        """Return summarized activities matching the supplied search filters."""
+        params: dict[str, str | int] = {"start": start, "limit": limit}
+        if start_date is not None:
+            params["startDate"] = _iso(start_date)
+        if end_date is not None:
+            params["endDate"] = _iso(end_date)
+        if activity_type is not None:
+            params["activityType"] = activity_type
+        return self.get("/activitylist-service/activities/search/activities", params=params)
+
+    def get_activity(self, activity_id: int | str) -> JsonValue:
+        """Return the activity summary/details for an activity ID."""
+        return self.get(f"/activity-service/activity/{activity_id}")
+
+    def get_activity_workouts(self, activity_id: int | str) -> JsonValue:
+        """Return workouts associated with an activity ID."""
+        return self.get(f"/activity-service/activity/{activity_id}/workouts")
+
+    def download_activity(self, activity_id: int | str) -> bytes:
+        """Return the original activity file as ZIP bytes, without extracting it."""
+        activity_id = str(activity_id)
+        if not activity_id.isascii() or not activity_id.isdecimal() or int(activity_id) <= 0:
+            raise GarminPersonalApiError("activity_id must be a positive integer")
+        response = self._get_response(
+            f"/download-service/files/activity/{activity_id}",
+            accept="application/zip, application/x-zip-compressed, application/octet-stream",
+        )
+        if not response.content:
+            raise GarminPersonalApiError("The original activity file response was empty")
+        return response.content
+
+    def get(self, path: str, *, params: QueryParams | None = None) -> JsonValue:
+        """GET a Personal API path and return decoded JSON, or ``None`` if empty."""
+        response = self._get_response(path, params=params)
+        if not response.content:
+            return None
+        return response.json()
+
+    def _get_response(
+        self,
+        path: str,
+        *,
+        params: QueryParams | None = None,
+        accept: str = "application/json",
+    ) -> requests.Response:
+        url = f"{self.base_url}{path}"
+        _LOGGER.info("GET %s", f"{path}?{urlencode(params)}" if params else path)
+        response = self._session.get(
+            url,
+            headers={**self._headers, "Accept": accept},
+            params=params,
+            timeout=self.timeout,
+        )
+        if not response.ok:
+            raise HttpError(
+                status_code=response.status_code,
+                method="GET",
+                url=url,
+                response_text=response.text,
+            )
+        return response
+
+
+def _iso(value: str | date) -> str:
+    """Format a date as YYYY-MM-DD; strings are passed through to the API unchanged."""
+    return value.isoformat() if isinstance(value, date) else value

garmin_personal_api/commands.py

@@ -0,0 +1,119 @@
+"""The command list shared by the CLI and interactive menu."""
+
+# Copyright 2026 Garmin Ltd. or its subsidiaries.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Literal
+
+from .client import GarminPersonalApiClient as Client
+from .client import JsonValue
+
+InputKind = Literal["date", "date_range", "date_with_today", "none", "activities", "activity"]
+# Shared by the CLI subcommand and the interactive menu action; not a data command.
+TOKEN_REFRESH_COMMAND = "refresh-token"
+
+
+@dataclass(frozen=True)
+class CommandSpec:
+    """Describe how the CLI and interactive menu invoke one client method."""
+
+    command: str
+    label: str
+    method: Callable[..., JsonValue | bytes]
+    input_kind: InputKind
+    output_kind: Literal["json", "download"] = "json"
+    description: str | None = None
+
+
+COMMANDS = (
+    CommandSpec("activities", "Activities", Client.search_activities, "activities"),
+    CommandSpec("stress", "Daily Stress", Client.get_daily_stress, "date_range"),
+    CommandSpec("steps", "Daily Steps", Client.get_daily_steps, "date_range"),
+    CommandSpec("hydration", "Daily Hydration", Client.get_daily_hydration, "date_range"),
+    CommandSpec(
+        "effective-weight-goals",
+        "Effective Weight Goals",
+        Client.get_effective_weight_goals,
+        "date_range",
+    ),
+    CommandSpec(
+        "weight-measurements", "Weight Measurements", Client.get_weight_measurements, "date_range"
+    ),
+    CommandSpec("food-logs", "Food Logs", Client.get_daily_food_logs, "date"),
+    CommandSpec(
+        "profile-settings", "User Profile Settings", Client.get_user_profile_settings, "none"
+    ),
+    CommandSpec("sleep", "Daily Sleep", Client.get_daily_sleep, "date"),
+    CommandSpec(
+        "sleep-summaries", "Daily Sleep Summaries", Client.get_daily_sleep_summaries, "date_range"
+    ),
+    CommandSpec("body-battery", "Daily Body Battery", Client.get_daily_body_battery, "date_range"),
+    CommandSpec(
+        "daily-summaries",
+        "User Daily Summaries",
+        Client.get_daily_summaries,
+        "date_range",
+    ),
+    CommandSpec("heart-rate", "Daily Heart Rate", Client.get_daily_heart_rate, "date"),
+    CommandSpec(
+        "hrv",
+        "Daily HRV",
+        Client.get_daily_hrv,
+        "date",
+        description="Get heart rate variability (HRV) summary and readings for a calendar date.",
+    ),
+    CommandSpec(
+        "hrv-summaries",
+        "Daily HRV Summaries",
+        Client.get_daily_hrv_summaries,
+        "date_range",
+        description="Get daily heart rate variability (HRV) summaries for an inclusive date range.",
+    ),
+    CommandSpec("heart-rate-zones", "Heart Rate Zones", Client.get_heart_rate_zones, "none"),
+    CommandSpec(
+        "menstrual-cycle-summary",
+        "Menstrual Cycle Summary",
+        Client.get_menstrual_cycle_summary,
+        "date",
+    ),
+    CommandSpec(
+        "menstrual-cycle-day-view",
+        "Menstrual Cycle Day View",
+        Client.get_menstrual_cycle_day_view,
+        "date_with_today",
+    ),
+    CommandSpec("fitness-age", "Fitness Age", Client.get_fitness_age, "date"),
+    CommandSpec("spo2", "Daily SpO2", Client.get_daily_spo2, "date"),
+    CommandSpec(
+        "wellness-activity-summaries",
+        "Wellness Activity Summaries",
+        Client.get_wellness_activity_summaries,
+        "date_range",
+    ),
+    CommandSpec("activity", "Activity Details", Client.get_activity, "activity"),
+    CommandSpec("activity-workouts", "Activity Workouts", Client.get_activity_workouts, "activity"),
+    CommandSpec(
+        "activity-download",
+        "Download original activity file",
+        Client.download_activity,
+        "activity",
+        "download",
+    ),
+)
+
+COMMANDS_BY_NAME = {spec.command: spec for spec in COMMANDS}

garmin_personal_api/constants.py

@@ -0,0 +1,25 @@
+"""Public defaults for Garmin Personal API access."""
+
+# Copyright 2026 Garmin Ltd. or its subsidiaries.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from pathlib import Path
+
+DEFAULT_BASE_URL = "https://personal.connectapi.garmin.com"
+DEFAULT_API_KEY_FILE = Path("~/.config/garmin/connect-personal-api-key")
+DEFAULT_BEARER_TOKEN_CACHE_FILE = Path("~/.config/garmin/connect-personal-api-bearer-token.json")
+DEFAULT_API_KEY_ENV_VAR = "GARMIN_PERSONAL_API_KEY"
+BASE_URL_ENV_VAR = "GARMIN_PERSONAL_API_BASE_URL"
+DEFAULT_TIMEOUT_SECONDS = 30.0
+TOKEN_PATH = "/personalapitoken-service/personal-api/personal-api-key/token"

garmin_personal_api/downloads.py

@@ -0,0 +1,48 @@
+"""File output shared by direct and interactive downloads."""
+
+# Copyright 2026 Garmin Ltd. or its subsidiaries.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+import tempfile
+from pathlib import Path
+
+from .errors import GarminPersonalApiError
+
+
+def save_download(content: bytes, destination: Path, *, overwrite: bool = False) -> Path:
+    """Publish a complete file, without replacing an existing file unless requested."""
+    destination = destination.expanduser()
+    temporary: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            dir=destination.parent, prefix=f".{destination.name}.", delete=False
+        ) as output:
+            temporary = Path(output.name)
+            output.write(content)
+        if overwrite:
+            temporary.replace(destination)
+        else:
+            # Linking publishes atomically and refuses even a dangling destination symlink.
+            os.link(temporary, destination)
+    except FileExistsError as exc:
+        raise GarminPersonalApiError(
+            f"File already exists: {destination}. Choose another path or allow overwrite."
+        ) from exc
+    except OSError as exc:
+        raise GarminPersonalApiError(f"Cannot save {destination}: {exc}") from exc
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+    return destination

garmin_personal_api/errors.py

@@ -0,0 +1,42 @@
+"""Exceptions raised by the Garmin Personal API client."""
+
+# Copyright 2026 Garmin Ltd. or its subsidiaries.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+
+class GarminPersonalApiError(Exception):
+    """Base class for all package-specific errors."""
+
+
+class HttpError(GarminPersonalApiError):
+    """Raised when the Garmin API returns an unsuccessful HTTP response."""
+
+    def __init__(
+        self,
+        *,
+        status_code: int,
+        method: str,
+        url: str,
+        response_text: str,
+    ) -> None:
+        self.status_code = status_code
+        self.method = method
+        self.url = url
+        self.response_text = response_text
+        message = f"{method} {url} returned HTTP {status_code}"
+        if response_text.strip():
+            message = f"{message}: {response_text.strip()}"
+        super().__init__(message)