Articles in this section

See more

Apple HealthKitV2 Samples Export Format

  • Updated
Follow

The HealthKit samples export encompasses most of the sample data generated by HealthKit (e.g., Heart Rate, Sleep Analysis, Steps, and any other data that is not a workout or activity summary).

Table of Contents

Data Structure

One file will be created per type of data (e.g., "HeartRate" and "VO2Max"). The file name will correspond to the type of data (e.g., "HealthKitV2Samples_HeartRate_20211101-20211217" and "HealthKitV2Samples_VO2Max_20211101-20211217").

Your team will need to be mindful of the following samples, ensuring they are removed for analysis:
  • Duplicate Samples: You may see duplicate samples exported over time, typically occurring if a participant deletes and reinstalls MyDataHelps. HealthKit samples are immutable, so when doing data analysis, your team will need to remove any samples that have the same HealthKitSampleKey and ParticipantIdentifier as another sample.

  • Deleted Samples: Participants may delete their HealthKit samples from their device or, occasionally, Apple Health will combine historic samples to save space, creating deleted samples. For example, consecutive step samples of 30 and 70 steps might be combined into a single step sample of 100 steps. The new 100 step sample would be delivered in the "Steps" file while the 30 and 70 step samples would be in the deleted steps file.

Samples

Field Description
HealthKitSampleKey A unique, auto-generated key for this sample.
ParticipantIdentifier The identifier of the participant this sample was recorded for. Can be used to cross reference with Participants.
ParticipantID The stable, automatically generated, internal system identifier for this participant. Universally unique identifier (UUID).
Type The data type - e.g. “Steps”, “HeartRate.”
StartDate The start date of the recording, in ISO 8601 format. Includes timezone offset information. May be empty if no start date was recorded.
Date The end date of the recording, in ISO 8601 format. Includes timezone offset information.
Value The recorded value.
Units The units for the corresponding value.
SourceIdentifier Uniquely identifies the iOS App which generated the reading. “com.apple.health.*” indicates a reading from an Apple Device like the iPhone or Apple Watch.
SourceName The name of the source app which generated the reading. In the case of a “com.apple.health.*” SourceIdentifier, this is the name of the Apple Device used to generate the reading (e.g. “Chris’ iPhone”).
SourceVersion The version of the source app which generated the reading. In the case of a “com.apple.health.*” SourceIdentifier, this is the version of iOS or WatchOS on the device used to generate the reading.
SourceOperatingSystemVersion An arbitrary string representing the version of the software running on the device, if applicable.
SourceProductType An arbitrary string representing the hardware version of the device, if applicable.
DeviceName The user-facing name for the device, if applicable.
DeviceModel Model of the device used the generate the reading, if applicable.
DeviceManufacturer Manufacturer of the device used the generate the reading, if applicable.
DeviceHardwareVersion An arbitrary string representing the hardware version of the device, if applicable.
DeviceSoftwareVersion An arbitrary string representing the version of the software running on the device, if applicable.
DeviceFirmwareVersion An arbitrary string representing the current version of the firmware running on the device, if applicable.
DeviceLocalIdentifier An identifier that uniquely identifies the device object on the hardware running this code, if applicable.
DeviceFDAIdentifier The device identifier portion of the US Food and Drug Administration’s Unique Device Identifier (UDI), if applicable.
Metadata Additional JSON metadata inserted by the source application.
InsertedDate The creation date of the entry, in ISO 8601 format. Is always in UTC.

Deleted Samples

Field Description
HealthKitSampleKey A unique, auto-generated key for this sample.
ParticipantIdentifier The identifier of the participant this sample was recorded for. Can be used to cross reference with Participants.
DeletedDate The date of the recording, in ISO 8601 format. Includes timezone offset information.

CSV Exports

Samples CSV Export

