Apple HealthKitV2 Samples Export Format
- Updated
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"
}
Was this article helpful?