Garmin API

[mojtaba]

In this section, we list the comprehensive range of Garmin metrics integrated with Avicenna through the Garmin API.

Supported Garmin API Metrics in Avicenna

Garmin Health Daily

Download Sample Data

Provides a high-level snapshot of a user’s health information throughout a single day. This corresponds to the information in Garmin Connect’s “My Day” section. It is stored internally as garmin_health_daily, and includes the following fields:

• Date: The user’s local calendar date to which the health information belongs. Internally stored as date.

• Start Time: Start time of the period. Internally stored as start_time.

• Duration: Length of the day the data is collected. 86400 if a full day is collected, or less if the user syncs mid-day. Internally stored as duration_sec.

• Steps: Count of steps recorded during the monitoring period. Internally stored as steps.

• Distance: Distance traveled in meters. Internally stored as distance_meter.

• Active Time: The time (in seconds) during which the device wearer was considered active during the monitoring period. This is based on internal heuristics in each device. Internally stored as active_time_sec.

• Active Kilocalories: Active Kilocalories (dietary calories) burned through actual movement and activity during the monitoring period. Internally stored as active_kilocalories.

• BMR Kilocalories: BMR Kilocalories burned by the existing Basal Metabolic Rate (calculated based on the user’s height, weight, age, and other demographic data). Internally stored as bmr_kilocalories.

• Consumed Calories: The number of calories consumed by the user through food for that day (value subtracted from calorie goal). This value is received from MyFitnessPal and is not entered within Connect. Internally stored as consumed_calories.

• Moderate Intensity Duration: Cumulative duration of moderate-intensity activities that last at least 600 seconds at a time. An activity of moderate intensity is defined as one having a MET value between 3-6. Internally stored as moderate_intensity_duration_sec.

• Vigorous Intensity Duration: The total duration of vigorous-intensity exercises that last at least 600 seconds at a time. An activity with a MET value greater than 6 is considered vigorous. Internally stored as vigorous_intensity_duration_sec.

• Floors Climbed: The number of floors climbed during the monitoring period. Internally stored as floors_climbed.

• Min Heart Rate: Minimum heart rate value captured during the monitoring period, in beats per minute. Internally stored as min_heart_rate.

• Average Heart Rate: Average heart rate value captured during the last 7 days, in beats per minute. Internally stored as average_heart_rate.

• Max Heart Rate: Maximum heart rate value captured during the monitoring period, in beats per minute. Internally stored as max_heart_rate.

• Resting Heart Rate: Average heart rate at rest during the monitoring period, in beats per minute. Internally stored as resting_heart_rate.

• Average Stress Level: An abstraction of the user’s average stress level throughout the monitoring period, on a scale of 1 to 100, or -1 if there is insufficient data to calculate average stress. Rest (i.e., not stressful) is a score of 1 to 25, low stress is a score of 26-50, medium stress is 51-75, and high stress is a score of 76-100. Internally stored as average_stress_level.

• Max Stress Level: The highest stress level measurement taken during this monitoring period. Internally stored as max_stress_level.

• Stress Duration: The number of seconds during this monitoring period when stress levels were in the stressful range (26-100). Internally stored as stress_duration.

• Rest Stress Duration: The number of seconds during this monitoring period during which stress levels were in the restful range (1 to 25). Internally stored as rest_stress_duration.

• Activity Stress Duration: The number of seconds in this monitoring period where the user was engaged in physical activity, and so stress measurement was unreliable. All durations in this monitoring period not covered by stress, rest, and activity stress should be considered Uncategorized, either because the device was not worn or because not enough data could be taken to generate a stress score. Internally stored as activity_stress_duration.

• Low-Stress Duration: The portion of the user’s stress duration where the measured stress score was in the low range (26-50). Internally stored as low_stress_duration.

• Medium-Stress Duration: The portion of the user’s stress duration where the measured stress score was in the medium range (51-75). Internally stored as medium_stress_duration.

• High-Stress Duration: The portion of the user’s stress duration where the measured stress score was in the high range (76-100). Internally stored as high_stress_duration.

• Stress Qualifier: A qualitative label applied based on all stress measurements in this monitoring period. Possible values: unknown, calm, balanced, stressful, very_stressful, calm_awake, balanced_awake, stressful_awake, very_stressful_awake. This matches what the user will see in Garmin Connect. Internally stored as stress_qualifier.

• Steps Goal: The user’s steps goal for this monitoring period. Internally stored as steps_goal.

• Net Kilocalories Goal: The user’s goal for net caloric intake (consumed calories minus active calories) for this monitoring period. This field is related to integration with MyFitnessPal and may not be present for many users. Internally stored as net_kilocalories_goal.

