HealthKit

Reference
1

Apple HealthKit is a powerful framework that allows researchers to access a comprehensive range of health and fitness data collected by participants’ iPhones and paired Apple Watch devices. It acts as a central repository for metrics on physical activity, vital signs, sleep, nutrition, mobility, and more, offering researchers valuable insights into participants’ health behaviors and outcomes.

[!info]
HealthKit is available on iPhones running iOS 8.0 or later and on paired Apple Watch devices. Some data types require newer iOS versions, and these will be specified in the relevant sections.

Adding HealthKit As a Data Source

Access to HealthKit data is limited to research uses and requires a private entitlement, which Apple reviews separately for each study.

To add HealthKit as a data source to your study, please contact our support team. These are the main steps that should be done in the process:

  • A custom iOS application will be developed for your study (you can also have a custom Android application, but it’s not required). This is because our main application is designed to support all studies. For more details, you can check our Branding documentation.
  • After your custom iOS application is published in the App Store, it will have a Bundle ID.
  • Then, you should fill out an entitlement request document with Bundle ID, what data sources your study is going to collect and why, etc. Also, you should attach the Institutional Review Board (IRB) approval to the document.

For more detailed information about the HealthKit access process, visit Apple’s HealthKit Authorization Documentation.

Supported HealthKit Metrics in Avicenna

Below is a comprehensive list of HealthKit metrics that Avicenna supports. We’ll first cover the common fields that appear across all HealthKit data types, followed by the specific fields for each individual metric.

Common Fields Across All HealthKit Data Sources

All metrics include the common data fields and the following additional fields:

Source & Device

Basic information about the device providing health data. Internally stored as part of each HealthKit record and includes:

  • Source Name: Name of the app or device that recorded the data (e.g., “Apple Watch”). Internally stored as source_name.
  • Source Bundle ID: Bundle identifier of the source app. Internally stored as source_bundle_id.
  • Source Version: Version of the source app or device. Internally stored as source_version.
  • Device Model: Device model that recorded the data (e.g., “iPhone13,4”, “Watch6,2”). Internally stored as device_model.
  • Device Hardware Version: Hardware version of the device. Internally stored as device_hardware_version.
  • Device Software Version: Software version of the device. Internally stored as device_software_version.

Data Quality & Context

Information about the reliability and context of the health data:

  • Was User Entered: Boolean indicating if the data was manually entered by the user. Internally stored as was_user_entered.
  • Creation Date: When the data point was originally created. Internally stored as creation_date.
  • Start Date: Start time of the measurement period. Internally stored as start_date.
  • End Date: End time of the measurement period. Internally stored as end_date.

HealthKit Activity

Captures participant activity, including movement, energy expenditure, and workout data. Internally stored as healthkit_activity and includes:

  • Identifier: Unique measurement identifier. Internally stored as identifier.
  • Step Count: Number of steps taken. Internally stored as step_count.
  • Distance: Distance walked or run in meters. Internally stored as distance_meters.
  • Flights Climbed: Flights of stairs climbed. Internally stored as flights_count.
  • Energy: Active or basal energy burned, measured in kilocalories. Internally stored as energy_kcal.
  • Duration: Exercise time or workout length, measured in minutes. Internally stored as duration_minutes.
  • Workout Activity Type: Type of workout performed (e.g., running, cycling, yoga). Internally stored as workout_activity_type.

HealthKit Vital Signs

Provides insight into cardiovascular and respiratory health. Internally stored as healthkit_vital_signs and includes:

  • Identifier: Unique measurement identifier. Internally stored as identifier.
  • Heart Rate: Heart rate in beats per minute (BPM). Internally stored as heart_rate_bpm.
  • Resting Heart Rate: Baseline resting heart rate in beats per minute (BPM). Internally stored as resting_heart_rate_bpm.
  • Heart Rate Variability (HRV): Root mean square of successive differences (RMSSD), measured in milliseconds. Internally stored as hrv_rmssd_ms.
  • Systolic Pressure: Systolic blood pressure value in millimeters of mercury (mmHg). Internally stored as systolic_pressure_mmhg.
  • Diastolic Pressure: Diastolic blood pressure value in millimeters of mercury (mmHg). Internally stored as diastolic_pressure_mmhg.
  • Respiratory Rate: Breathing rate in breaths per minute. Internally stored as respiratory_rate_bpm.
  • Oxygen Saturation: Blood oxygen level as a percentage. Internally stored as oxygen_saturation_percent.

HealthKit Sleep

Allows researchers to assess sleep quality, duration, and circadian patterns. Internally stored as healthkit_sleep and includes:

  • Identifier: Unique measurement identifier. Internally stored as identifier.
  • Sleep State: Type of sleep recorded. Internally stored as sleep_state. It can be one of the following:
    • IN_BED
    • ASLEEP_UNSPECIFIED
    • AWAKE
    • ASLEEP_CORE
    • ASLEEP_DEEP
    • ASLEEP_REM
  • Duration: Duration of the sleep state in minutes. Internally stored as duration_minutes.

