GARMIN INTERNATIONAL

Garmin Connect Developer

Program
Training API
Version 1.0.0
CONFIDENTIAL
Table of Contents
1. Revision History ........................................................................................................................................ 3
2. Getting Started .......................................................................................................................................... 4
2.1. Purpose of the API ..............................................................................................................................................4
2.2. Consumer Key and Secret ...................................................................................................................................4
2.3. User Registration .................................................................................................................................................5
2.4. Training API Import Types ..................................................................................................................................5
2.5. Requesting a Production Key ..............................................................................................................................5
2.6. API Rate Limiting or Excessive Usage ..................................................................................................................6
3. Training API Endpoint Details .................................................................................................................... 7
3.1. Training API Permissions .....................................................................................................................................7
3.2. Workouts.............................................................................................................................................................8
3.2.1. Field Definitions .............................................................................................................................................................. 8
3.2.2. Example JSON ............................................................................................................................................................... 11
3.2.3. Create............................................................................................................................................................................ 12
3.2.4. Retrieve ......................................................................................................................................................................... 13
3.2.5. Update .......................................................................................................................................................................... 13
3.2.6. Delete ............................................................................................................................................................................ 14
3.3. Workout Schedules ...........................................................................................................................................14
3.3.1. Field Definitions ............................................................................................................................................................ 14
3.3.2. Example JSON ............................................................................................................................................................... 14
3.3.3. Create............................................................................................................................................................................ 15
3.3.4. Retrieve ......................................................................................................................................................................... 15
3.3.5. Update .......................................................................................................................................................................... 15
3.3.6. Delete ............................................................................................................................................................................ 16
3.3.7. Retrieve by Date ........................................................................................................................................................... 16

2
Garmin International
1. Revision History

Version Date Revisions

1.0 12/01/2020 Initial revision

3
Garmin International
2. Getting Started
2.1. Purpose of the API

The Garmin Connect Training API is the underlying mechanism by which users can opt to import
workouts and workout schedules, regardless of activity type from third-party platforms into their
Garmin Connect account, making it easy to manage this type of information in a centralized location.

2.2. Consumer Key and Secret

Garmin Connect Training API partners will be provided with a consumer key and secret used to gain
access to the Training API. The consumer key is used to uniquely identify a partner and the consumer
secret is used to validate that the requests received are from that partner and not a third-party that has
gained unauthorized access to the consumer key. The consumer key can be considered public
information, but the consumer secret is private. For the security of users, the consumer secret should be
secured and never sent over a network in plain text. It is not permitted to embed the consumer secret
into consumer products like mobile apps.