• Intensity Duration Goal: The user’s goal for consecutive seconds of moderate to vigorous-intensity activity for this monitoring period. Internally stored as intensity_duration_goal.

• Floors Climbed Goal: The user’s goal for floors climbed in this monitoring period. Internally stored as floors_climbed_goal.

Garmin Health

Download Sample Data

Garmin Health records are provided with 15-minute time slice granularity. Each activity type monitored within a single time slice has its own record. For example, if the user sat for five minutes, walked for five minutes, and then ran for five minutes during the period of 15 minutes, three activity records would be generated for that single 15-minute time slice. The duration value would be 900 seconds for all three records, but the active time for each would be 300 seconds. A duration of less than 900 seconds indicates that the user synced data during the middle of a time slice. On the user’s next sync, that time slice record will be replaced with a 900-second-duration epoch covering the entire span. It is stored internally as garmin_health, and includes the following fields:

• Activity Type: Sedentary when having a heart rate of less than 90 bpm, Generic when greater than 90 bpm but no movement is recorded. Walking when heart rate is greater than 90 bpm and movement is recorded. Internally stored as activity_type_id.

• Start Time: Start time of the monitoring period. Internally stored as record_time.

• Start Time Offset: Offset in seconds to add to Start Time to derive the local time of the device. Internally stored as start_time_offset_sec.

• Duration: Length of the monitoring period in seconds. Internally stored as duration_sec.

• Active Time: The portion of the monitoring period (in seconds) in which the device wearer was active for this activity type. The sum of active times of all epochs of the same start time (and different activity types) should be equal to the duration. Internally stored as active_time_sec.

• Steps: Count of steps recorded during the monitoring period. Internally stored as steps.

• Distance: Distance traveled in meters. Internally stored as distance_meter.

• Active Kilocalories: Active kilocalories (dietary calories) burned during the monitoring period. This includes only the calories burned by the activity and not calories burned as part of the basal metabolic rate (BMR). Internally stored as active_kilocalories.

• MET: MET (Metabolic Equivalent of Task) value for the active time for this activity type. Metabolic Equivalent of Task (MET) is an official measure of activity intensity. Garmin’s calculation of MET is an estimation based on the biometric data provided (height, weight, date of birth, gender) and improves in accuracy if heart rate data is also captured. Please refer to MET and physical activity intensity. for more detailed information. Internally stored as met.

• Motion Intensity: A Qualitative measure of intensity. Motion Intensity is a numerical abstraction of low-level accelerometer data, provided for use in further analysis. Motion Intensity is calculated at minute-level granularity as a number between 0 and 7, with 0 being absolutely still and 7 being constant, sharp motion. Unlike steps, distance, or activity type, which take net movement into account, motion intensity will increase even if the user does not move in space. For instance, if a user were to jump up and down or fidget with a pencil they would not get credit for any distance, but their motion intensity scores for that monitoring period would increase. It is very common to see mid-range max motion intensities even for sedentary epochs as most people do not sit absolutely still. Internally stored as intensity_type_id.

• Mean Motion Intensity: The average motion intensity scores for all minutes in this monitoring period. Internally stored as mean_motion_intesity.

• Max Motion Intensity: The largest motion intensity score of any minute in this monitoring period. Internally stored as max_motion_intesity.

Garmin Health Heart

It is internally stored as heart_rate. Each Garmin Health Heart record includes the following:

• Heart Rate: Representative heart rate value recorded for the previous 15 seconds from record time, in beats per minute. Lack of entry for a given offset should be interpreted as no data available. Internally stored as bpm.

Garmin Health Sleep Daily

It is internally stored as garmin_health_sleep_daily. Each Garmin Health Sleep Daily record includes the following:

• Date: The user’s local calendar date to which health information belongs. Internally stored as date.

• Start Time: Start time of the period. Internally stored as start_time.

• Duration: Length of the monitoring period in seconds. Internally stored as duration.

• Unmeasurable Sleep: Time in seconds that the sleep level of the user could not be measured. This may or may not correspond to off-wrist time. Internally stored as unmeasurable_sleep.

• Deep Sleep Duration: Time in seconds the user spent in deep sleep during the sleep period. Internally stored as deep_sleep_duration.

• Light Sleep Duration: Time in seconds the user spent in light sleep during the sleep period. Internally stored as light_sleep_duration.

• REM Sleep: Time in seconds the user spent in REM sleep during the sleep period. Internally stored as rem_sleep.

• Awake Duration: Time in seconds the user spent awake during the sleep period. Internally stored as awake_duration.

• Validation: Validation state of the sleep data and its date range. The data could be auto-confirmed, but the sleep window could have been manually adjusted, or the sleep data itself is entirely manually entered. Values: MANUAL, DEVICE, AUTO_TENTATIVE, AUTO_FINAL, AUTO_MANUAL, ENHANCED_TENTATIVE, ENHANCED_FINAL. Internally stored as validation.

