Garmin SDK

Reference
1

In this section, we list the comprehensive range of Garmin SDK metrics that Avicenna supports.

Supported Garmin SDK Metrics in Avicenna

Each metric includes details about its fields and the default sampling rates. Also, all metrics include the common data fields and the following additional fields:

  • Device: The device that collected the data. Internally stored as device. It contains the following fields:
    • Device ID: The unique ID of the device. Internally stored as identifier.
    • Device Name: The name of the device. Internally stored as name.
    • Device Model: The model of the device. Internally stored as model.
    • Device Firmware Version: The firmware version of the device. Internally stored as firmware_version.

[!note]
The specific metrics collected depend on your Garmin device model. Not all metrics listed below are available on every device. To determine which metrics are supported by your watch, please refer to your device manual.

Garmin Health SDK Logged Accelerometer

Records 25Hz accelerometer data from all three axes in milli-Gs. Timestamps are recorded in milliseconds.

  • Acceleration X: Measures acceleration along the x-axis. Internally stored as x_value.
  • Acceleration Y: Measures acceleration along the y-axis. Internally stored as y_value.
  • Acceleration Z: Measures acceleration along the z-axis. Internally stored as z_value.

Garmin Health SDK Logged Actigraphy

Provides actigraphy data from three independently configurable instances. Each sample includes three activity metrics computed from 25Hz accelerometer data. The data is logged with a default processing interval of 30 seconds.

  • Instance: Indicates which of the three actigraphy instances the data belongs to. Internally stored as instance. Possible values are:

    Numeric Value Name Description
    0 ACTIGRAPHY_INSTANCE_UNKNOWN Unknown or undefined actigraphy instance
    1 ACTIGRAPHY_1 First actigraphy instance
    2 ACTIGRAPHY_2 Second actigraphy instance
    3 ACTIGRAPHY_3 Third actigraphy instance

  • End Timestamp: The end time of the actigraphy measurement interval. Internally stored as end_timestamp.

  • Total Energy: The total energy calculated from the accelerometer data. Internally stored as total_energy.

  • Zero Crossing Count: The number of zero crossings detected during the interval. Internally stored as zero_crossing_count.

  • Time Above Threshold: The time spent above the activity threshold during the interval. Internally stored as time_above_threshold.

Garmin Health SDK Logged BBI

Provides beat-to-beat intervals (BBI) for individual heartbeats. This data type records all valid heartbeats continuously without intervals.

  • BBI: The beat-to-beat interval value in milliseconds. Internally stored as bbi.

Garmin Health SDK Logged Enhanced BBI

Provides beat-to-beat intervals (BBI), supplemented with a confidence value that indicates the quality of the BBI data. This data type records all valid heartbeats continuously without intervals.

  • Status: Indicates the confidence level and quality of the BBI measurement. Internally stored as status. Possible values are:

    Numeric Value Name Description
    0 ENHANCED_BBI_STATUS_UNKNOWN Unknown or undefined BBI status
    1 ENHANCED_BBI_STATUS_GAP Gap in BBI data detected
    2 ENHANCED_BBI_STATUS_HIGH_CONFIDENCE High confidence BBI measurement
    3 ENHANCED_BBI_STATUS_LOW_CONFIDENCE Low confidence BBI measurement

  • BBI: The beat-to-beat interval value in milliseconds. Internally stored as bbi.

  • Gap Duration: The duration of any gap in the BBI data in milliseconds. Internally stored as gap_duration.

Garmin Health SDK Logged Gyroscope

Records 32Hz gyroscope data, representing the rate of rotation around each of the three axes in degrees/second. Timestamps are recorded in milliseconds.

  • Rotation Rate X: The rate of rotation around the x-axis in degrees per second. Internally stored as x_value.
  • Rotation Rate Y: The rate of rotation around the y-axis in degrees per second. Internally stored as y_value.
  • Rotation Rate Z: The rate of rotation around the z-axis in degrees per second. Internally stored as z_value.

Garmin Health SDK Logged Heart Rate