HealthKit State of Mind

iOS 17+

Allows researchers to study emotional well-being and its relationship with physiological or behavioral factors. Internally stored as healthkit_state_of_mind and includes:

  • Identifier: Unique measurement identifier. Internally stored as identifier.
  • Kind: Type of mood captured. Internally stored as kind. Possible values include:
    • MOMENTARY: Momentary emotion
    • DAILY: Daily mood summary
  • Valence: Emotional valence ranging from negative to positive. Internally stored as valence. It can be one of the following:
    • VERY_UNPLEASANT
    • UNPLEASANT
    • SLIGHTLY_UNPLEASANT
    • NEUTRAL
    • SLIGHTLY_PLEASANT
    • PLEASANT
    • VERY_PLEASANT
  • Labels: Participant-selected descriptors of mood. Internally stored as labels. It can be one of the following:
    • AMAZED
    • AMUSED
    • ANGRY
    • ANXIOUS
    • ASHAMED
    • BRAVE
    • CALM
    • CONTENT
    • DISAPPOINTED
    • DISCOURAGED
    • DISGUSTED
    • EMBARRASSED
    • EXCITED
    • FRUSTRATED
    • GRATEFUL
    • GUILTY
    • HAPPY
    • HOPELESS
    • IRRITATED
    • JEALOUS
    • JOYFUL
    • LONELY
    • PASSIONATE
    • PEACEFUL
    • PROUD
    • RELIEVED
    • SAD
    • SCARED
    • STRESSED
    • SURPRISED
    • WORRIED
    • ANNOYED
    • CONFIDENT
    • DRAINED
    • HOPEFUL
    • INDIFFERENT
    • OVERWHELMED
    • SATISFIED
  • Associations: Context associated with the mood. Internally stored as associations. It can be one of the following:
    • COMMUNITY
    • CURRENT_EVENTS
    • DATING
    • EDUCATION
    • FAMILY
    • FITNESS
    • FRIENDS
    • HEALTH
    • HOBBIES
    • IDENTITY
    • MONEY
    • PARTNER
    • SELF_CARE
    • SPIRITUALITY
    • TASKS
    • TRAVEL
    • WORK
    • WEATHER

HealthKit Electrocardiogram

Apple Watch Series 4+

Records electrocardiogram (ECG) data from Apple Watch. Internally stored as healthkit_ecg and includes:

  • Identifier: Unique measurement identifier. Internally stored as identifier.
  • Average Heart Rate: Average heart rate during the recording, in beats per minute. Internally stored as average_heart_rate.
  • Classification: ECG interpretation. Internally stored as classification. It can be one of the following:
    • CLASSIFICATION_NOT_SET
    • SINUS_RHYTHM: Normal rhythm
    • ATRIAL_FIBRILLATION: AFib detected
    • INCONCLUSIVE_LOW_HEART_RATE: Unable to classify due to low heart rate
    • INCONCLUSIVE_HIGH_HEART_RATE: Unable to classify due to high heart rate
    • INCONCLUSIVE_POOR_READING: Unable to classify due to poor signal quality
    • INCONCLUSIVE_OTHER: Unable to classify for other reasons
    • UNRECOGNIZED
  • Symptoms Status: Indicates whether the participant reported symptoms during the recording. Internally stored as symptoms_status. It can be one of the following:
    • STATUS_NOT_SET
    • NONE: No symptoms reported
    • PRESENT: Symptoms reported
    • STATUS_UNKNOWN
  • Voltages: Raw ECG waveform voltage values in millivolts. Internally stored as voltages.
  • Number of Voltage Measurements – Total number of voltage samples recorded. Internally stored as number_of_voltage_measurements.
  • Sample Start Time: Time in seconds since the start of the ECG recording. Internally stored as time_since_sample_start.
  • Sampling Frequency: Frequency at which voltage measurements were recorded, in Hz. Internally stored as sampling_frequency.
  • Lead: Lead configuration used for recording. Internally stored as lead.

HealthKit Body Measurements

Tracks participant body metrics. Internally stored as healthkit_body_measurements and includes:

  • Identifier: Unique measurement identifier. Internally stored as identifier.
  • Height: Body height in meters. Internally stored as height_meters.
  • Mass: Body weight in kilograms. Internally stored as mass_kg.
  • BMI: Body Mass Index calculated from height and weight. Internally stored as bmi_value.
  • Body Fat Percentage: Body fat composition as a percentage. Internally stored as body_fat_percent.

Data Collection Behavior

HealthKit data is collected within Avicenna’s standard 5-minute collection cycle. The app queries the HealthKit store for new data since the last fetch. This process avoids duplicates and prioritizes the most accurate source, such as an Apple Watch over an iPhone. New data is available for collection almost immediately after a device syncs with Apple Watch.

User Consent

HealthKit data is never accessible without explicit user consent. Participants have granular control over permissions and can update them at any time via iOS settings.

Monitoring and Exporting HealthKit Data

You can export and download the collected HealthKit data using the Data Export page.