Garmin Health Sleep

Download Sample Data

It is internally stored as garmin_health_sleep. Each Garmin Health Sleep record includes the following:

• Start Time: Start time of the period. Internally stored as start_time.

• End Time: End time of the period. Internally stored as end_time.

• Sleep Level: One of Deep, Light, and Awake. Internally stored as sleep_level.

Garmin Health Body Composition

It is internally stored as garmin_health_body_composition. Each Garmin Health Body Composition record includes the following:

• Muscle Mass: Muscle mass in grams. Internally stored as muscle_mass.

• Bone Mass: Bone mass in grams. Internally stored as bone_mass.

• Body Water: Percentage of body water (range 0.0 - 100.0). Internally stored as body_water.

• Body Fat: Percentage of body fat. (range 0.0 - 100.0). Internally stored as body_fat.

• Body Mass Index: Body mass index, or BMI. Internally stored as body_mass_index.

• Weight: Weight in grams. Internally stored as weight.

Garmin Health Stress

Download Sample Data

It is internally stored as garmin_health_stress. Each Garmin Health Stress record includes the following:

• Stress Level: Stress level value recorded. Internally stored as stress_level.

• Body Battery Level: Body battery level value recorded. Information on and a list of devices that support Body Battery is available here. Internally stored as body_battery_level.

Garmin Health User Metrics

It is internally stored as garmin_health_user_metrics. Each Garmin Health User Metrics record includes the following:

• Date: The user’s local calendar date to which health information belongs. Internally stored as date.

• Vo2 Max: An estimate of the maximum volume of oxygen (in milliliters) the user can consume per minute per kilogram of body weight at maximum performance. Internally stored as vo2_max.

• Fitness Age: An estimation of the ‘age’ of the user’s fitness level, calculated by comparing internal fitness metrics with the average readings of biometrically similar users by age. For instance, a fitness age of 48 indicates that the user’s physical fitness is similar to that of an average 48- year-old person of the same gender. Internally stored as fitness_age.

Garmin Health Pulse Ox

Download Sample Data

It is internally stored as garmin_health_pulse_ox. Each Garmin Health Pulse Ox record includes the following:

• SpO2: SpO2 measurement taken at record time (1 sample/minute). Internally stored as spo2.

• On Demand: A Boolean to show whether this pulse ox summary represents an on-demand reading or an averaged acclimation reading. Internally stored as on_demand.

Garmin Health Respiration

It is internally stored as garmin_health_respiration. Each Garmin Health Respiration record includes the following:

• Breaths: Respiration measurement taken at record time, in breaths per minute. Internally stored as breaths.

Data Collection Behavior

Whenever there is new data, Garmin’s server will send the new data to Avicenna.

Adding Garmin API Metrics as Data Sources

See Accessing Data Sources.

Monitoring and Exporting Garmin API Metrics Data

You can monitor and export Garmin API metrics data using Kibana.

Garmin API Data Sources in Participant Device

To collect data through the API integration method, you need to set up both Garmin Connect and grant access in the Avicenna app. Here’s the complete setup process:

1. Install and Set Up Garmin Connect

1. Install Garmin Connect:

   • Download and install the Garmin Connect app from your device’s app store.

   • Create a Garmin account if you don’t have one already.

2. Pair your device:

   • Open the Garmin Connect app.

   • Follow the on-screen instructions to pair your Garmin wearable.

   • Ensure your device is properly connected and syncing data.

3. Regular syncing:

   • Keep the Garmin Connect app installed and running.

   • Regularly sync your device to ensure data is uploaded to Garmin’s servers.

   • Avicenna can only access data that has been synced to Garmin’s servers.

[!note]
The Garmin Connect app must remain installed, and your device must stay paired with it throughout the study. If the app is uninstalled or your device is unpaired, data collection will stop until the connection is restored.

2. Grant Access in the Avicenna App

After setting up Garmin Connect, you need to grant Avicenna access to your Garmin data. Here’s how:

1. Open the Avicenna app and go to Settings.

   

2. Click on My Studies and choose the study you are participating in.

   
   

3. Tap on Data Sources from the bottom-right to see all data sources being collected.

   

4. Find the Garmin data source(s) in the list. As shown below, this study is collecting Garmin Health Respiration. Press Grant Access and enter your Garmin account email and password. If you don’t have an account, you can create one at Garmin’s website.

   
   

5. After signing in, review what information will be shared with Avicenna and what Avicenna will share with your Garmin Connect account. If everything looks good, press Save

   

6. Click on Agree to allow sharing information with Avicenna.

   

7. You’ll be redirected back to the Data Sources page. To stop sharing data at any time, simply tap on REVOKE ACCESS.