garmin-personal

n8n node for the Garmin Connect Personal API: sleep, HRV, heart rate, Body Battery, stress, steps, activities and a last-24-hours health summary

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.2.0
Author: gaetanclaeys

Documentation

n8n-nodes-garmin-personal

n8n community node that reads your own health and fitness data from the official
Garmin Connect Personal API.

Each person uses their own Personal API key, so friends can install the same node in
their own n8n and connect their own watch.

Operations

The node works like n8n's built-in nodes (Gmail, Google Sheets…): pick a Resource, then an
Operation.

Resource Operations
Health Summary (Last 24h) Get Last 24 Hours: one item with every dataset you tick in Datasets, plus activities started in the window
Sleep Get (one night), Get Many (date range), Get Summaries
Heart Rate, HRV, Body Battery, Stress, Steps, Pulse Ox (SpO2), Hydration, Weight, VO2 Max, Fitness Age, Daily Summary, Food Log, Menstrual Cycle, Wellness Activity Get (one day), Get Many (date range, max 31 days, one item per day where Garmin stores data per day)
Activity Get, Get Many (date range, Return All / Limit), Get Workouts
User Get Profile Settings, Get Heart Rate Zones

Simplify (on by default, like the Gmail node): returns the essential values with readable
names and units, e.g. sleep.duration: "7h 40m", sleep.score: 84, hrv.lastNightAvg: 39,
dailySummary[].steps, activities[].avgPacePerKm: "5:15". Turn it off to get the raw Garmin
response.

Every operation has Options:

  • Fields to Return: comma-separated fields to keep, with dots for nested fields, e.g.
    calendarDate, dailySleepDTO.sleepTimeSeconds. Leave empty to get everything. Run the node
    once without it to see the available field names.
  • Include Time Series: off by default. Detailed arrays such as heart rate every few
    minutes are removed to keep the output small.

Notes on "last 24 hours": Garmin stores most data per calendar day, so the node fetches the
calendar days touched by the window (yesterday and today, in the workflow's timezone).
Sleep, HRV, SpO2 and fitness age come from today (last night). Heart rate is returned for
both days. Activities are filtered to those that started in the last 24 hours.

If one dataset fails (for example a feature your watch doesn't support), the summary still
returns the others and lists the failure under errors. If every dataset fails, the node fails.

1. Create your Garmin Personal API key

  1. Log in to Garmin Connect in a browser.
  2. Open the Personal API Key page, select Create Key, accept the terms and pick an
    expiration (30 days to 1 year).
  3. Copy the key immediately. Garmin shows it only once.

Garmin emails you about a week before the key expires. Create a new key and paste it into
the n8n credential.

2. Install the node in self-hosted n8n

From npm (once published)

In n8n: Settings → Community Nodes → Install, enter n8n-nodes-garmin-personal.

From a local build (before publishing)

npm install
npm run build
npm pack                        # creates n8n-nodes-garmin-personal-<version>.tgz

n8n installed with npm:

mkdir -p ~/.n8n/nodes && cd ~/.n8n/nodes
npm install /path/to/n8n-nodes-garmin-personal-<version>.tgz
# restart n8n

n8n in Docker (with the usual /home/node/.n8n volume):

docker cp n8n-nodes-garmin-personal-<version>.tgz <container>:/tmp/
docker exec -it <container> sh -c "mkdir -p /home/node/.n8n/nodes && cd /home/node/.n8n/nodes && npm install /tmp/n8n-nodes-garmin-personal-<version>.tgz"
docker restart <container>

Try it without touching your n8n

npm run dev    # starts a local n8n at http://localhost:5678 with this node loaded

3. Add the credential

In n8n: Credentials → Add credential → Garmin Connect Personal API, paste the API key and
save. n8n tests the key by reading your profile settings.

The node exchanges the key for an access token (valid 24 hours) and stores the token in the
credential. When Garmin answers 401, n8n fetches a new token and retries automatically.

Timezone

The node decides what "today" and "yesterday" mean using the workflow timezone. Set it in
Workflow settings → Timezone, or for the whole instance with the GENERIC_TIMEZONE
environment variable (on Cloudron: add export GENERIC_TIMEZONE=Europe/Brussels to
/app/data/env.sh and restart the app). The example workflows use Europe/Brussels.

4. Daily email report (Gmail)

examples/garmin-daily-report.workflow.json is a ready-made workflow:

Schedule (07:00) → Garmin: last 24 hours → Build report (Code) → Send with Gmail

  1. In n8n: Workflows → Import from File and pick the JSON file.
  2. Select your Garmin credential on the Garmin node.
  3. On the Gmail node, create a Gmail OAuth2 credential (n8n guides you through Google sign-in)
    and replace you@example.com with your address.
  4. Run it once manually, check the email, then activate the workflow.

The report (in French) uses the simplified output: last night's sleep and HRV, yesterday's full
day (steps, calories, resting heart rate, stress, Body Battery…), activities of the last 24 hours,
VO2 Max and fitness age. Values your watch doesn't record show "n/a".

Sharing with friends

Each friend creates their own Personal API key and installs the node in their own n8n. Garmin
intends the Personal API for people accessing their own data, not for one app serving many
users. For that, see the roadmap.

Roadmap

  • Garmin Connect Developer Program (multi-user OAuth). Add a second credential type
    (garminOAuth2Api) and an "Authentication" option on the node, so existing workflows keep
    working. This requires Garmin's approval. Its Health API mostly pushes data to a webhook,
    so it will likely also need a trigger node.

Development

npm run build    # compile to dist/
npm run lint     # n8n community node linter
npm run dev      # local n8n with hot reload

Endpoints follow Garmin's reference client:
garmin/connect-personal-api-python.

License

MIT

Discussion