# Garth
[](https://github.com/matin/garth/actions/workflows/ci.yml?query=event%3Apush+branch%3Amain+workflow%3ACI)
[](https://codecov.io/gh/matin/garth)
[](https://www.pepy.tech/projects/garth)
Garmin SSO auth + Connect Python client
## Google Colabs
### [Stress: 28-day rolling average](https://colab.research.google.com/github/matin/garth/blob/main/colabs/stress.ipynb)
Stress levels from one day to another can vary by extremes, but there's always
a general trend. Using a scatter plot with a rolling average shows both the
individual days and the trend. The Colab retrieves up to three years of daily
data. If there's less than three years of data, it retrieves whatever is
available.
### [Sleep analysis over 90 days](https://colab.research.google.com/github/matin/garth/blob/main/colabs/sleep.ipynb)
The Garmin Connect app only shows a maximum of seven days for sleep
stages—making it hard to see trends. The Connect API supports retrieving
daily sleep quality in 28-day pages, but that doesn't show details. Using
`SleedData.list()` gives us the ability to retrieve an arbitrary number of
day with enough detail to product a stacked bar graph of the daily sleep
stages.
One specific graph that's useful but not available in the Connect app is
sleep start and end times over an extended period. This provides context
to the sleep hours and stages.
### [ChatGPT analysis of Garmin stats](https://colab.research.google.com/github/matin/garth/blob/main/colabs/chatgpt_analysis_of_stats.ipynb)
ChatGPT's Advanced Data Analysis took can provide incredible insight
into the data in a way that's much simpler than using Pandas and Matplotlib.
Start by using the linked Colab to download a CSV of the last three years
of your stats, and upload the CSV to ChatGPT.
Here's the outputs of the following prompts:
How do I sleep on different days of the week?
<img width="600" alt="image" src="https://github.com/matin/garth/assets/98985/b7507459-2482-43d6-bf55-c3a1f756facb">
On what days do I exercise the most?
<img width="600" alt="image" src="https://github.com/matin/garth/assets/98985/11294be2-8e1a-4fed-a489-13420765aada">
Magic!
## Background
Garth is meant for personal use and follows the philosophy that your data is
your data. You should be able to download it and analyze it in the way that
you'd like. In my case, that means processing with Google Colab, Pandas,
Matplotlib, etc.
There are already a few Garmin Connect libraries. Why write another?
### Authentication and stability
The most important reasoning is to build a library with authentication that
works on [Google Colab](https://colab.research.google.com/) and doesn't require
tools like Cloudscraper. Garth, in comparison:
1. Uses OAuth1 and OAuth2 token authentication after initial login
1. OAuth1 token survives for a year
1. Supports MFA
1. Auto-refresh of OAuth2 token when expired
1. Works on Google Colab
1. Uses Pydantic dataclasses to validate and simplify use of data
1. Full test coverage
### JSON vs HTML
Using `garth.connectapi()` allows you to make requests to the Connect API
and receive JSON vs needing to parse HTML. You can use the same endpoints the
mobile app uses.
This also goes back to authentication. Garth manages the necessary Bearer
Authentication (along with auto-refresh) necessary to make requests routed to
the Connect API.
## Instructions
### Install
```bash
python -m pip install garth
```
### Clone, setup environment and run tests
```bash
gh repo clone matin/garth
cd garth
make install
make
```
Use `make help` to see all the options.
### Authenticate and save session
```python
import garth
from getpass import getpass
email = input("Enter email address: ")
password = getpass("Enter password: ")
# If there's MFA, you'll be prompted during the login
garth.login(email, password)
garth.save("~/.garth")
```
### Custom MFA handler
There's already a default MFA handler that prompts for the code in the
terminal. You can provide your own handler. The handler should return the
MFA code through your custom prompt.
```python
garth.login(email, password, prompt_mfa=lambda: input("Enter MFA code: "))
```
### Configure
#### Set domain for China
```python
garth.configure(domain="garmin.cn")
```
#### Proxy through Charles
```python
garth.configure(proxies={"https": "http://localhost:8888"}, ssl_verify=False)
```
### Attempt to resume session
```python
import garth
from garth.exc import GarthException
garth.resume("~/.garth")
try:
garth.client.username
except GarthException:
# Session is expired. You'll need to log in again
```
## Connect API
### Daily details
```python
sleep = garth.connectapi(
f"/wellness-service/wellness/dailySleepData/{garth.client.username}",
params={"date": "2023-07-05", "nonSleepBufferMinutes": 60},
)
list(sleep.keys())
```
```json
[
"dailySleepDTO",
"sleepMovement",
"remSleepData",
"sleepLevels",
"sleepRestlessMoments",
"restlessMomentsCount",
"wellnessSpO2SleepSummaryDTO",
"wellnessEpochSPO2DataDTOList",
"wellnessEpochRespirationDataDTOList",
"sleepStress"
]
```
### Stats
```python
stress = garth.connectapi("/usersummary-service/stats/stress/weekly/2023-07-05/52")
```
```json
{
"calendarDate": "2023-07-13",
"values": {
"highStressDuration": 2880,
"lowStressDuration": 10140,
"overallStressLevel": 33,
"restStressDuration": 30960,
"mediumStressDuration": 8760
}
}
```
## Upload
```python
with open("12129115726_ACTIVITY.fit", "rb") as f:
uploaded = garth.client.upload(f)
```
Note: Garmin doesn't accept uploads of _structured_ FIT files as outlined in
[this conversation](https://github.com/matin/garth/issues/27). FIT files
generated from workouts are accepted without issues.
```python
{
'detailedImportResult': {
'uploadId': 212157427938,
'uploadUuid': {
'uuid': '6e56051d-1dd4-4f2c-b8ba-00a1a7d82eb3'
},
'owner': 2591602,
'fileSize': 5289,
'processingTime': 36,
'creationDate': '2023-09-29 01:58:19.113 GMT',
'ipAddress': None,
'fileName': '12129115726_ACTIVITY.fit',
'report': None,
'successes': [],
'failures': []
}
}
```
## Stats resources
### Stress
Daily stress levels
```python
DailyStress.list("2023-07-23", 2)
```
```python
[
DailyStress(
calendar_date=datetime.date(2023, 7, 22),
overall_stress_level=31,
rest_stress_duration=31980,
low_stress_duration=23820,
medium_stress_duration=7440,
high_stress_duration=1500
),
DailyStress(
calendar_date=datetime.date(2023, 7, 23),
overall_stress_level=26,
rest_stress_duration=38220,
low_stress_duration=22500,
medium_stress_duration=2520,
high_stress_duration=300
)
]
```
Weekly stress levels
```python
WeeklyStress.list("2023-07-23", 2)
```
```python
[
WeeklyStress(calendar_date=datetime.date(2023, 7, 10), value=33),
WeeklyStress(calendar_date=datetime.date(2023, 7, 17), value=32)
]
```
### Steps
Daily steps
```python
garth.DailySteps.list(period=2)
```
```python
[
DailySteps(
calendar_date=datetime.date(2023, 7, 28),
total_steps=6510,
total_distance=5552,
step_goal=8090
),
DailySteps(
calendar_date=datetime.date(2023, 7, 29),
total_steps=7218,
total_distance=6002,
step_goal=7940
)
]
```
Weekly steps
```python
garth.WeeklySteps.list(period=2)
```
```python
[
WeeklySteps(
calendar_date=datetime.date(2023, 7, 16),
total_steps=42339,
average_steps=6048.428571428572,
average_distance=5039.285714285715,
total_distance=35275.0,
wellness_data_days_count=7
),
WeeklySteps(
calendar_date=datetime.date(2023, 7, 23),
total_steps=56420,
average_steps=8060.0,
average_distance=7198.142857142857,
total_distance=50387.0,
wellness_data_days_count=7
)
]
```
### Intensity Minutes
Daily intensity minutes
```python
garth.DailyIntensityMinutes.list(period=2)
```
```python
[
DailyIntensityMinutes(
calendar_date=datetime.date(2023, 7, 28),
weekly_goal=150,
moderate_value=0,
vigorous_value=0
),
DailyIntensityMinutes(
calendar_date=datetime.date(2023, 7, 29),
weekly_goal=150,
moderate_value=0,
vigorous_value=0
)
]
```
Weekly intensity minutes
```python
garth.WeeklyIntensityMinutes.list(period=2)
```
```python
[
WeeklyIntensityMinutes(
calendar_date=datetime.date(2023, 7, 17),
weekly_goal=150,
moderate_value=103,
vigorous_value=9
),
WeeklyIntensityMinutes(
calendar_date=datetime.date(2023, 7, 24),
weekly_goal=150,
moderate_value=101,
vigorous_value=105
)
]
```
### HRV
Daily HRV
```python
garth.DailyHRV.list(period=2)
```
```python
[
DailyHRV(
calendar_date=datetime.date(2023, 7, 28),
weekly_avg=39,
last_night_avg=36,
last_night_5_min_high=52,
baseline=HRVBaseline(
low_upper=36,
balanced_low=39,
balanced_upper=51,
marker_value=0.25
),
status='BALANCED',
feedback_phrase='HRV_BALANCED_2',
create_time_stamp=datetime.datetime(2023, 7, 28, 12, 40, 16, 785000)
),
DailyHRV(
calendar_date=datetime.date(2023, 7, 29),
weekly_avg=40,
last_night_avg=41,
last_night_5_min_high=76,
baseline=HRVBaseline(
low_upper=36,
balanced_low=39,
balanced_upper=51,
marker_value=0.2916565
),
status='BALANCED',
feedback_phrase='HRV_BALANCED_8',
create_time_stamp=datetime.datetime(2023, 7, 29, 13, 45, 23, 479000)
)
]
```
Detailed HRV data
```python
garth.HRVData.get("2023-07-20")
```
```python
HRVData(
user_profile_pk=2591602,
hrv_summary=HRVSummary(
calendar_date=datetime.date(2023, 7, 20),
weekly_avg=39,
last_night_avg=42,
last_night_5_min_high=66,
baseline=Baseline(
low_upper=36,
balanced_low=39,
balanced_upper=52,
marker_value=0.25
),
status='BALANCED',
feedback_phrase='HRV_BALANCED_7',
create_time_stamp=datetime.datetime(2023, 7, 20, 12, 14, 11, 898000)
),
hrv_readings=[
HRVReading(
hrv_value=54,
reading_time_gmt=datetime.datetime(2023, 7, 20, 5, 29, 48),
reading_time_local=datetime.datetime(2023, 7, 19, 23, 29, 48)
),
HRVReading(
hrv_value=56,
reading_time_gmt=datetime.datetime(2023, 7, 20, 5, 34, 48),
reading_time_local=datetime.datetime(2023, 7, 19, 23, 34, 48)
),
# ... truncated for brevity
HRVReading(
hrv_value=38,
reading_time_gmt=datetime.datetime(2023, 7, 20, 12, 9, 48),
reading_time_local=datetime.datetime(2023, 7, 20, 6, 9, 48)
)
],
start_timestamp_gmt=datetime.datetime(2023, 7, 20, 5, 25),
end_timestamp_gmt=datetime.datetime(2023, 7, 20, 12, 9, 48),
start_timestamp_local=datetime.datetime(2023, 7, 19, 23, 25),
end_timestamp_local=datetime.datetime(2023, 7, 20, 6, 9, 48),
sleep_start_timestamp_gmt=datetime.datetime(2023, 7, 20, 5, 25),
sleep_end_timestamp_gmt=datetime.datetime(2023, 7, 20, 12, 11),
sleep_start_timestamp_local=datetime.datetime(2023, 7, 19, 23, 25),
sleep_end_timestamp_local=datetime.datetime(2023, 7, 20, 6, 11)
)
```
### Sleep
Daily sleep quality
```python
garth.DailySleep.list("2023-07-23", 2)
```
```python
[
DailySleep(calendar_date=datetime.date(2023, 7, 22), value=69),
DailySleep(calendar_date=datetime.date(2023, 7, 23), value=73)
]
```
Detailed sleep data
```python
garth.SleepData.get("2023-07-20")
```
```python
SleepData(
daily_sleep_dto=DailySleepDTO(
id=1689830700000,
user_profile_pk=2591602,
calendar_date=datetime.date(2023, 7, 20),
sleep_time_seconds=23700,
nap_time_seconds=0,
sleep_window_confirmed=True,
sleep_window_confirmation_type='enhanced_confirmed_final',
sleep_start_timestamp_gmt=datetime.datetime(2023, 7, 20, 5, 25, tzinfo=TzInfo(UTC)),
sleep_end_timestamp_gmt=datetime.datetime(2023, 7, 20, 12, 11, tzinfo=TzInfo(UTC)),
sleep_start_timestamp_local=datetime.datetime(2023, 7, 19, 23, 25, tzinfo=TzInfo(UTC)),
sleep_end_timestamp_local=datetime.datetime(2023, 7, 20, 6, 11, tzinfo=TzInfo(UTC)),
unmeasurable_sleep_seconds=0,
deep_sleep_seconds=9660,
light_sleep_seconds=12600,
rem_sleep_seconds=1440,
awake_sleep_seconds=660,
device_rem_capable=True,
retro=False,
sleep_from_device=True,
sleep_version=2,
awake_count=1,
sleep_scores=SleepScores(
total_duration=Score(
qualifier_key='FAIR',
optimal_start=28800.0,
optimal_end=28800.0,
value=None,
ideal_start_in_seconds=None,
deal_end_in_seconds=None
),
stress=Score(
qualifier_key='FAIR',
optimal_start=0.0,
optimal_end=15.0,
value=None,
ideal_start_in_seconds=None,
ideal_end_in_seconds=None
),
awake_count=Score(
qualifier_key='GOOD',
optimal_start=0.0,
optimal_end=1.0,
value=None,
ideal_start_in_seconds=None,
ideal_end_in_seconds=None
),
overall=Score(
qualifier_key='FAIR',
optimal_start=None,
optimal_end=None,
value=68,
ideal_start_in_seconds=None,
ideal_end_in_seconds=None
),
rem_percentage=Score(
qualifier_key='POOR',
optimal_start=21.0,
optimal_end=31.0,
value=6,
ideal_start_in_seconds=4977.0,
ideal_end_in_seconds=7347.0
),
restlessness=Score(
qualifier_key='EXCELLENT',
optimal_start=0.0,
optimal_end=5.0,
value=None,
ideal_start_in_seconds=None,
ideal_end_in_seconds=None
),
light_percentage=Score(
qualifier_key='EXCELLENT',
optimal_start=30.0,
optimal_end=64.0,
value=53,
ideal_start_in_seconds=7110.0,
ideal_end_in_seconds=15168.0
),
deep_percentage=Score(
qualifier_key='EXCELLENT',
optimal_start=16.0,
optimal_end=33.0,
value=41,
ideal_start_in_seconds=3792.0,
ideal_end_in_seconds=7821.0
)
),
auto_sleep_start_timestamp_gmt=None,
auto_sleep_end_timestamp_gmt=None,
sleep_quality_type_pk=None,
sleep_result_type_pk=None,
average_sp_o2_value=92.0,
lowest_sp_o2_value=87,
highest_sp_o2_value=100,
average_sp_o2_hr_sleep=53.0,
average_respiration_value=14.0,
lowest_respiration_value=12.0,
highest_respiration_value=16.0,
avg_sleep_stress=17.0,
age_group='ADULT',
sleep_score_feedback='NEGATIVE_NOT_ENOUGH_REM',
sleep_score_insight='NONE'
),
sleep_movement=[
SleepMovement(
start_gmt=datetime.datetime(2023, 7, 20, 4, 25),
end_gmt=datetime.datetime(2023, 7, 20, 4, 26),
activity_level=5.688743692980419
),
SleepMovement(
start_gmt=datetime.datetime(2023, 7, 20, 4, 26),
end_gmt=datetime.datetime(2023, 7, 20, 4, 27),
activity_level=5.318763075304898
),
# ... truncated for brevity
SleepMovement(
start_gmt=datetime.datetime(2023, 7, 20, 13, 10),
end_gmt=datetime.datetime(2023, 7, 20, 13, 11),
activity_level=7.088729101943337
)
]
)
```
List sleep data over several nights.
```python
garth.SleepData.list("2023-07-20", 30)
```
## User
### UserProfile
```python
garth.UserProfile.get()
```
```python
UserProfile(
id=3154645,
profile_id=2591602,
garmin_guid="0690cc1d-d23d-4412-b027-80fd4ed1c0f6",
display_name="mtamizi",
full_name="Matin Tamizi",
user_name="mtamizi",
profile_image_uuid="73240e81-6e4d-43fc-8af8-c8f6c51b3b8f",
profile_image_url_large=(
"https://s3.amazonaws.com/garmin-connect-prod/profile_images/"
"73240e81-6e4d-43fc-8af8-c8f6c51b3b8f-2591602.png"
),
profile_image_url_medium=(
"https://s3.amazonaws.com/garmin-connect-prod/profile_images/"
"685a19e9-a7be-4a11-9bf9-faca0c5d1f1a-2591602.png"
),
profile_image_url_small=(
"https://s3.amazonaws.com/garmin-connect-prod/profile_images/"
"6302f021-0ec7-4dc9-b0c3-d5a19bc5a08c-2591602.png"
),
location="Ciudad de México, CDMX",
facebook_url=None,
twitter_url=None,
personal_website=None,
motivation=None,
bio=None,
primary_activity=None,
favorite_activity_types=[],
running_training_speed=0.0,
cycling_training_speed=0.0,
favorite_cycling_activity_types=[],
cycling_classification=None,
cycling_max_avg_power=0.0,
swimming_training_speed=0.0,
profile_visibility="private",
activity_start_visibility="private",
activity_map_visibility="public",
course_visibility="public",
activity_heart_rate_visibility="public",
activity_power_visibility="public",
badge_visibility="private",
show_age=False,
show_weight=False,
show_height=False,
show_weight_class=False,
show_age_range=False,
show_gender=False,
show_activity_class=False,
show_vo_2_max=False,
show_personal_records=False,
show_last_12_months=False,
show_lifetime_totals=False,
show_upcoming_events=False,
show_recent_favorites=False,
show_recent_device=False,
show_recent_gear=False,
show_badges=True,
other_activity=None,
other_primary_activity=None,
other_motivation=None,
user_roles=[
"SCOPE_ATP_READ",
"SCOPE_ATP_WRITE",
"SCOPE_COMMUNITY_COURSE_READ",
"SCOPE_COMMUNITY_COURSE_WRITE",
"SCOPE_CONNECT_READ",
"SCOPE_CONNECT_WRITE",
"SCOPE_DT_CLIENT_ANALYTICS_WRITE",
"SCOPE_GARMINPAY_READ",
"SCOPE_GARMINPAY_WRITE",
"SCOPE_GCOFFER_READ",
"SCOPE_GCOFFER_WRITE",
"SCOPE_GHS_SAMD",
"SCOPE_GHS_UPLOAD",
"SCOPE_GOLF_API_READ",
"SCOPE_GOLF_API_WRITE",
"SCOPE_INSIGHTS_READ",
"SCOPE_INSIGHTS_WRITE",
"SCOPE_PRODUCT_SEARCH_READ",
"ROLE_CONNECTUSER",
"ROLE_FITNESS_USER",
"ROLE_WELLNESS_USER",
"ROLE_OUTDOOR_USER",
"ROLE_CONNECT_2_USER",
"ROLE_TACX_APP_USER",
],
name_approved=True,
user_profile_full_name="Matin Tamizi",
make_golf_scorecards_private=True,
allow_golf_live_scoring=False,
allow_golf_scoring_by_connections=True,
user_level=3,
user_point=118,
level_update_date="2020-12-12T15:20:38.0",
level_is_viewed=False,
level_point_threshold=140,
user_point_offset=0,
user_pro=False,
)
```
### UserSettings
```python
garth.UserSettings.get()
```
```python
UserSettings(
id=2591602,
user_data=UserData(
gender="MALE",
weight=83000.0,
height=182.0,
time_format="time_twenty_four_hr",
birth_date=datetime.date(1984, 10, 17),
measurement_system="metric",
activity_level=None,
handedness="RIGHT",
power_format=PowerFormat(
format_id=30,
format_key="watt",
min_fraction=0,
max_fraction=0,
grouping_used=True,
display_format=None,
),
heart_rate_format=PowerFormat(
format_id=21,
format_key="bpm",
min_fraction=0,
max_fraction=0,
grouping_used=False,
display_format=None,
),
first_day_of_week=FirstDayOfWeek(
day_id=2,
day_name="sunday",
sort_order=2,
is_possible_first_day=True,
),
vo_2_max_running=45.0,
vo_2_max_cycling=None,
lactate_threshold_speed=0.34722125000000004,
lactate_threshold_heart_rate=None,
dive_number=None,
intensity_minutes_calc_method="AUTO",
moderate_intensity_minutes_hr_zone=3,
vigorous_intensity_minutes_hr_zone=4,
hydration_measurement_unit="milliliter",
hydration_containers=[],
hydration_auto_goal_enabled=True,
firstbeat_max_stress_score=None,
firstbeat_cycling_lt_timestamp=None,
firstbeat_running_lt_timestamp=1044719868,
threshold_heart_rate_auto_detected=True,
ftp_auto_detected=None,
training_status_paused_date=None,
weather_location=None,
golf_distance_unit="statute_us",
golf_elevation_unit=None,
golf_speed_unit=None,
external_bottom_time=None,
),
user_sleep=UserSleep(
sleep_time=80400,
default_sleep_time=False,
wake_time=24000,
default_wake_time=False,
),
connect_date=None,
source_type=None,
)
```
Raw data
{
"_id": null,
"home_page": null,
"name": "garth",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "garmin, garmin api, garmin connect, garmin sso",
"author": null,
"author_email": "Matin Tamizi <mtamizi@duck.com>",
"download_url": "https://files.pythonhosted.org/packages/c3/22/d936e91a7f083b6340e5a06dc3d7f7f84d36edeb798f0664e48fbd3a1cef/garth-0.4.46.tar.gz",
"platform": null,
"description": "# Garth\n\n[](https://github.com/matin/garth/actions/workflows/ci.yml?query=event%3Apush+branch%3Amain+workflow%3ACI)\n[](https://codecov.io/gh/matin/garth)\n[](https://www.pepy.tech/projects/garth)\n\nGarmin SSO auth + Connect Python client\n\n## Google Colabs\n\n### [Stress: 28-day rolling average](https://colab.research.google.com/github/matin/garth/blob/main/colabs/stress.ipynb)\n\nStress levels from one day to another can vary by extremes, but there's always\na general trend. Using a scatter plot with a rolling average shows both the\nindividual days and the trend. The Colab retrieves up to three years of daily\ndata. If there's less than three years of data, it retrieves whatever is\navailable.\n\n\n\n### [Sleep analysis over 90 days](https://colab.research.google.com/github/matin/garth/blob/main/colabs/sleep.ipynb)\n\nThe Garmin Connect app only shows a maximum of seven days for sleep\nstages\u2014making it hard to see trends. The Connect API supports retrieving\ndaily sleep quality in 28-day pages, but that doesn't show details. Using\n`SleedData.list()` gives us the ability to retrieve an arbitrary number of\nday with enough detail to product a stacked bar graph of the daily sleep\nstages.\n\n\n\nOne specific graph that's useful but not available in the Connect app is\nsleep start and end times over an extended period. This provides context\nto the sleep hours and stages.\n\n\n\n### [ChatGPT analysis of Garmin stats](https://colab.research.google.com/github/matin/garth/blob/main/colabs/chatgpt_analysis_of_stats.ipynb)\n\nChatGPT's Advanced Data Analysis took can provide incredible insight\ninto the data in a way that's much simpler than using Pandas and Matplotlib.\n\nStart by using the linked Colab to download a CSV of the last three years\nof your stats, and upload the CSV to ChatGPT.\n\nHere's the outputs of the following prompts:\n\nHow do I sleep on different days of the week?\n\n<img width=\"600\" alt=\"image\" src=\"https://github.com/matin/garth/assets/98985/b7507459-2482-43d6-bf55-c3a1f756facb\">\n\nOn what days do I exercise the most?\n\n<img width=\"600\" alt=\"image\" src=\"https://github.com/matin/garth/assets/98985/11294be2-8e1a-4fed-a489-13420765aada\">\n\nMagic!\n\n## Background\n\nGarth is meant for personal use and follows the philosophy that your data is\nyour data. You should be able to download it and analyze it in the way that\nyou'd like. In my case, that means processing with Google Colab, Pandas,\nMatplotlib, etc.\n\nThere are already a few Garmin Connect libraries. Why write another?\n\n### Authentication and stability\n\nThe most important reasoning is to build a library with authentication that\nworks on [Google Colab](https://colab.research.google.com/) and doesn't require\ntools like Cloudscraper. Garth, in comparison:\n\n1. Uses OAuth1 and OAuth2 token authentication after initial login\n1. OAuth1 token survives for a year\n1. Supports MFA\n1. Auto-refresh of OAuth2 token when expired\n1. Works on Google Colab\n1. Uses Pydantic dataclasses to validate and simplify use of data\n1. Full test coverage\n\n### JSON vs HTML\n\nUsing `garth.connectapi()` allows you to make requests to the Connect API\nand receive JSON vs needing to parse HTML. You can use the same endpoints the\nmobile app uses.\n\nThis also goes back to authentication. Garth manages the necessary Bearer\nAuthentication (along with auto-refresh) necessary to make requests routed to\nthe Connect API.\n\n## Instructions\n\n### Install\n\n```bash\npython -m pip install garth\n```\n\n### Clone, setup environment and run tests\n\n```bash\ngh repo clone matin/garth\ncd garth\nmake install\nmake\n```\n\nUse `make help` to see all the options.\n\n### Authenticate and save session\n\n```python\nimport garth\nfrom getpass import getpass\n\nemail = input(\"Enter email address: \")\npassword = getpass(\"Enter password: \")\n# If there's MFA, you'll be prompted during the login\ngarth.login(email, password)\n\ngarth.save(\"~/.garth\")\n```\n\n### Custom MFA handler\n\nThere's already a default MFA handler that prompts for the code in the\nterminal. You can provide your own handler. The handler should return the\nMFA code through your custom prompt.\n\n```python\ngarth.login(email, password, prompt_mfa=lambda: input(\"Enter MFA code: \"))\n```\n\n### Configure\n\n#### Set domain for China\n\n```python\ngarth.configure(domain=\"garmin.cn\")\n```\n\n#### Proxy through Charles\n\n```python\ngarth.configure(proxies={\"https\": \"http://localhost:8888\"}, ssl_verify=False)\n```\n\n### Attempt to resume session\n\n```python\nimport garth\nfrom garth.exc import GarthException\n\ngarth.resume(\"~/.garth\")\ntry:\n garth.client.username\nexcept GarthException:\n # Session is expired. You'll need to log in again\n```\n\n## Connect API\n\n### Daily details\n\n```python\nsleep = garth.connectapi(\n f\"/wellness-service/wellness/dailySleepData/{garth.client.username}\",\n params={\"date\": \"2023-07-05\", \"nonSleepBufferMinutes\": 60},\n)\nlist(sleep.keys())\n```\n\n```json\n[\n \"dailySleepDTO\",\n \"sleepMovement\",\n \"remSleepData\",\n \"sleepLevels\",\n \"sleepRestlessMoments\",\n \"restlessMomentsCount\",\n \"wellnessSpO2SleepSummaryDTO\",\n \"wellnessEpochSPO2DataDTOList\",\n \"wellnessEpochRespirationDataDTOList\",\n \"sleepStress\"\n]\n```\n\n### Stats\n\n```python\nstress = garth.connectapi(\"/usersummary-service/stats/stress/weekly/2023-07-05/52\")\n```\n\n```json\n{\n \"calendarDate\": \"2023-07-13\",\n \"values\": {\n \"highStressDuration\": 2880,\n \"lowStressDuration\": 10140,\n \"overallStressLevel\": 33,\n \"restStressDuration\": 30960,\n \"mediumStressDuration\": 8760\n }\n}\n```\n\n## Upload\n\n```python\nwith open(\"12129115726_ACTIVITY.fit\", \"rb\") as f:\n uploaded = garth.client.upload(f)\n```\n\nNote: Garmin doesn't accept uploads of _structured_ FIT files as outlined in\n[this conversation](https://github.com/matin/garth/issues/27). FIT files\ngenerated from workouts are accepted without issues.\n\n```python\n{\n 'detailedImportResult': {\n 'uploadId': 212157427938,\n 'uploadUuid': {\n 'uuid': '6e56051d-1dd4-4f2c-b8ba-00a1a7d82eb3'\n },\n 'owner': 2591602,\n 'fileSize': 5289,\n 'processingTime': 36,\n 'creationDate': '2023-09-29 01:58:19.113 GMT',\n 'ipAddress': None,\n 'fileName': '12129115726_ACTIVITY.fit',\n 'report': None,\n 'successes': [],\n 'failures': []\n }\n}\n```\n\n## Stats resources\n\n### Stress\n\nDaily stress levels\n\n```python\nDailyStress.list(\"2023-07-23\", 2)\n```\n\n```python\n[\n DailyStress(\n calendar_date=datetime.date(2023, 7, 22),\n overall_stress_level=31,\n rest_stress_duration=31980,\n low_stress_duration=23820,\n medium_stress_duration=7440,\n high_stress_duration=1500\n ),\n DailyStress(\n calendar_date=datetime.date(2023, 7, 23),\n overall_stress_level=26,\n rest_stress_duration=38220,\n low_stress_duration=22500,\n medium_stress_duration=2520,\n high_stress_duration=300\n )\n]\n```\n\nWeekly stress levels\n\n```python\nWeeklyStress.list(\"2023-07-23\", 2)\n```\n\n```python\n[\n WeeklyStress(calendar_date=datetime.date(2023, 7, 10), value=33),\n WeeklyStress(calendar_date=datetime.date(2023, 7, 17), value=32)\n]\n```\n\n### Steps\n\nDaily steps\n\n```python\ngarth.DailySteps.list(period=2)\n```\n\n```python\n[\n DailySteps(\n calendar_date=datetime.date(2023, 7, 28),\n total_steps=6510,\n total_distance=5552,\n step_goal=8090\n ),\n DailySteps(\n calendar_date=datetime.date(2023, 7, 29),\n total_steps=7218,\n total_distance=6002,\n step_goal=7940\n )\n]\n```\n\nWeekly steps\n\n```python\ngarth.WeeklySteps.list(period=2)\n```\n\n```python\n[\n WeeklySteps(\n calendar_date=datetime.date(2023, 7, 16),\n total_steps=42339,\n average_steps=6048.428571428572,\n average_distance=5039.285714285715,\n total_distance=35275.0,\n wellness_data_days_count=7\n ),\n WeeklySteps(\n calendar_date=datetime.date(2023, 7, 23),\n total_steps=56420,\n average_steps=8060.0,\n average_distance=7198.142857142857,\n total_distance=50387.0,\n wellness_data_days_count=7\n )\n]\n```\n\n### Intensity Minutes\n\nDaily intensity minutes\n\n```python\ngarth.DailyIntensityMinutes.list(period=2)\n```\n\n```python\n[\n DailyIntensityMinutes(\n calendar_date=datetime.date(2023, 7, 28),\n weekly_goal=150,\n moderate_value=0,\n vigorous_value=0\n ),\n DailyIntensityMinutes(\n calendar_date=datetime.date(2023, 7, 29),\n weekly_goal=150,\n moderate_value=0,\n vigorous_value=0\n )\n]\n```\n\nWeekly intensity minutes\n\n```python\ngarth.WeeklyIntensityMinutes.list(period=2)\n```\n\n```python\n[\n WeeklyIntensityMinutes(\n calendar_date=datetime.date(2023, 7, 17),\n weekly_goal=150,\n moderate_value=103,\n vigorous_value=9\n ),\n WeeklyIntensityMinutes(\n calendar_date=datetime.date(2023, 7, 24),\n weekly_goal=150,\n moderate_value=101,\n vigorous_value=105\n )\n]\n```\n\n### HRV\n\nDaily HRV\n\n```python\ngarth.DailyHRV.list(period=2)\n```\n\n```python\n[\n DailyHRV(\n calendar_date=datetime.date(2023, 7, 28),\n weekly_avg=39,\n last_night_avg=36,\n last_night_5_min_high=52,\n baseline=HRVBaseline(\n low_upper=36,\n balanced_low=39,\n balanced_upper=51,\n marker_value=0.25\n ),\n status='BALANCED',\n feedback_phrase='HRV_BALANCED_2',\n create_time_stamp=datetime.datetime(2023, 7, 28, 12, 40, 16, 785000)\n ),\n DailyHRV(\n calendar_date=datetime.date(2023, 7, 29),\n weekly_avg=40,\n last_night_avg=41,\n last_night_5_min_high=76,\n baseline=HRVBaseline(\n low_upper=36,\n balanced_low=39,\n balanced_upper=51,\n marker_value=0.2916565\n ),\n status='BALANCED',\n feedback_phrase='HRV_BALANCED_8',\n create_time_stamp=datetime.datetime(2023, 7, 29, 13, 45, 23, 479000)\n )\n]\n```\n\nDetailed HRV data\n\n```python\ngarth.HRVData.get(\"2023-07-20\")\n```\n\n```python\nHRVData(\n user_profile_pk=2591602,\n hrv_summary=HRVSummary(\n calendar_date=datetime.date(2023, 7, 20),\n weekly_avg=39,\n last_night_avg=42,\n last_night_5_min_high=66,\n baseline=Baseline(\n low_upper=36,\n balanced_low=39,\n balanced_upper=52,\n marker_value=0.25\n ),\n status='BALANCED',\n feedback_phrase='HRV_BALANCED_7',\n create_time_stamp=datetime.datetime(2023, 7, 20, 12, 14, 11, 898000)\n ),\n hrv_readings=[\n HRVReading(\n hrv_value=54,\n reading_time_gmt=datetime.datetime(2023, 7, 20, 5, 29, 48),\n reading_time_local=datetime.datetime(2023, 7, 19, 23, 29, 48)\n ),\n HRVReading(\n hrv_value=56,\n reading_time_gmt=datetime.datetime(2023, 7, 20, 5, 34, 48),\n reading_time_local=datetime.datetime(2023, 7, 19, 23, 34, 48)\n ),\n # ... truncated for brevity\n HRVReading(\n hrv_value=38,\n reading_time_gmt=datetime.datetime(2023, 7, 20, 12, 9, 48),\n reading_time_local=datetime.datetime(2023, 7, 20, 6, 9, 48)\n )\n ],\n start_timestamp_gmt=datetime.datetime(2023, 7, 20, 5, 25),\n end_timestamp_gmt=datetime.datetime(2023, 7, 20, 12, 9, 48),\n start_timestamp_local=datetime.datetime(2023, 7, 19, 23, 25),\n end_timestamp_local=datetime.datetime(2023, 7, 20, 6, 9, 48),\n sleep_start_timestamp_gmt=datetime.datetime(2023, 7, 20, 5, 25),\n sleep_end_timestamp_gmt=datetime.datetime(2023, 7, 20, 12, 11),\n sleep_start_timestamp_local=datetime.datetime(2023, 7, 19, 23, 25),\n sleep_end_timestamp_local=datetime.datetime(2023, 7, 20, 6, 11)\n)\n```\n\n### Sleep\n\nDaily sleep quality\n\n```python\ngarth.DailySleep.list(\"2023-07-23\", 2)\n```\n\n```python\n[\n DailySleep(calendar_date=datetime.date(2023, 7, 22), value=69),\n DailySleep(calendar_date=datetime.date(2023, 7, 23), value=73)\n]\n```\n\nDetailed sleep data\n\n```python\ngarth.SleepData.get(\"2023-07-20\")\n```\n\n```python\nSleepData(\n daily_sleep_dto=DailySleepDTO(\n id=1689830700000,\n user_profile_pk=2591602,\n calendar_date=datetime.date(2023, 7, 20),\n sleep_time_seconds=23700,\n nap_time_seconds=0,\n sleep_window_confirmed=True,\n sleep_window_confirmation_type='enhanced_confirmed_final',\n sleep_start_timestamp_gmt=datetime.datetime(2023, 7, 20, 5, 25, tzinfo=TzInfo(UTC)),\n sleep_end_timestamp_gmt=datetime.datetime(2023, 7, 20, 12, 11, tzinfo=TzInfo(UTC)),\n sleep_start_timestamp_local=datetime.datetime(2023, 7, 19, 23, 25, tzinfo=TzInfo(UTC)),\n sleep_end_timestamp_local=datetime.datetime(2023, 7, 20, 6, 11, tzinfo=TzInfo(UTC)),\n unmeasurable_sleep_seconds=0,\n deep_sleep_seconds=9660,\n light_sleep_seconds=12600,\n rem_sleep_seconds=1440,\n awake_sleep_seconds=660,\n device_rem_capable=True,\n retro=False,\n sleep_from_device=True,\n sleep_version=2,\n awake_count=1,\n sleep_scores=SleepScores(\n total_duration=Score(\n qualifier_key='FAIR',\n optimal_start=28800.0,\n optimal_end=28800.0,\n value=None,\n ideal_start_in_seconds=None,\n deal_end_in_seconds=None\n ),\n stress=Score(\n qualifier_key='FAIR',\n optimal_start=0.0,\n optimal_end=15.0,\n value=None,\n ideal_start_in_seconds=None,\n ideal_end_in_seconds=None\n ),\n awake_count=Score(\n qualifier_key='GOOD',\n optimal_start=0.0,\n optimal_end=1.0,\n value=None,\n ideal_start_in_seconds=None,\n ideal_end_in_seconds=None\n ),\n overall=Score(\n qualifier_key='FAIR',\n optimal_start=None,\n optimal_end=None,\n value=68,\n ideal_start_in_seconds=None,\n ideal_end_in_seconds=None\n ),\n rem_percentage=Score(\n qualifier_key='POOR',\n optimal_start=21.0,\n optimal_end=31.0,\n value=6,\n ideal_start_in_seconds=4977.0,\n ideal_end_in_seconds=7347.0\n ),\n restlessness=Score(\n qualifier_key='EXCELLENT',\n optimal_start=0.0,\n optimal_end=5.0,\n value=None,\n ideal_start_in_seconds=None,\n ideal_end_in_seconds=None\n ),\n light_percentage=Score(\n qualifier_key='EXCELLENT',\n optimal_start=30.0,\n optimal_end=64.0,\n value=53,\n ideal_start_in_seconds=7110.0,\n ideal_end_in_seconds=15168.0\n ),\n deep_percentage=Score(\n qualifier_key='EXCELLENT',\n optimal_start=16.0,\n optimal_end=33.0,\n value=41,\n ideal_start_in_seconds=3792.0,\n ideal_end_in_seconds=7821.0\n )\n ),\n auto_sleep_start_timestamp_gmt=None,\n auto_sleep_end_timestamp_gmt=None,\n sleep_quality_type_pk=None,\n sleep_result_type_pk=None,\n average_sp_o2_value=92.0,\n lowest_sp_o2_value=87,\n highest_sp_o2_value=100,\n average_sp_o2_hr_sleep=53.0,\n average_respiration_value=14.0,\n lowest_respiration_value=12.0,\n highest_respiration_value=16.0,\n avg_sleep_stress=17.0,\n age_group='ADULT',\n sleep_score_feedback='NEGATIVE_NOT_ENOUGH_REM',\n sleep_score_insight='NONE'\n ),\n sleep_movement=[\n SleepMovement(\n start_gmt=datetime.datetime(2023, 7, 20, 4, 25),\n end_gmt=datetime.datetime(2023, 7, 20, 4, 26),\n activity_level=5.688743692980419\n ),\n SleepMovement(\n start_gmt=datetime.datetime(2023, 7, 20, 4, 26),\n end_gmt=datetime.datetime(2023, 7, 20, 4, 27),\n activity_level=5.318763075304898\n ),\n # ... truncated for brevity\n SleepMovement(\n start_gmt=datetime.datetime(2023, 7, 20, 13, 10),\n end_gmt=datetime.datetime(2023, 7, 20, 13, 11),\n activity_level=7.088729101943337\n )\n ]\n)\n```\n\nList sleep data over several nights.\n\n```python\ngarth.SleepData.list(\"2023-07-20\", 30)\n```\n\n## User\n\n### UserProfile\n\n```python\ngarth.UserProfile.get()\n```\n\n```python\nUserProfile(\n id=3154645,\n profile_id=2591602,\n garmin_guid=\"0690cc1d-d23d-4412-b027-80fd4ed1c0f6\",\n display_name=\"mtamizi\",\n full_name=\"Matin Tamizi\",\n user_name=\"mtamizi\",\n profile_image_uuid=\"73240e81-6e4d-43fc-8af8-c8f6c51b3b8f\",\n profile_image_url_large=(\n \"https://s3.amazonaws.com/garmin-connect-prod/profile_images/\"\n \"73240e81-6e4d-43fc-8af8-c8f6c51b3b8f-2591602.png\"\n ),\n profile_image_url_medium=(\n \"https://s3.amazonaws.com/garmin-connect-prod/profile_images/\"\n \"685a19e9-a7be-4a11-9bf9-faca0c5d1f1a-2591602.png\"\n ),\n profile_image_url_small=(\n \"https://s3.amazonaws.com/garmin-connect-prod/profile_images/\"\n \"6302f021-0ec7-4dc9-b0c3-d5a19bc5a08c-2591602.png\"\n ),\n location=\"Ciudad de M\u00e9xico, CDMX\",\n facebook_url=None,\n twitter_url=None,\n personal_website=None,\n motivation=None,\n bio=None,\n primary_activity=None,\n favorite_activity_types=[],\n running_training_speed=0.0,\n cycling_training_speed=0.0,\n favorite_cycling_activity_types=[],\n cycling_classification=None,\n cycling_max_avg_power=0.0,\n swimming_training_speed=0.0,\n profile_visibility=\"private\",\n activity_start_visibility=\"private\",\n activity_map_visibility=\"public\",\n course_visibility=\"public\",\n activity_heart_rate_visibility=\"public\",\n activity_power_visibility=\"public\",\n badge_visibility=\"private\",\n show_age=False,\n show_weight=False,\n show_height=False,\n show_weight_class=False,\n show_age_range=False,\n show_gender=False,\n show_activity_class=False,\n show_vo_2_max=False,\n show_personal_records=False,\n show_last_12_months=False,\n show_lifetime_totals=False,\n show_upcoming_events=False,\n show_recent_favorites=False,\n show_recent_device=False,\n show_recent_gear=False,\n show_badges=True,\n other_activity=None,\n other_primary_activity=None,\n other_motivation=None,\n user_roles=[\n \"SCOPE_ATP_READ\",\n \"SCOPE_ATP_WRITE\",\n \"SCOPE_COMMUNITY_COURSE_READ\",\n \"SCOPE_COMMUNITY_COURSE_WRITE\",\n \"SCOPE_CONNECT_READ\",\n \"SCOPE_CONNECT_WRITE\",\n \"SCOPE_DT_CLIENT_ANALYTICS_WRITE\",\n \"SCOPE_GARMINPAY_READ\",\n \"SCOPE_GARMINPAY_WRITE\",\n \"SCOPE_GCOFFER_READ\",\n \"SCOPE_GCOFFER_WRITE\",\n \"SCOPE_GHS_SAMD\",\n \"SCOPE_GHS_UPLOAD\",\n \"SCOPE_GOLF_API_READ\",\n \"SCOPE_GOLF_API_WRITE\",\n \"SCOPE_INSIGHTS_READ\",\n \"SCOPE_INSIGHTS_WRITE\",\n \"SCOPE_PRODUCT_SEARCH_READ\",\n \"ROLE_CONNECTUSER\",\n \"ROLE_FITNESS_USER\",\n \"ROLE_WELLNESS_USER\",\n \"ROLE_OUTDOOR_USER\",\n \"ROLE_CONNECT_2_USER\",\n \"ROLE_TACX_APP_USER\",\n ],\n name_approved=True,\n user_profile_full_name=\"Matin Tamizi\",\n make_golf_scorecards_private=True,\n allow_golf_live_scoring=False,\n allow_golf_scoring_by_connections=True,\n user_level=3,\n user_point=118,\n level_update_date=\"2020-12-12T15:20:38.0\",\n level_is_viewed=False,\n level_point_threshold=140,\n user_point_offset=0,\n user_pro=False,\n)\n```\n\n### UserSettings\n\n```python\ngarth.UserSettings.get()\n```\n\n```python\nUserSettings(\n id=2591602,\n user_data=UserData(\n gender=\"MALE\",\n weight=83000.0,\n height=182.0,\n time_format=\"time_twenty_four_hr\",\n birth_date=datetime.date(1984, 10, 17),\n measurement_system=\"metric\",\n activity_level=None,\n handedness=\"RIGHT\",\n power_format=PowerFormat(\n format_id=30,\n format_key=\"watt\",\n min_fraction=0,\n max_fraction=0,\n grouping_used=True,\n display_format=None,\n ),\n heart_rate_format=PowerFormat(\n format_id=21,\n format_key=\"bpm\",\n min_fraction=0,\n max_fraction=0,\n grouping_used=False,\n display_format=None,\n ),\n first_day_of_week=FirstDayOfWeek(\n day_id=2,\n day_name=\"sunday\",\n sort_order=2,\n is_possible_first_day=True,\n ),\n vo_2_max_running=45.0,\n vo_2_max_cycling=None,\n lactate_threshold_speed=0.34722125000000004,\n lactate_threshold_heart_rate=None,\n dive_number=None,\n intensity_minutes_calc_method=\"AUTO\",\n moderate_intensity_minutes_hr_zone=3,\n vigorous_intensity_minutes_hr_zone=4,\n hydration_measurement_unit=\"milliliter\",\n hydration_containers=[],\n hydration_auto_goal_enabled=True,\n firstbeat_max_stress_score=None,\n firstbeat_cycling_lt_timestamp=None,\n firstbeat_running_lt_timestamp=1044719868,\n threshold_heart_rate_auto_detected=True,\n ftp_auto_detected=None,\n training_status_paused_date=None,\n weather_location=None,\n golf_distance_unit=\"statute_us\",\n golf_elevation_unit=None,\n golf_speed_unit=None,\n external_bottom_time=None,\n ),\n user_sleep=UserSleep(\n sleep_time=80400,\n default_sleep_time=False,\n wake_time=24000,\n default_wake_time=False,\n ),\n connect_date=None,\n source_type=None,\n)\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Garmin SSO auth + Connect client",
"version": "0.4.46",
"project_urls": null,
"split_keywords": [
"garmin",
" garmin api",
" garmin connect",
" garmin sso"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f56e6007e33bbcbe4ea0912ffed3396ffb0e2e91f681a4271ac3be5359608932",
"md5": "cea42f6f8db536361eb638091beb3d67",
"sha256": "c209192bac793f42764f0f06131dc503f74783d41af326f29187a1f6394dc5ff"
},
"downloads": -1,
"filename": "garth-0.4.46-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cea42f6f8db536361eb638091beb3d67",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 23740,
"upload_time": "2024-05-18T23:10:56",
"upload_time_iso_8601": "2024-05-18T23:10:56.318170Z",
"url": "https://files.pythonhosted.org/packages/f5/6e/6007e33bbcbe4ea0912ffed3396ffb0e2e91f681a4271ac3be5359608932/garth-0.4.46-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c322d936e91a7f083b6340e5a06dc3d7f7f84d36edeb798f0664e48fbd3a1cef",
"md5": "101d0b471abdf6272afac308ece90d96",
"sha256": "5ae19e67612083285b10321b8e0e1f7c815a8f60f21e2f13be8c21a22e64d8eb"
},
"downloads": -1,
"filename": "garth-0.4.46.tar.gz",
"has_sig": false,
"md5_digest": "101d0b471abdf6272afac308ece90d96",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 187460,
"upload_time": "2024-05-18T23:10:59",
"upload_time_iso_8601": "2024-05-18T23:10:59.008836Z",
"url": "https://files.pythonhosted.org/packages/c3/22/d936e91a7f083b6340e5a06dc3d7f7f84d36edeb798f0664e48fbd3a1cef/garth-0.4.46.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-18 23:10:59",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "garth"
}
JSON