Golf

Scorecards, shot data, club and player stats.

Every method below hangs off a Garmin instance. See Installation & setup for how to construct one:

import { GarminClient, Garmin, FileTokenStore } from "garminconnect-js";

const client = new GarminClient({ tokenStore: new FileTokenStore("./tokens") });
if (!(await client.loadTokens())) throw new Error("not connected to Garmin");
const garmin = new Garmin(client);

5 methods. The verification column says what has been confirmed against a live Garmin account, not merely unit-tested — AGENTS.md carries the full evidence per method.

getGolfClubStats

garmin.getGolfClubStats(limit?: number): Promise<GolfClubStats[] | null>

const result = await garmin.getGolfClubStats();

Returns

An array of GolfClubStats — an object whose fields this library does not model. Garmin's response is passed through unparsed, so read one to see what you get, or use a Record<string, unknown> and narrow it yourself.

defaults limit=1000; validated positive; GETs /gcs-golfcommunity/api/v2/club/player; hyphenated query params per-page and include-stats (literal "true"). An ARRAY, verified live — the test account returned a JSON ARRAY of 17 club entries ({id, clubTypeId, shaftLength, flexTypeId, averageDistance, adviceDistance, retired, deleted, lastModifiedTime}), not a single object

Verification: live-verified

getGolfScorecard

garmin.getGolfScorecard(scorecardId: number | string): Promise<GolfScorecardDetail | null>

const result = await garmin.getGolfScorecard(activityId);

Returns

GolfScorecardDetail — an object whose fields this library does not model. Garmin's response is passed through unparsed, so read one to see what you get, or use a Record<string, unknown> and narrow it yourself.

GETs /gcs-golfcommunity/api/v2/scorecard/detail; hyphenated query params scorecard-ids and include-longest-shot-distance (sent as the literal string "true"); passes through unchecked

Verification: attempted, unconfirmed

getGolfShotData

garmin.getGolfShotData(scorecardId: number | string, holeNumbers?: string): Promise<GolfShotData | null>

const result = await garmin.getGolfShotData(activityId);

Returns

GolfShotData — an object whose fields this library does not model. Garmin's response is passed through unparsed, so read one to see what you get, or use a Record<string, unknown> and narrow it yourself.

GETs /gcs-golfcommunity/api/v2/shot/scorecard/{scorecardId}/hole; holeNumbers accepts commas or hyphens as separators (spaces stripped), re-joined with - before sending as the hyphenated hole-numbers param; if any requested hole number is >9, the filter is silently dropped and all 18 holes are requested instead (Garmin's endpoint drops double-digit hole numbers from a filtered query); omitting holeNumbers also fetches all 18; passes through unchecked

Verification: attempted, unconfirmed

getGolfSummary

garmin.getGolfSummary(start?: number, limit?: number): Promise<GolfScorecardSummary | null>

const result = await garmin.getGolfSummary();

Returns

GolfScorecardSummary — an object whose fields this library does not model. Garmin's response is passed through unparsed, so read one to see what you get, or use a Record<string, unknown> and narrow it yourself.

defaults start=0, limit=100; start validated non-negative, limit validated positive (throws GarminError otherwise); query params are literally hyphenated (per-page, start), matching Garmin's own naming. An OBJECT, not an array, verified live — the test account (0 rounds recorded) returned a single pagination-envelope OBJECT {pageNumber, rowsPerPage, totalRows}, not an array

Verification: live-verified

getGolfUserStats

garmin.getGolfUserStats(): Promise<GolfUserStats | null>

const result = await garmin.getGolfUserStats();

Returns

GolfUserStats — an object whose fields this library does not model. Garmin's response is passed through unparsed, so read one to see what you get, or use a Record<string, unknown> and narrow it yourself.

GETs /gcs-golfcommunity/api/v2/player/stats; handicap and strokes-gained overview, no params; passes through unchecked

Verification: live-verified