Measures heart rate in beats per minute (BPM). Data is reported as instantaneous values with a default interval of 60 seconds.

  • Heart Rate: The heart rate in beats per minute (BPM). Internally stored as beats_per_minute.

  • Status: Determines if the device is on-wrist or not, making it useful for adherence monitoring. Internally stored as status. Possible values are:

    Numeric Value Name Description
    0 HEART_RATE_STATUS_UNKNOWN Unknown or undefined heart rate status
    1 HEART_RATE_STATUS_SEARCHING Device is searching for the heart rate signal
    2 HEART_RATE_STATUS_LOCKED Device has locked onto the heart rate signal

Garmin Health SDK Motion Intensity

Provides motion intensity data with activity type classification. Motion intensity is a numerical abstraction of low-level accelerometer data calculated at minute-level granularity, representing the level of physical motion regardless of whether the user actually changes location. Motion intensity values can rise even if the user remains in the same place. For example, activities like jumping in place or fidgeting with a pencil will not contribute to distance metrics, but will still increase motion intensity scores during that period. It is also common to observe moderate motion intensity values during sedentary periods, since most people do not remain completely motionless.

  • Activity Type: Indicates the type of activity detected during the motion intensity measurement. Internally stored as activity_type. Possible values are:

    Numeric Value Enum Name Description
    0 GENERIC Generic activity type
    1 RUNNING Running activity
    2 CYCLING Cycling activity
    3 TRANSITION Transition between activities
    4 FITNESS_EQUIPMENT Fitness equipment usage
    5 SWIMMING Swimming activity
    6 WALKING Walking activity
    7 SLEEP Sleep activity
    8 SEDENTARY Sedentary activity
    9 UNMONITORED Unmonitored activity
    10 DRIVING Driving activity
    11 DOG_TRAINING Dog training activity
    12 EATING Eating activity
    13 ALL All activity types

  • Intensity Level: The motion intensity level value ranging from 0 to 7, where 0 represents absolutely still and 7 represents constant, sharp motion. Internally stored as intensity_level.

  • End Timestamp: The end time of the motion intensity measurement interval. Internally stored as end_timestamp.

Garmin Health SDK MoveIQ Event

Provides MoveIQ event data with activity type classification. MoveIQ events are Garmin activities that are not started by the user explicitly. Instead, a MoveIQ activity is triggered based on the analysis of user activity.

  • Activity Type: Indicates the type of activity detected during the MoveIQ event. Internally stored as activity_type. Possible values are:

    Numeric Value Enum Name Description
    0 GENERIC Generic activity type
    1 RUNNING Running activity
    2 CYCLING Cycling activity
    3 TRANSITION Transition between activities
    4 FITNESS_EQUIPMENT Fitness equipment usage
    5 SWIMMING Swimming activity
    6 WALKING Walking activity
    7 SLEEP Sleep activity
    8 SEDENTARY Sedentary activity
    9 UNMONITORED Unmonitored activity
    10 DRIVING Driving activity
    11 DOG_TRAINING Dog training activity
    12 EATING Eating activity
    13 ALL All activity types

  • End Timestamp: The end time of the MoveIQ event. Internally stored as end_timestamp.

Garmin Health SDK Logged Stress

Records the Garmin stress score, a value normalized from 0 to 100. Data is reported as instantaneous values with a default interval of 60 seconds.

  • Stress Score: The Garmin stress score. Internally stored as stress_score.

  • Status: Helps determine the quality of the stress measurement. Internally stored as status. Possible values are:

    Numeric Value Name Description
    0 STRESS_STATUS_UNKNOWN Unknown or undefined stress status
    1 STRESS_STATUS_LARGE_MOTION Device detected large motion (unreliable stress measurement)
    2 STRESS_STATUS_NOT_ENOUGH_DATA Insufficient data available for stress calculation
    3 STRESS_STATUS_OFF_WRIST Device is not being worn (off wrist)
    4 STRESS_STATUS_RECOVERING_FROM_EXERCISE Device is in recovery mode after exercise
    5 STRESS_STATUS_UNIDENTIFIED Stress status could not be identified
    6 STRESS_STATUS_VALID Valid stress measurement available

