ECG API: Electrocardiogram and Irregular Rhythm Data

This is the most clinical data a consumer health API returns, and every platform that has it treats it that way. Google flags both of its types as software-as-a-medical-device output and offers no write operation for either. Apple marks both of its identifiers read-only. Nobody lets a third-party app put an ECG or an arrhythmia alert into the store, which tells you what your app's role is: reading and displaying a result someone else's regulated feature produced.

What each platform exposes#

The HealthKit ECG row rests on one sentence. Apple documents the metadata key HKMetadataKeyAppleECGAlgorithmVersion with "Apple Watch sets this key on the HKElectrocardiogram samples it creates. The key is read-only." Our HealthKit query predicates page also lists an electrocardiogram(_:) sample-predicate factory method. Nothing in this site's generated identifier data describes the sample's fields, so this page does not.

Google's ECG record#

Google describes electrocardiogram as "an Electrocardiogram (ECG) measurement session." The fields, all from the v4 discovery document:

• waveformSamples: "An array of voltage values representing lead I ECG values," where "The first value in array corresponds to the start of the reading."
• samplingFrequencyHertz: the sampling frequency of those samples.
• millivoltsScalingFactor: the divisor that turns a sample into a voltage, which Google writes as millivolts = waveform_sample / millivolts_scaling_factor.
• leadNumber: the number of leads used.
• beatsPerMinuteAvg: the average heart rate during the reading.
• resultClassification: one of NORMAL_SINUS_RHYTHM, ATRIAL_FIBRILLATION, INCONCLUSIVE, INCONCLUSIVE_HIGH_HEART_RATE, INCONCLUSIVE_LOW_HEART_RATE, UNREADABLE, NOT_ANALYZED or unspecified. Google's text for the two heart-rate results gives its cut-offs as >120bpm and <50bpm.
• medicalDeviceInfo: output-only metadata that, for ECG, typically populates the firmware version, feature version and device model. Google describes the schema as "Software as Medical Device (SaMD) metadata. Used to construct the Unique Device Identifier (UDI)."

Two notes on time are easy to miss. The interval's start and end are equal, "representing the reading time." And "Historical ECG data lacks timezone offsets," so the offsets "will be missing or default to zero" and the civil time fields "will default to UTC"; Google recommends the physical time fields instead. A reading taken in the evening in Los Angeles can therefore show the next day if you group by civil date.

Google's table lists eight compatible devices for the type, including Fitbit Charge 5 and 6, Fitbit Sense and Sense 2, and Pixel Watch through Pixel Watch 4. Its Fitbit migration table maps the Fitbit Web API's ECG data to it.

Irregular rhythm notifications#

Google describes irregular-rhythm-notification as "an Irregular Rhythm Notification alert, indicating a potential sign of atrial fibrillation (AFib)." Beyond its interval and device metadata it carries alertWindows, "The overlapping analysis windows that were used to evaluate rhythm for potential AFib." Each window has its own start and end with UTC offsets, the heartbeats it contained, and a positive flag, and Google's note on the window schema is worth quoting whole: "The current version of the algorithm will only produce alerts if all windows are positive. So anything returned from the API will always have the positive bit set to true." The flag's own description adds that false "does not guarantee the absence of AFib."

HealthKit's nearest types carry far less. irregularHeartRhythmEvent is "A category sample type for irregular heart rhythm events," whose values come from the generic HKCategoryValue rather than an enum of its own, so a sample tells you that an event happened and when, as our HKCategoryValue reference explains for every type that resolves that way. Apple adds: "The irregular rhythm samples are read-only." atrialFibrillationBurden is a different measurement altogether: "an estimate of the percentage of time a person’s heart shows signs of atrial fibrillation (AFib) while wearing Apple Watch," in percentage units, discrete, read-only, from iOS 16.0. It is a summary percentage, not an alert, so it does not map onto Google's notification type.

Scopes and access#

The Google Health API reads these types under their own scopes: .ecg.readonly, whose consent text is "See your Google Health ECG data.", and .irn.readonly, "See your Google Health Irregular Rhythm Notifications data." Google's Scopes page lists no write scope for either family, the data-types table lists only list for both, and it marks neither with webhook support, so you poll. The scopes reference lists every family, and access and limits covers Google's OAuth app verification and the cap on unverified apps.

On iOS both identifiers are read-only by Apple's statement, so the authorization you request is read access only.

Android has no on-device route#

Health Connect's data-types table has no ECG or rhythm record, and Wear OS Health Services defines no such data type. Pixel Watch models appear in the Google Health API's compatible-device list for electrocardiogram, so on the evidence this site holds, an Android app reaches Pixel Watch ECG data through the Google Health API's cloud endpoints rather than on the device.

Keep the claims where the data puts them#

Google ties both types to a SaMD feature and says changes to them "may require additional review." Apple marks its types read-only. Our recommendation follows from that: show the classification, the alert and the burden percentage as the platform labels them, credit the platform, and do not compute a rhythm classification of your own from the waveform. Our heart rate API guide makes the same point about ordinary heart rate samples, and the FDA fitness app regulation page sets out where interpretation turns an app into a medical device. Nothing here is medical advice.

Before you ship#

Re-read the two Google type pages and the two HealthKit identifier pages before each release, since they regenerate from Google's and Apple's documentation. Use physical time for ECG readings. Treat every returned alert window as positive by Google's own note, and never present a missing alert as a clean result.