HealthKitSampleKey,ParticipantIdentifier,StartDate,Date,Value,Units,SourceIdentifier,SourceName,SourceVersion,SourceOperatingSystemVersion,SourceProductType,DeviceName,DeviceModel,DeviceManufacturer,DeviceHardwareVersion,DeviceSoftwareVersion,DeviceFirmwareVersion,DeviceLocalIdentifier,DeviceFDAIdentifier,Metadata,InsertedDate
84aeb80c-c27f-5972-9514-192a7305f71d,e794c47e-438e-4d7b-9b24-99ce68c75300,2021-10-26T08:24:09-04:00,2021-10-26T08:24:09-04:00,49.53,ml/(kg*min),com.apple.health.FA902D86-1FDE-492D-B25A-3EB99A9BC6A6,Sample's Apple Watch S4,2663.1.1,8.0.1,"Watch4,4",,,,,,,,,"{""HKMetadataKeySyncVersion"":""1"",""HKVO2MaxTestType"":""2"",""HKMetadataKeySyncIdentifier"":""3B0C822F-1389-413F-B5EA-B93E0E9F2634""}",2021-11-05T14:20:39Z
1422059e-6dcd-5872-8621-7b822e5e3c69,e794c47e-438e-4d7b-9b24-99ce68c75300,2021-10-28T08:25:47-04:00,2021-10-28T08:25:47-04:00,49.68,ml/(kg*min),com.apple.health.FA902D86-1FDE-492D-B25A-3EB99A9BC6A6,Sample's Apple Watch S4,2664.0.8.1.1,8.1.0,"Watch4,4",,,,,,,,,"{""HKMetadataKeySyncVersion"":""1"",""HKVO2MaxTestType"":""2"",""HKMetadataKeySyncIdentifier"":""720FC6FE-B451-433C-90B8-8784595F980F""}",2021-11-05T14:20:39Z
0e866a66-1610-5493-acb5-b3448fe06ad2,e794c47e-438e-4d7b-9b24-99ce68c75300,2021-10-28T18:17:54-04:00,2021-10-28T18:17:54-04:00,49.7,ml/(kg*min),com.apple.health.FA902D86-1FDE-492D-B25A-3EB99A9BC6A6,Sample's Apple Watch S4,2664.0.8.1.1,8.1.0,"Watch4,4",,,,,,,,,"{""HKMetadataKeySyncVersion"":""1"",""HKVO2MaxTestType"":""2"",""HKMetadataKeySyncIdentifier"":""E50E9B87-E76B-4244-B7D6-FB51B652A786""}",2021-11-05T14:20:39Z

Deleted Samples CSV Export

HealthKitSampleKey,ParticipantIdentifier,DeletedDate
7f445386-e542-554d-8eed-0113e493bd71,e794c47e-438e-4d7b-9b24-99ce68c75300,2021-11-05T14:20:12Z
1669ad87-edae-5090-afb1-a70abf17db28,e794c47e-438e-4d7b-9b24-99ce68c75300,2021-11-05T14:20:12Z
b2df16d0-f5f3-521a-963e-36967009cf2f,e794c47e-438e-4d7b-9b24-99ce68c75300,2021-11-05T14:20:12Z

JSON Exports

Samples JSON Export

{
 "HealthKitSampleKey":"84aeb80c-c27f-5972-9514-192a7305f71d",
 "ParticipantIdentifier":"e794c47e-438e-4d7b-9b24-99ce68c75300",
 "StartDate":"2021-10-26T08:24:09-04:00",
 "Date":"2021-10-26T08:24:09-04:00",
 "Value":"49.530000000000001",
 "Units":"ml/(kg*min)",
 "Source":
  {
   "Name":"Sample’s Apple Watch S4",
   "Identifier":"com.apple.health.FA902D86-1FDE-492D-B25A-3EB99A9BC6A6",
   "Version":"2663.1.1",
   "OperatingSystemVersion":"8.0.1",
   "ProductType":"Watch4,4"
  },
 "Device":null,
 "Metadata":
  {
   "HKMetadataKeySyncVersion":"1",
   "HKVO2MaxTestType":"2",
   "HKMetadataKeySyncIdentifier":"3B0C822F-1389-413F-B5EA-B93E0E9F2634"
  },
 "InsertedDate":"2021-11-05T14:20:39Z"
}
{
 "HealthKitSampleKey":"1422059e-6dcd-5872-8621-7b822e5e3c69",
 "ParticipantIdentifier":"e794c47e-438e-4d7b-9b24-99ce68c75300",
 "StartDate":"2021-10-28T08:25:47-04:00",
 "Date":"2021-10-28T08:25:47-04:00",
 "Value":"49.68",
 "Units":"ml/(kg*min)",
 "Source":
  {
   "Name":"Sample’s Apple Watch S4",
   "Identifier":"com.apple.health.FA902D86-1FDE-492D-B25A-3EB99A9BC6A6",
   "Version":"2664.0.8.1.1",
   "OperatingSystemVersion":"8.1.0",
   "ProductType":"Watch4,4"
  },
 "Device":null,
 "Metadata":
  {
   "HKMetadataKeySyncVersion":"1",
   "HKVO2MaxTestType":"2",
   "HKMetadataKeySyncIdentifier":"720FC6FE-B451-433C-90B8-8784595F980F"
  },
 "InsertedDate":"2021-11-05T14:20:39Z"
}

Deleted Samples JSON Export

{
 "HealthKitSampleKey":"7f445386-e542-554d-8eed-0113e493bd71",
 "ParticipantIdentifier":"e794c47e-438e-4d7b-9b24-99ce68c75300",
 "DeletedDate":"2021-11-05T14:20:12Z"
}
{
 "HealthKitSampleKey":"1669ad87-edae-5090-afb1-a70abf17db28",
 "ParticipantIdentifier":"e794c47e-438e-4d7b-9b24-99ce68c75300",
 "DeletedDate":"2021-11-05T14:20:12Z"
}

Related articles