Garmin Health SDK Logged Steps

Measures the number of steps taken during a one-minute interval. Data is reported as instantaneous values with a default interval of 60 seconds.

  • Step Count: The number of steps recorded during the current interval. Internally stored as step_count.
  • Total Steps: The cumulative total of steps recorded since the last reset. Internally stored as total_steps.
  • End Timestamp: The end time of the step counting interval. Internally stored as end_timestamp.

Garmin Health SDK Logged SpO2

Measures blood oxygen saturation (SpO2). Data is reported as instantaneous values with a default interval of 60 seconds. Pulse Ox measurement is highly sensitive to motion.

  • SpO2 Reading: The blood oxygen saturation (SpO2). Internally stored as spo2_reading.

Garmin Health SDK Logged Respiration

Measures respiration rate in breaths per minute. Data is reported as instantaneous values with a default interval of 60 seconds.

  • Respiration: The respiration rate in breaths per minute. Internally stored as breaths_per_minute.

  • Status: Indicates the quality and reliability of the respiration measurement. Internally stored as status. Possible values are:

    Numeric Value Name Description
    0 RESPIRATION_STATUS_UNKNOWN Unknown or undefined respiration status
    1 RESPIRATION_STATUS_VALID Valid respiration measurement available
    2 RESPIRATION_STATUS_OFF_WRIST Device is not being worn (off wrist)
    3 RESPIRATION_STATUS_LARGE_MOTION Device detected large motion (unreliable measurement)
    4 RESPIRATION_STATUS_INVALID Invalid respiration measurement
    5 RESPIRATION_STATUS_UNAVAILABLE Respiration measurement unavailable

Garmin Health SDK Logged Sleep

