Resting Heart Rate API: How to Read RHR From HealthKit and Health Connect

Resting heart rate looks like the easiest field in a health store: one small integer, roughly one per day, with the same name on both platforms. It is also the clearest example of the two platforms agreeing on a label and disagreeing on what the label means. HealthKit treats it as something the system works out and revises. Health Connect treats it as something an app asserts. Build a trend line without knowing which store you are reading and you will either show users values Apple has since withdrawn, or present an unverified integer as though a platform measured it.

HealthKit: an estimate the system keeps revising#

Apple documents HKQuantityTypeIdentifier.restingHeartRate as "A quantity sample type that measures the user's resting heart rate," available from iOS 11.0 and watchOS 4.0, using count/time units and measuring discrete values. The discussion is unusually candid for a type page and worth quoting closely.

First, on what the number is: Apple says resting heart rate "is an estimation of the user's lowest heart rate during periods of rest, and is intended to be used as a medically relevant metric." So on iOS the value is an estimate by Apple's own description, even though the parent metric, heart rate, is measured.

Second, on how it differs from a quiet moment: "A resting heart rate sample is different than a sedentary heart rate sample," meaning an ordinary heartRate sample whose motion context is HKHeartRateMotionContext.sedentary. Apple's example is the user who finishes a high-intensity workout and sits down: the next sample may be marked sedentary, "but it is still much higher than the user's actual resting heart rate." To get a better answer, "the system estimates the resting heart rate by analyzing sedentary heart rate samples throughout the day."

Third, and this is the sentence that breaks naive sync code: "Because the resting heart rate estimates become more accurate as the day progresses, the system may delete earlier samples and replace them with better estimates. Apple Watch replaces only the samples written by the watch for the current or previous day."

The motion context that feeds this is itself documented on the heartRate page. Apple Watch sets HKHeartRateMotionContext.sedentary when the user has been still for at least five minutes before the sample and .active when the user is in motion; not every sample carries the key, and samples from a first-generation Apple Watch or watchOS 3 and earlier never do, so Apple says to treat those as .notSet. Any app can write heart rate samples with or without the key. Our HealthKit vital signs reference lists the identifier beside the rest of the heart group. The group's three event types, for high heart rate, low heart rate and irregular rhythm, date from iOS 12.2; the HealthKit types introduced in iOS 12 lists them.

Health Connect: an integer somebody wrote#

Google documents RestingHeartRateRecord as a class that "Captures the user's resting heart rate. Each record represents a single instantaneous measurement." It sits in the Vitals category as an instantaneous record, added in connect-client 1.1.0, with beatsPerMinute, metadata and time as its mandatory fields and a nullable zoneOffset. Reads and writes are gated on android.permission.health.READ_RESTING_HEART_RATE and android.permission.health.WRITE_RESTING_HEART_RATE.

The value is a Long, documented as "Heart beats per minute. Required field. Validation range: 1-300." That is all the reference says about the number. There is no description of how a resting value is derived, no reference to HeartRateRecord, and no motion context. Google's vitals guide adds only that the record "Represents a single measurement of resting heart rate." Our generated RestingHeartRateRecord reference carries the full field list and the aggregate metrics.

Read that silence literally. Health Connect does not say it produces resting heart rate for you, so the presence of a record means some app with the write permission, a watch vendor's companion app for example, decided on a number and stored it. Whether that number came from an overnight minimum, a morning reading or a rolling estimate is the writing app's business, and the only place it might say so is metadata. Our page on recording method metadata covers what that field can and cannot tell you.

Where you can get it#

Syncing it without keeping stale values#

On iOS the deletion behaviour decides your query class. A one-shot sample query copies whatever estimate exists at that moment, and if Apple later replaces it your copy is now wrong with no signal that it is. HKAnchoredObjectQuery is the class that reports deleted objects as well as new samples, so it is the one to use; treat today's and yesterday's resting values as provisional and apply the deletions it hands you. Values older than that are, by Apple's statement, no longer rewritten by the watch, though another app could still delete its own.

On Android there is no documented rewrite, but there is also no documented author. If you want one number per day, decide whether that is the latest record, the minimum, or BPM_AVG over the day, and say which in the UI. Our aggregate request page covers the mechanics; the record's own zoneOffset is nullable, and the reference says queries with user-experienced time filters assume the current system offset when it is absent, so a traveller's morning value can land on the wrong local day.

The traps#

• Two definitions, one label. HealthKit's value is an estimate the system computes from sedentary samples and revises. Health Connect's is a number an app wrote, with no derivation documented. Do not normalise them into one field without recording which store it came from.
• Yesterday can change. Apple documents replacement of watch-written samples for the current or previous day. Any "resting heart rate this morning" notification you send from the first value of the day is quoting a draft.
• Sedentary is not resting. A heartRate sample with .sedentary motion context is the raw material, not the answer. Apple's post-workout example shows how far apart the two can be.
• Integer versus double. beatsPerMinute is a Long with a documented range of 1 to 300; restingHeartRate is a count/time quantity whose HKUnit you choose. Rounding and range filtering are yours to do, and a zero on Android is outside the documented range rather than a quiet null.
• No value without a writer. On Android, a user whose watch vendor does not write RestingHeartRateRecord has no resting heart rate at all, however many HeartRateRecord samples exist. Design the empty state before the chart.
• History and background need their own permissions. Reading more than 30 days back requires READ_HEALTH_DATA_HISTORY, declared separately from the data-type permission, and background reads need their own grant too.

Keep the claims where the docs put them#

Apple's description, "intended to be used as a medically relevant metric," is a statement about the type, not a licence for your copy. A trend line labelled as the platform's estimate stays on the wellness side; thresholds, alerts and interpretation move the product toward the line our FDA fitness app regulation page describes, and which store the number came from does not change that. Nothing here is medical or legal advice.

Before you ship#

Re-verify the identifier, the record's fields and validation range, and the permission strings against the live Apple and Google references, since all of them move. On iOS, sync with an anchored query and honour deletions. On Android, record the writing app from metadata and name it in the UI. For any vendor field, confirm the window the value is computed over in that vendor's own data dictionary rather than inferring it from the name.