About the HealthKit Framework

The HealthKit framework is designed to share data between apps in a meaningful way. The framework constrains the types of data and units to a predefined list, ensuring that all apps understand what the data means and how it can be used. Developers cannot create custom data types or units. Instead, HealthKit provides a wide variety of data types and units.

Additionally, the framework uses a large number of subclasses, producing deep hierarchies of similar classes. Often, these classes have subtle but important differences between them. For example, an HKQuantitySample object is used to store data with a numeric value, while an HKCategorySample object is used to store a value selected from an enumeration.

HealthKit also uses pairs of closely related classes. These classes must be paired correctly. For example, the HKObject and HKObjectType abstract classes have largely parallel hierarchies of concrete subclasses. When working with objects and object types, you must use matching subclasses.

HealthKit saves a variety of data types in the HealthKit Store:

• Characteristic data. These records represent items that typically do not change, such as the user’s birthdate, blood type, biological sex, and skin type. You can read this data directly from the HealthKit store, using the dateOfBirthWithError:, bloodTypeWithError:, biologicalSexWithError:, and fitzpatrickSkinTypeWithError: methods. Your application cannot save characteristic data. The user must enter or modify this data using the Health app.

• Sample data. Most of the user’s health data is stored in samples that represent data at a particular point in time. All sample classes are subclasses of the HKSample class, which is a subclass of the HKObject class. These classes are described in more detail in Samples.

• Workout data. Information about fitness and exercise activities are stored as HKWorkout samples. While HKWorkout is a subclass of HKSample, it behaves somewhat differently than other sample subclasses. These differences are described in Workout Data.

• Source data. Each sample stores information about its source. The HKSourceRevision object contains information about the app or device that saved the sample. The HKDevice object contains information about the hardware device that generated the data.

• Deleted objects. An HKDeletedObject instance is used to temporarily store the UUID of an item that has been deleted from the HealthKit store. You can use deleted objects to respond when an object is deleted by the user or another app. For more information, see HKAnchoredObjectQuery and HKDeletedObject.

The HKObject class is the superclass of all HealthKit sample types. All HKObject subclasses are immutable. Each object has the following properties:

• UUID. A unique identifier for that particular entry.

• Metadata. A dictionary containing additional information about the entry. The metadata can contain both predefined and custom keys. The predefined keys facilitate the sharing of data between apps. Custom keys help extend a given HealthKit object type, adding app-specific data to the entry.

• Source Revision. The source of the sample. The source can be a device that directly saves data into HealthKit, or an app. HealthKit automatically records each object’s source and version when the object is saved to the HealthKit store. This property is available only on objects retrieved from the store.

• Device. The hardware device that generated the data stored in this sample.

The HKSample class is a subclass of HKObject. Sample objects represent data at a particular point in time, and all sample objects are subclasses of the HKSample class. They have the following properties:

• Type. The sample type, such as a sleep analysis sample, a height sample, or a step count sample.

• Start date. The sample’s start time.

• End date. The sample’s end time. If the sample represents a single point in time, the end time should equal the start time. If the sample represents data collected over a time interval, the end time should occur after the start time.

Samples are further divided into four concrete subclasses:

• Category samples. Data that can be classified into a finite set of categories. See HKCategorySample.

• Quantity samples. Data that can be stored as numeric values. Quantity samples are the most common data types in HealthKit. These include the user’s height and weight, as well as other data such as the number of steps taken, the user’s temperature, and their pulse rate. See HKQuantitySample.

• Correlations. Composite data containing one or more samples. In iOS 8.0, HealthKit uses correlations to represent food and blood pressure. You should always use a correlation when creating food or blood pressure data. See HKCorrelation.

• Workouts. Data representing a physical activity, like running, swimming, or even play. Workouts often have type, duration, distance, and energy burned properties. You can also associate a workout with a number of fine-grained samples. Unlike correlations, these samples are not contained within the workout—however, they can be queried using the workout. For more information, see HKWorkout.

The HealthKit store is thread-safe, and most HealthKit objects are immutable. In general, you can use HealthKit safely in a multithreaded environment.

For more information about multithreading and concurrent programming, see Concurrency Programming Guide.

iPhone and Apple Watch each have their own HealthKit store, and data is automatically synced between the phone and watch. To save space, old data is periodically purged from Apple Watch. Use earliestPermittedSampleDate to determine the oldest samples available on Apple Watch.

HealthKit is not available on iPad.