Provides detailed sleep data, including sleep intervals, assessments, and overnight skin temperature. Internally stored as sleep.

  • Sleep Result Type: Indicates the type of sleep analysis performed. Internally stored as sleep_result_type. Possible values are:

    Numeric Value Enum Name Description
    0 SLEEP_RESULT_TYPE_UNKNOWN Unknown or undefined sleep result type
    1 SLEEP_RESULT_TYPE_ENHANCED Enhanced sleep analysis
    2 SLEEP_RESULT_TYPE_MOTION_BASED Motion-based sleep analysis

  • Sleep Source Type: Indicates the source of the sleep data. Internally stored as sleep_source_type. Possible values are:

    Numeric Value Enum Name Description
    0 SLEEP_SOURCE_TYPE_UNKNOWN Unknown or undefined sleep source type
    1 SLEEP_SOURCE_TYPE_SERVER Sleep data from server
    2 SLEEP_SOURCE_TYPE_DEVICE Sleep data from device

  • End Time: The end time of the sleep session. Internally stored as end_time.

  • Sleep Intervals: Array of sleep intervals. Internally stored as sleep_interval. It contains the following fields:

    • Start Time: The start time of the sleep interval. Internally stored as start_time.

    • End Time: The end time of the sleep interval. Internally stored as end_time.

    • Sleep Level: Indicates the sleep stage or level during a sleep interval. Internally stored as sleep_level. Possible values are:

      Numeric Value Enum Name Description
      0 SLEEP_LEVEL_UNKNOWN Unknown or undefined sleep level
      1 SLEEP_LEVEL_INVALID Invalid sleep level measurement
      2 SLEEP_LEVEL_UNMEASURABLE Sleep level could not be measured
      3 SLEEP_LEVEL_AWAKE Awake during sleep period
      4 SLEEP_LEVEL_LIGHT Light sleep stage
      5 SLEEP_LEVEL_DEEP Deep sleep stage
      6 SLEEP_LEVEL_REM REM (Rapid Eye Movement) sleep stage

  • Sleep Assessments: Array of sleep assessments with various sleep quality scores. Internally stored as sleep_assessment. It contains the following fields:

    • Start Time: The start time of the sleep assessment period in milliseconds since epoch. Internally stored as start_time.
    • End Time: The end time of the sleep assessment period in milliseconds since epoch. Internally stored as end_time.
    • Awakenings Count: Number of awakenings during the sleep period. Internally stored as awakenings_count.
    • Awakenings Count Score: Garmin’s proprietary score based on the number of awakenings. Internally stored as awakenings_count_score.
    • Awake Time Score: Garmin’s proprietary score based on time spent awake. Internally stored as awake_time_score.
    • Combined Awake Score: Garmin’s proprietary combined score for awake-related metrics. Internally stored as combined_awake_score.
    • Deep Sleep Score: Garmin’s proprietary score based on deep sleep quality. Internally stored as deep_sleep_score.
    • Light Sleep Score: Garmin’s proprietary score based on light sleep quality. Internally stored as light_sleep_score.
    • Overall Sleep Score: Garmin’s proprietary overall sleep quality score. Internally stored as overall_sleep_score.
    • REM Sleep Score: Garmin’s proprietary score based on REM sleep quality. Internally stored as rem_sleep_score.
    • Sleep Duration Score: Garmin’s proprietary score based on total sleep duration. Internally stored as sleep_duration_score.
    • Sleep Quality Score: Garmin’s proprietary general sleep quality score. Internally stored as sleep_quality_score.
    • Sleep Recovery Score: Garmin’s proprietary score indicating sleep recovery quality. Internally stored as sleep_recovery_score.
    • Sleep Restlessness Score: Garmin’s proprietary score based on sleep restlessness. Internally stored as sleep_restlessness_score.
    • Interruptions Score: Garmin’s proprietary score based on sleep interruptions. Internally stored as interruptions_score.

  • Sleep Restless Moments: Array of timestamps for restless moments during sleep. Each entry is a timestamp in milliseconds since epoch. Internally stored as sleep_restless_moments.

  • Overnight Skin Temperature: Overnight skin temperature data, including average temperature and calibration information. Internally stored as overnight_skin_temperature. It contains the following fields:

    • Timestamp: The timestamp of the temperature measurement in milliseconds since epoch. Internally stored as timestamp.
    • Average Temperature Change: Change in average temperature from baseline in degrees Celsius. Internally stored as average_temperature_change.
    • Seven-Day Mean of Average Temperature Change: Seven-day average of temperature changes in degrees Celsius. Internally stored as seven_day_mean_of_average_temperature_change.
    • Average Temperature: Average skin temperature during sleep in degrees Celsius (range 0°C to 65°C). Internally stored as average_temperature.
    • Days Calibrated: Number of days the temperature sensor has been calibrated. Internally stored as days_calibrated.

Garmin Health SDK Logged Zero Crossing

Provides an algorithmic view of motion based on a count of “zero crossings” and a calculated physical power measurement. The data is aggregated with a default interval of 30 seconds.

  • Zero Crossing Count: The number of zero crossings detected during the interval. Internally stored as zero_crossing_count.
  • Total Energy: The total energy calculated from the motion data. Internally stored as total_energy.
  • Deadband: The deadband value used in the zero crossing calculation. Internally stored as deadband.
  • End Timestamp: The end time of the zero crossing measurement interval. Internally stored as end_timestamp.

Garmin Health SDK Logged Wrist Status

Tracks whether the Garmin device is worn on the wrist. This data is generated every minute and whenever the wrist status changes. Logging is enabled by default when other data types are active. Internally stored as wrist_status.

  • Status: Indicates whether the device is being worn on the wrist. Internally stored as status. Possible values are:

    Numeric Value Name Description
    0 WRIST_STATUS_UNKNOWN Unknown or undefined wrist status
    1 WRIST_STATUS_OFF_WRIST Device is not being worn on the wrist
    2 WRIST_STATUS_ON_WRIST Device is being worn on the wrist

Garmin Health SDK Logged Skin Temperature