Consumer key credentials are created using the Developer Portal and creating Apps
(https://developerportal.garmin.com/user/me/apps?program=829). Each app represents a unique
consumer key. Your first app will generate an evaluation-level consumer key that is rate limited.
Once your integration has been verified for production, subsequent apps will create consumer keys
with production-level access. Please see “Requesting a Production Key” below for more information.

Note:
Multiple consumer keys should be created to correspond to projects or implementations whose user
base is logically separated. A common scenario is for one partner to manage user data from multiple
other companies. A new key should be created and associated with each managed company so that
Garmin users can make an informed decision to consent to sharing their data with just that company.

4
Garmin International
 2.3. User Registration

Before a partner can write data to a user’s account, the user must grant the partner write access.
Please refer to the detailed Garmin OAuth documentation for details on acquiring, authorizing, and
signing with a User Access Token (UAT) to write data to a Garmin user’s account.

2.4. Training API Import Types

All data uploaded to Garmin Connect via the Training API can either be categorized as a workout or a
workout schedule. The API allows for the standard CRUD operations on these two data types.

• Workout
A workout contains a list of steps for the user to take as part of their workout, as well as
metadata about the workout (e.g. description, sport type, etc.).

• Workout Schedule
A workout schedule allows a previously defined workout to be scheduled for a
specified day.

2.5. Requesting a Production Key

The first consumer key generated through the Developer Portal is an evaluation key. This key is rate
limited and should only be used for testing, evaluation, and development. To receive production
level credentials, Garmin must review and approve the Training API integration to ensure a high-
quality user experience in Garmin Connect. Garmin also reserves the right to review partner
applications and/or websites to ensure proper usage of Garmin assets (e.g. device images) and
adherence to Garmin brand guidelines.

Please email Training API support at [email protected] to request and

schedule a production readiness review. Garmin will review the following technical aspects of the
integration:

• Authorization and correct use of UATs for at least two Garmin Connect users;
• No unnecessary or excessive API call utilization or volume;
• Proper handling of quota violations and subsequent retry attempts.

If the technical integration is not approved, any open issues must be corrected, and another review
will be required. Once the technical integration is approved, Garmin may conduct a user experience
review. This review can be achieved by application demonstration to Garmin via video conference or
other mutually agreed upon method. This review is used to confirm the following criteria are met:

• Proper representation of all Garmin trademarked/copyrighted terms;

• Proper representation Garmin products and product images; and
• User experience (UX) flow does not misrepresent Garmin or reflect Garmin poorly.

5
Garmin International
Once all reviews are approved, production credentials (consumer key and secret) may be requested
via the Garmin Connect Developer Portal.

2.6. API Rate Limiting or Excessive Usage

To manage capacity and ensure system stability, Garmin Training API implementations may be
subject to rate limiting. If any of the following limits are problematic for your implementation,
please contact [email protected] to discuss alternatives.

Please plan the implementation with the following limitations in mind:

Evaluation Rate Limits

• 100 API call requests per partner per minute - a rolling 60 second window summing the Oauth
requests and API calls.
• 200 API call requests per user per day - a rolling 24‐hour window excluding Oauth requests.

Production Rate limits

• 6000 API call requests per partner per minute - a rolling 60 second window summing the
Oauth requests and API calls.
• 6000 API call requests per user per day - a rolling 24‐hour window excluding Oauth requests.

If one or both of the above limits are exceeded by a partner or a specific user, the subsequent API
call request attempts will receive an HTTP Status Code 429 (too many requests). The call or calls in
question will need to be attempted again later.

6
Garmin International
3. Training API Endpoint Details

3.1. Training API Permissions

Consumer can have multiple permissions like “Activity Export” and “Workout Import” set up with GC.
User while signing up may only opt in for fewer permissions, so this endpoint helps in fetching the
permissions for that particular user.

Example response for this endpoint:

{[
"WORKOUT_IMPORT"
]}

Method & URL: GET https://apis.garmin.com/userPermissions/

Response body: The retrieved user permissions in JSON.

Response code:
HTTP Response Status Description

200 User Permissions retrieved

401 Unauthorized

429 Quota violation / rate‐limiting

The below section provides details for both the Workout and Workout Schedule endpoints.

7
Garmin International
 3.2. Workouts

3.2.1. Field Definitions

Workout Data Type Description

workoutId Long A unique identifier for the Workout. This field is not necessary for Create
action and will be set automatically.

ownerId Long A unique identifier for the owner of the Workout. This field is not
necessary for Create workouts, but necessary for update.

workoutName String The name of the Workout.

description String A description of the Workout with a maximum length of 1024

characters. Longer descriptions will be truncated.

updatedDate String A datetime representing the last update time of the Workout, formatted
as YYYY-mm-dd. Example: "2019-01-14T16:25:10.0”. This field is not
necessary for Create or Update actions and will be set automatically.

createdDate String A datetime representing the creation time of the Workout, formatted as
YYYY-mm-dd. Example: "2019-01-14T16:25:10.0”. This field is not
necessary for Create or Update actions and will be set automatically.

sport String The type of sport. Valid values: RUNNING, CYCLING, LAP_SWIMMING,
STRENGTH_TRAINING, CARDIO_TRAINING, GENERIC (supported by
limited devices) , YOGA, PILATES
estimatedDurationInSecs Integer The estimated duration of the Workout in seconds. This value is
calculated server-side and will be ignored in Create and Update actions.

estimatedDistanceInMeters Double The estimated distance of the Workout in meters. This value is
calculated server-side and will be ignored in Create and Update actions.

poolLength Double The length of the pool. Used only when sport = LAP_SWIMMING.

poolLengthUnit String The unit of the pool length. Valid values: YARD, METER. Used only if
poolLength is set.

workoutProvider String The workout provider to display to the user.

workoutSourceId String The workout provider to use for internal tracking purposes. This value
should be the same as workoutProvider unless otherwise noted.

8
Garmin International
steps List<Step> A list of Steps that specify the details of the workout.

WorkoutStep Data Type Description

type String The type of Step. Valid values are WorkoutStep and
WorkoutRepeatStep. WorkoutStep type Steps contains details of the
Step itself, while workoutRepeatSteps contain a sub-list of Steps that
should be repeated until a condition is met as specified in the
repeatType and repeatValue field.

stepId Long A unique ID is generated for the Step. This value is calculated server-
side and will be ignored in Create actions.

stepOrder Integer Represents the order of the Step.

repeatType String The type of the repeat action, specifying how long or until when the
user should repeat the sub-list of Steps. Used only for
WorkoutRepeatSteps. Valid values: REPEAT_UNTIL_STEPS_CMPLT,
REPEAT_UNTIL_TIME, REPEAT_UNTIL_DISTANCE,
REPEAT_UNTIL_CALORIES, REPEAT_UNTIL_HR_LESS_THAN,
REPEAT_UNTIL_HR_GREATER_THAN,
REPEAT_UNTIL_POWER_LESS_THAN,
REPEAT_UNTIL_POWER_GREATER_THAN,
REPEAT_UNTIL_POWER_LAST_LAP_LESS_THAN,
REPEAT_UNTIL_MAX_POWER_LAST_LAP_LESS_THAN

repeatValue Double The value of the repeat action. When paired with repeatType, specifies
how long or until when the user should repeat the sublist of steps. Used
only for WorkoutRepeatSteps.

steps List<Step> The list of steps that should be repeated as specified by repeatType and
repeatValue. Used only for WorkoutRepeatSteps.

intensity String The intensity of the Step. Valid values: REST, WARMUP, COOLDOWN,
RECOVERY, INTERVAL

description String A description of the Step with a maximum of 512 characters. Longer
descriptions will be truncated.

durationType String The type of duration. Paired with durationValue, this represents the
relative duration of the Step. Valid values: TIME, DISTANCE,
HR_LESS_THAN, HR_GREATER_THAN, CALORIES, OPEN,
POWER_LESS_THAN, POWER_GREATER_THAN, REPETITION_TIME,
REPS, TIME_AT_VALID_CDA, FIXED_REST
durationValue Double The duration value. Pair with durationType, this represents the relative
duration of the Step.

9
Garmin International
durationValueType String A modifier for duration value used only for HR and POWER types to
express units. Valid values: PERCENT, MILE, KILOMETER, METER, YARD

targetType String The type of target for this Step. Valid values: SPEED, HEART_RATE,
OPEN, CADENCE, POWER, GRADE, RESISTANCE, POWER_3S,
POWER_10S, POWER_30S, POWER_LAP, SWIM_STROKE, SPEED_LAP,
HEART_RATE_LAP, PACE (as speed in m/s)

targetValue Double The target HR or power zone to be used for this Step. Target zones must
have been previously defined and saved.

targetValueLow Double The lowest value for the target range. Used to specify a custom range
instead of specifying a target zone through targetValue.

targetValueHigh Double The highest value for the target range. Used to specify a custom range
instead of specifying a target zone through targetValue.

targetValueType String A modifier for target value used only for HR and POWER types to
express units. Valid values: PERCENT, MILE, KILOMETER, METER, YARD

strokeType String The type of stroke for this Step. Used only in LAP_SWIMMING
Workouts. Valid values: BACKSTROKE, BREASTSTROKE, DRILL,
BUTTERFLY, FREESTYLE, MIXED, IM

equipmentType String
The type of equipment needed for this Step. Currently used only for
LAP_SWIMMING Workouts. Valid values: NONE, SWIM_FINS,
SWIM_KICKBOARD, SWIM_PADDLES, SWIM_PULL_BUOY,
SWIM_SNORKEL
exerciseCategory String The exercise category for this Step. Used only for STRENGTH_TRAINING
and CARDIO_TRAINING Workouts. Valid values: BENCH_PRESS,
CALF_RAISE, CARDIO, CARRY, CHOP, CORE, CRUNCH, CURL , DEADLIFT,
FLYE, HIP_RAISE, HIP_STABILITY, HIP_SWING, HYPEREXTENSION,
LATERAL_RAISE, LEG_CURL, LEG_RAISE, LUNGE, OLYMPIC_LIFT, PLANK,
PLYO, PULL_UP, PUSH_UP, ROW, SHOULDER_PRESS,
SHOULDER_STABILITY, SHRUG, SIT_UP, SQUAT, TOTAL_BODY ,
TRICEPS_EXTENSION, WARM_UP, RUN, BIKE, CARDIO_SENSORS,
UNKNOWN, INVALID
exerciseName String The exercise name for this Step. Used only for STRENGTH_TRAINING
and CARDIO_TRAINING Workouts.

weightValue Double The weight value for this Step in kilograms. Used only for
STRENGTH_TRAINING Workouts.

weightDisplayUnit String The units in which to display the weightValue to the user, if a
weightValue exists. The display unit does not impact weightValue within
the Training API, only for display. Valid values: OTHER, KILOGRAM,
POUND

10
Garmin International
3.2.2. Example JSON

The following is an example of a Workout in JSON.

{
"workoutId": 2201,
"ownerId": 232,
"workoutName": "Bike Workout",
"description": null,
"updatedDate": "2018-10-23T21:17:53.0",
"createdDate": "2018-10-23T21:17:53.0",
"sport": "CYCLING",
"estimatedDurationInSecs": null,
"estimatedDistanceInMeters": null,
"poolLength": null,
"poolLengthUnit": null,
"workoutProvider": null,
"workoutSourceId": null,
"steps": [
{
"type": "WorkoutStep",
"stepId": 1475,
"stepOrder": 1,
"intensity": "WARMUP",
"description": null,
"durationType": "CALORIES",
"durationValue": 2,
"durationValueType": null,
"targetType": "OPEN",
"targetValue": null,
"targetValueLow": null,
"targetValueHigh": null,
"targetValueType": null,
"strokeType": null,
"equipmentType": null,
"exerciseCategory": null,
"exerciseName": null,
"weightValue": null,
"weightDisplayUnit": null
},
{
"type": "WorkoutRepeatStep",
"stepId": 1476,
"stepOrder": 2,
"repeatType": null,
"repeatValue": null,
"steps": [
{

11
Garmin International
 "type": "WorkoutStep",
"stepId": 1477,
"stepOrder": 5,
"intensity": "ACTIVE",
"description": null,
"durationType": "TIME",
"durationValue": 120,
"durationValueType": null,
"targetType": "POWER",
"targetValue": 1,
"targetValueLow": null,
"targetValueHigh": null,
"targetValueType": null,
"strokeType": null,
"equipmentType": null,
"exerciseCategory": null,
"exerciseName": null,
"weightValue": null,
"weightDisplayUnit": null
},
{
"type": "WorkoutStep",
"stepId": 1478,
"stepOrder": 6,
"intensity": "ACTIVE",
"description": null,
"durationType": "DISTANCE",
"durationValue": 32186.880859,
"durationValueType": "MILE",
"targetType": "OPEN",
"targetValue": null,
"targetValueLow": null,
"targetValueHigh": null,
"targetValueType": null,
"strokeType": null,
"equipmentType": null,
"exerciseCategory": null,
"exerciseName": null,
"weightValue": null,
"weightDisplayUnit": null
}
]
}
]
}

3.2.3. Create

This request is to create a workout by/for a user:

12
Garmin International
Method & URL: POST https://apis.garmin.com/training-api/workout/
Request body: The new workout in JSON. A workout ID should not be included.
Content-Type: application/json
Response Body: The newly-created workout as JSON.

Response code:
HTTP Response Status Description

200 Workout successfully created

401 User Access Token doesn’t exist

412 User Permission error

429 Quota violation / rate‐limiting

3.2.4. Retrieve

This request is to retrieve a workout by/for a user:

Method & URL: GET https://apis.garmin.com/training-api/workout/{workoutId}
Response body: The retrieved workout in JSON.

Response code:
HTTP Response Status Description

200 Workout successfully retrieved

401 User Access Token doesn’t exist

412 User permission error

429 Quota violation / rate‐limiting

3.2.5. Update

This request is to update a workout by/for a user:

Method & URL: PUT https://apis.garmin.com/training-api/workout/{workoutId}
Request body: The full updated workout in JSON.
Content-Type: application/json

Response code:
HTTP Response Status Description

204 Workout successfully updated

401 User Access Token doesn’t exist

13
Garmin International
 404 Not found

412 User permission error

429 Quota violation / rate‐limiting

3.2.6. Delete

This request is to delete a workout by/for a user:

Method & URL: DELETE https://apis.garmin.com/training-api/workout/{workoutId}

Response code:
HTTP Response Status Description

200 Workout successfully deleted

401 User Access Token doesn’t exist

412 User permission error

429 Quota violation / rate‐limiting

3.3. Workout Schedules

3.3.1. Field Definitions

Field Name Description

scheduleId A unique identifier for the workout schedule

workoutId The ID of the workout to which the schedules refers

date The scheduled date, formatted as ‘YYYY-mm-dd

3.3.2. Example JSON

{
"scheduleId":123,
"workoutId":123,
"date":"2019-01-31"
}

14
Garmin International
3.3.3. Create

This request is to create a workout schedule by/for a user:

Method & URL: POST https://apis.garmin.com/training-api/schedule/
Request body: A workout schedule to create. A schedule Id should not be included.
Content-Type: application/json

Response code:
HTTP Response Status Description

200 Workout schedule successfully created/added

401 User Access Token doesn’t exist

412 User permission error

429 Quota violation / rate‐limiting

3.3.4. Retrieve

This request is to retrieve a workout schedule by/for a user:

Method & URL:
GET https://apis.garmin.com/training-api/schedule/{workoutScheduleId}
Response body: The retrieved workout schedule.

Response code:
HTTP Response Status Description

200 Workout schedule successfully retrieved

401 User Access Token doesn’t exist

412 User permission error

429 Quota violation / rate‐limiting

3.3.5. Update

This request is to update a workout schedule by/for a user:

Method & URL:
PUT https://apis.garmin.com/training-api/schedule/{workoutScheduleId}
Request body: The full workout schedule in JSON.
Content-Type: application/json
Response body: The updated workout schedule.

15
Garmin International
Response code:
HTTP Response Status Description

204 Workout schedule successfully updated

401 User Access Token doesn’t exist

412 User permission error

429 Quota violation / rate‐limiting

3.3.6. Delete

This request is to delete a workout schedule by/for a user:

Method & URL:
DELETE https://apis.garmin.com/training-api/schedule/{workoutScheduleId}

Response code:
HTTP Response Status Description

200 Workout schedule successfully deleted

401 User Access Token doesn’t exist

412 User permission error

429 Quota violation / rate‐limiting

3.3.7. Retrieve by Date

This request is used to retrieve workout schedule by/for a user by date range:
Method & URL: GET https://apis.garmin.com/training-api/schedule?startDate=YYYY-mm-
dd&endDate=YYYY-mm-dd
Response Body: An array of workout schedules as JSON.

Response:
HTTP Response Status Description

200 Workout schedule successfully retrieved for the date

range specified

401 User Access Token doesn’t exist

412 User permission error

429 Quota violation / rate‐limiting

16
Garmin International