Python Garmin数据库详解

python-garminconnect 是一个开源 Python 库，允许开发者在没有官方 API 的情况下，通过模拟登录与 Garmin Connect 云端交互。它能自动化获取运动轨迹、心率、睡眠等健康数据，并支持 .fit 文件批量下载与上传。该工具是个人数据分析和量化自我的利器，但作为非官方逆向工程项目，用户需留意 Cloudflare 拦截、接口变更风险及中国区账号的兼容性问题。

python-garminconnect 是一个非常流行的开源 Python 库，用于与 Garmin Connect（佳明）的云端服务进行交互。

简单来说，它允许你通过 Python 代码自动登录 Garmin Connect 账户，获取你的运动数据（跑步、骑行等）、健康数据（心率、睡眠、步数），甚至上传新的活动文件。

由于 Garmin 没有面向普通开发者的免费官方开放 API（官方 API 仅向企业合作伙伴开放，且申请门槛极高），这个库通过模拟浏览器行为（API 逆向工程）来实现数据访问，是个人开发者进行数据分析或自动化的首选工具。

1. 主要功能

这个库的功能非常丰富，几乎涵盖了你在网页版 Garmin Connect 上能看到的所有数据：

身份验证： 支持账号密码登录，能够处理部分 MFA（多因素认证）情况。
获取活动数据： 下载特定活动的详细信息、GPS 轨迹、甚至原始的 .fit 或 .tcx 文件。
获取健康监测： 读取每日步数、静息心率、睡眠阶段分析、压力水平、身体电量（Body Battery）等。
设备管理： 查看已连接的设备列表、闹钟设置等。
数据上传： 支持自动上传 .fit 文件（例如从 Zwift 或其他平台导出的数据）。

2. 安装与配置

该库托管在 PyPI 上，可以通过 pip 直接安装。建议使用 Python 3.6+ 版本。

pip install garminconnect

3. 基础使用示例

以下是一个最简单的代码示例，演示如何登录并获取今天的步数数据：

from garminconnect import Garmin
from datetime import date

# 1. 配置账号信息
email = "[email protected]"
password = "YOUR_PASSWORD"

try:
    # 2. 初始化并登录
    # Garmin 类会自动处理 Cookie 和 Session
    client = Garmin(email, password)
    client.login()
    
    # 3. 获取数据
    today = date.today()
    
    # 获取今日的健康统计概览
    stats = client.get_stats(today.isoformat())
    
    # 获取今日步数
    steps = client.get_steps_data(today.isoformat())
    
    print(f"今日总步数: {steps['sum']}")
    print("----------------------------")
    print(f"今日摘要: {stats}")

except Exception as e:
    print(f"发生错误: {e}")

4. 常见的高级用法

除了查看步数，大多数开发者使用它来做以下两件事：

A. 批量下载活动 (Backup/Analysis)

你可以获取历史活动列表，并下载原始文件用于本地分析。

# 获取最近的 10 个活动
activities = client.get_activities(0, 10) # (start, limit)

for activity in activities:
    activity_id = activity["activityId"]
    name = activity["activityName"]
    print(f"正在下载: {name} ({activity_id})")
    
    # 下载原始 ZIP 格式的 FIT 文件
    data = client.download_activity(activity_id, dl_fmt=client.ActivityDownloadFormat.ORIGINAL)
    
    with open(f"./{activity_id}.zip", "wb") as fb:
        fb.write(data)

B. 获取详细的健康指标 (Bio-hacking)

如果你对量化自我（Quantified Self）感兴趣，可以提取极细颗粒度的数据：

get_heart_rates(date): 获取全天心率数据。
get_sleep_data(date): 获取睡眠深浅、REM 周期。
get_body_battery(date): 获取身体电量变化。

5. ⚠️ 重要注意事项与局限性

在使用此库时，必须了解以下风险和限制：

非官方 API (Unofficial):
这是一个第三方逆向工程库，Garmin 官方并不支持它。
如果 Garmin 更改了后端接口或网页结构，代码可能会随时失效。你需要经常关注库的更新（pip install --upgrade garminconnect）。
Cloudflare 拦截:
Garmin 使用 Cloudflare 来防止机器人爬虫。这经常导致 403 Forbidden 错误。
该库的维护者通常会通过更新 garth（底层的认证模块）来绕过此限制，但有时连接会很不稳定。
封号风险:
虽然罕见，但通过脚本高频请求服务器可能会触发风控。建议在循环请求中加入 time.sleep() 延时，不要对服务器发起 DDoS 级别的请求。
中国区账号问题:
Garmin 的服务器分为国际区（Global）和中国区（CN）。
该库主要针对国际区优化。如果你使用的是 Garmin.cn 账号，可能需要在初始化时指定区域参数（如果库支持）或遇到登录困难。通常建议迁移到国际区账号以获得更好的 API 支持。

总结

python-garminconnect 是目前 Python 生态中连接 Garmin 数据最强大的工具。它非常适合用来制作个人的运动仪表盘、将数据同步到 Notion/Excel，或者进行长期的健康趋势分析。

*如有疏漏，欢迎指正。

欢迎访问>>小札在线<<讨论或在下方留言区分享你的看法或经验！

<-本篇完->