HealthKit deep-read.

HealthKit is iOS's health data store. It's the right primitive for any app that needs the user's heart rate, sleep, workouts, or 100+ other quantities — and the only way to write data that other apps (and Apple Health) will see. This guide covers the patterns I've used in tmpo (read + write + observe across 8 write types) and on Weather.Co's wrist surface.

Step 1Request authorization

HealthKit auth is two-way: you ask for read permissions and write permissions separately. The 8 write types I've shipped in tmpo: body mass, body fat percentage, lean body mass, height, dietary energy, dietary protein, dietary carbohydrates, dietary fat. The reads are a much longer list — heart rate, HRV, sleep, workouts, etc.

import HealthKit

final class HealthStore {
  static let shared = HealthStore()
  let store = HKHealthStore()

  let readTypes: Set<HKObjectType> = [
    HKQuantityType(.heartRate),
    HKQuantityType(.heartRateVariabilitySDNN),
    HKQuantityType(.activeEnergyBurned),
    HKQuantityType(.stepCount),
    HKCategoryType(.sleepAnalysis),
    HKObjectType.workoutType(),
    // …add the rest you need
  ]
  let writeTypes: Set<HKSampleType> = [
    HKQuantityType(.bodyMass),
    HKQuantityType(.bodyFatPercentage),
    HKQuantityType(.leanBodyMass),
    HKQuantityType(.height),
    HKQuantityType(.dietaryEnergyConsumed),
    HKQuantityType(.dietaryProtein),
    HKQuantityType(.dietaryCarbohydrates),
    HKQuantityType(.dietaryFatTotal),
  ]

  func requestAuth() async throws {
    guard HKHealthStore.isHealthDataAvailable() else { throw HKError(.errorHealthDataUnavailable) }
    try await store.requestAuthorization(toShare: writeTypes, read: readTypes)
  }
}

Step 2Read a sample (the modern way)

func latestHeartRate() async throws -> Double? {
  let type = HKQuantityType(.heartRate)
  let descriptor = HKSampleQueryDescriptor(
    predicates: [.sample(type: type)],
    sortDescriptors: [SortDescriptor(\.endDate, order: .reverse)],
    limit: 1
  )
  let results = try await descriptor.result(for: store)
  guard let sample = results.first as? HKQuantitySample else { return nil }
  return sample.quantity.doubleValue(for: HKUnit(from: "count/min"))
}

Step 3Write a sample

func logBodyMass(_ kg: Double, at date: Date = .now) async throws {
  let type = HKQuantityType(.bodyMass)
  let qty = HKQuantity(unit: .gramUnit(with: .kilo), doubleValue: kg)
  let sample = HKQuantitySample(type: type, quantity: qty, start: date, end: date)
  try await store.save(sample)
}

Critical: pass start == end for a point-in-time reading, or start ≠ end for a duration (e.g. dietary intake over a meal). Apple Health uses this to lay the sample out on the timeline.

Step 4Observe changes

You don't poll HealthKit. You register an HKObserverQuery and HealthKit wakes your app when new data arrives — even when the app is in the background (with the right entitlement).

func startObserving() {
  let type = HKQuantityType(.stepCount)
  let query = HKObserverQuery(sampleType: type, predicate: nil) { [weak self] _, completion, error in
    defer { completion() }
    guard error == nil else { return }
    Task { await self?.refreshUI() }
  }
  store.execute(query)
  store.enableBackgroundDelivery(for: type, frequency: .hourly) { _, _ in }
}

enableBackgroundDelivery requires the HealthKit background delivery entitlement, which Apple grants on request (in App Store Connect). Without it, observers only fire when the app is foreground.

Step 5Aggregate (the right primitive for charts)

For dashboards — "steps per day for the last 30 days" — use HKStatisticsCollectionQueryDescriptor rather than fetching every sample and grouping yourself. HealthKit aggregates server-side and it's dramatically faster.

func dailySteps(days: Int) async throws -> [(Date, Double)] {
  let end = Calendar.current.startOfDay(for: .now).addingTimeInterval(86400)
  let start = Calendar.current.date(byAdding: .day, value: -days, to: end)!
  let type = HKQuantityType(.stepCount)
  let descriptor = HKStatisticsCollectionQueryDescriptor(
    predicate: HKSamplePredicate.quantitySample(type: type),
    options: .cumulativeSum,
    anchorDate: end,
    intervalComponents: .init(day: 1)
  )
  let stats = try await descriptor.result(for: store)
  var rows: [(Date, Double)] = []
  stats.enumerateStatistics(from: start, to: end) { stat, _ in
    let count = stat.sumQuantity()?.doubleValue(for: .count()) ?? 0
    rows.append((stat.startDate, count))
  }
  return rows
}

The summary: build for partial data (Apple won't tell you what's denied for reads), use the modern async API throughout, prefer aggregation queries for any UI that's "data over time," and remember background delivery needs an extra entitlement. tmpo's full Today surface — rings, decision, three rings, readiness — is built on this exact stack.