Provides skin temperature readings in degrees Celsius, estimated using a calibrated heat flow model. Data is reported as instantaneous values with a default interval of 60 seconds. Internally stored as skin_temperature.

  • Status: Indicates the quality and reliability of the skin temperature measurement. Internally stored as status. Possible values are:

    Numeric Value Name Description
    0 SKIN_TEMPERATURE_STATUS_UNKNOWN Unknown or undefined skin temperature status
    1 SKIN_TEMPERATURE_STATUS_VALID Valid skin temperature measurement available
    2 SKIN_TEMPERATURE_STATUS_INVALID Invalid skin temperature measurement

  • Temperature: The skin temperature reading in degrees Celsius (range 0°C to 65°C). Internally stored as temperature.

Metric Configuration Options

The following table shows the default intervals and available configuration options for each Garmin SDK metric:

Metric Default Interval/Frequency Configurable Range Notes
Accelerometer 25Hz continuous Fixed (not configurable) -
Actigraphy 30 seconds 1-30 seconds, or multiples of 30 seconds, max 1 hour (3600 seconds) -
BBI Continuous Not applicable -
Enhanced BBI Continuous Not applicable -
Gyroscope 32Hz continuous Fixed (not configurable) -
Heart Rate 60 seconds 1 second to 1 hour (3600 seconds) Shorter intervals recommended for detailed monitoring
Motion Intensity Not applicable Not applicable Motion intensity is calculated at minute-level granularity
MoveIQ Event Not applicable Not applicable Events are triggered based on analysis of user activity
Respiration 60 seconds 1 second to 1 hour (3600 seconds) Values may not update for intervals < 10 seconds
Sleep Not applicable Not applicable Sleep data is collected automatically during sleep periods
Skin Temperature 60 seconds 1 second to 1 hour (3600 seconds) -
SpO2 60 seconds 1 second to 1 hour (3600 seconds) Values may not update for intervals < 10 seconds
Steps 60 seconds Fixed (not configurable) -
Stress 60 seconds 1 second to 1 hour (3600 seconds) Values may not update for intervals < 10 seconds
Wrist Status Every minute + status changes Fixed (not configurable) -
Zero Crossing 30 seconds Multiples of 30 seconds, max 1 hour (3600 seconds) -

To modify the default intervals or frequencies for your study, please contact our support team. Custom configurations can be set up based on your specific research requirements.

Data Collection Behavior

All data is collected automatically on the watch once it is paired with the phone, and the app will sync data from the watch on certain events and on regular intervals while the watch is in proximity to the phone, the Bluetooth connection is active, and the app is running in the background or foreground. You can also manually sync data from the watch by tapping the sync button in the app, as described in the Garmin SDK Data Sources in Participant Device section.

[!note]
Considering the amount of data that is being collected, it is recommended to sync data from the watch regularly to avoid data loss.

Adding Garmin SDK Metrics As Data Sources

See Accessing Data Sources.

Monitoring and Exporting Garmin Data

You can export and download the collected Garmin SDK metrics data using the Data Export page.

Garmin SDK Data Sources in Participant Device

To use any of these data sources, follow the instructions below.

  1. Put your Garmin watch in pairing mode.
    This setting is typically found under Settings > Bluetooth or Phone > Pair Mobile Device or Pair Phone on your Garmin watch. Refer to your device manual for specific steps.

  2. Start the Garmin pairing process and grant Bluetooth permissions.
    If your study requires Garmin data, you will see an onboarding alert to pair your Garmin device. Tap START PAIRING button to begin. The app will then request permission to scan for Bluetooth devices, if not already granted. Tap Allow to proceed.

  3. Select your Garmin device.
    The app will scan for nearby devices. When your Garmin watch appears in the list, select it.

  4. Complete user settings.
    You will be asked to enter your personal information (e.g., gender, birth year, height, weight, sleep schedule). Fill in the required fields and tap Continue.

    [!note]
    These settings affect some of your metrics, so it is important to fill them in accurately. To modify these settings later, you will need to unpair your Garmin device and pair it again.

  5. Pair the device.
    Tap Pair Device to initiate pairing.

  6. Confirm pairing and connection.
    Once paired, your Garmin watch will appear as a connected device in the app. You can view its status and sync data as needed. By selecting your Garmin device, you will be able to view the connection status, the date and time of the last sync, and the unpairing option.

  7. Sync data.
    You can tap Sync to manually synchronize data from your Garmin watch.