normogen/thoughts/research/2026-01-05-mobile-health-frameworks-data.md

---
date: 2026-01-05T20:27:17-03:00
git_commit: N/A (not a git repository)
branch: N/A
repository: normogen
topic: "Mobile Health Frameworks - Available Data Types"
tags: [research, healthkit, health-connect, mobile-integration, data-types]
status: complete
---

# Research: Mobile Health Frameworks Data Availability

## Research Question
What health data can be accessed from mobile phone health frameworks (Apple HealthKit and Google Health Connect) with proper application permissions?

## Summary

**Key Finding:** Both iOS and Android provide comprehensive access to health data through their respective frameworks (HealthKit and Health Connect). With proper permissions, applications can access **50+ different health data types** including body measurements, vitals, activity, sleep, nutrition, and reproductive health.

**Platform Coverage:**
- **Apple HealthKit (iOS):** 9 major categories, 50+ data types
- **Google Health Connect (Android):** 8 major categories, 45+ data types
- **Common to Both:** ~15 core data types with overlap

**User Control:** Both platforms require explicit user permission for each data category, with granular controls and easy revocation.

---

## Apple HealthKit (iOS)

### Data Categories Available

#### 1. Body Measurements
With basic permissions:
- **Weight** - kg, lbs
- **Height** - cm, in, ft
- **Body Mass Index (BMI)** - calculated
- **Body Fat Percentage** - %age
- **Lean Body Mass** - kg, lbs

#### 2. Vitals (Requires Special Permissions)
- **Heart Rate** - beats per minute (BPM)
- **Resting Heart Rate** - BPM
- **Blood Pressure** - systolic/diastolic (mmHg)
- **Body Temperature** - °C, °F
- **Respiratory Rate** - breaths per minute
- **Oxygen Saturation (SpO2)** - percentage
- **Blood Glucose** - mg/dL, mmol/L

#### 3. Fitness & Activity
- **Step Count** - daily/total steps
- **Distance Walking/Running** - km, mi
- **Flights Climbed** - count
- **Active Energy Burned** - kcal
- **Basal Energy Burned** - kcal/day
- **Exercise Duration** - minutes/hours
- **Workouts** - type, duration, calories, route

#### 4. Sleep Analysis
- **Sleep Duration** - total time asleep
- **Time in Bed** - total time in bed
- **Sleep Stages** - in bed, asleep, awake
- **Sleep Quality** - REM, light, deep sleep

#### 5. Mobility
- **Walking Speed** - m/s
- **Walking Asymmetry** - percentage
- **Walking Steadiness** - score
- **Step Length** - cm, in

#### 6. Nutrition
- **Dietary Energy** - calories
- **Macronutrients** - carbs, protein, fat (total, saturated, unsaturated)
- **Fiber** - grams
- **Sugar** - grams
- **Sodium** - milligrams
- **Water Intake** - liters, cups, ounces
- **Vitamins & Minerals** - various (A, C, D, iron, calcium, etc.)

#### 7. Reproductive Health
- **Menstrual Flow** - light, medium, heavy
- **Basal Body Temperature** - °C, °F
- **Cervical Mucus Quality** - type and amount
- **Ovulation Test Result** - positive/negative
- **Sexual Activity** - protected/unprotected
- **Spotting** - yes/no

#### 8. Medical Records & Labs (Clinical Data)
- **Allergy Records** - allergen, severity, reaction
- **Condition Records** - diagnosis, status
- **Immunization Records** - vaccine, date
- **Lab Result Records** - test name, result, unit, reference range
- **Medication Records** - name, dosage, frequency
- **Procedure Records** - procedure, date, outcome
- **Vital Signs Records** - clinical measurements

#### 9. Apple Watch Specific Data
- **ECG Results** - ECG readings and classifications
- **AFib Detection** - atrial fibrillation notifications
- **Fall Detection** - fall events
- **Noise Levels** - environmental sound exposure
- **Headphone Audio Levels** - audio exposure

### Permission Requirements

**Info.plist Required Entries:**
```xml
<key>NSHealthShareUsageDescription</key>
<string>We need access to your health data to track and analyze your wellness metrics.</string>

<key>NSHealthUpdateUsageDescription</key>
<string>We need permission to save health data to your Health app.</string>
```

**Entitlements Required:**
- HealthKit capability in Xcode project settings
- Special entitlements for clinical data access

**User Permissions:**
- User must explicitly grant permission for each data category
- Prompts shown at first access to each category
- User can revoke permissions in Settings > Health > Data Access & Devices
- Clinical data requires additional user consent

**Metadata Available:**
- **Timestamp:** Start and end time (millisecond precision)
- **Device:** Source device (iPhone, Apple Watch, third-party app)
- **Units:** Always included with proper conversions
- **Provenance:** Which app/device provided the data
- **Accuracy:** For sensor-based measurements
- **User Notes:** Optional user-created annotations

---

## Google Health Connect (Android)

### Data Types Available

#### 1. Activity & Exercise
- **Steps** - count
- **Distance** - meters, kilometers, miles
- **Floors** - count
- **Elevation** - meters, feet
- **Exercise Sessions** - type (running, walking, cycling, etc.), duration, calories
- **Swimming** - strokes, laps, distance
- **Wheelchair Pushes** - count
- **Golf Swings** - count (for supported apps)

#### 2. Body Measurements
- **Weight** - kg, lbs
- **Height** - meters, centimeters, feet, inches
- **Body Fat** - percentage
- **Basal Metabolic Rate** - kcal/day
- **Body Water Mass** - kg
- **Bone Mass** - kg
- **Lean Body Mass** - kg

#### 3. Vitals
- **Heart Rate** - BPM
- **Resting Heart Rate** - BPM
- **Heart Rate Variability** - milliseconds
- **Blood Pressure** - systolic/diastolic in mmHg
- **Oxygen Saturation (SpO2)** - percentage
- **Body Temperature** - °C, °F
- **Respiratory Rate** - breaths/minute

#### 4. Sleep
- **Sleep Sessions** - start time, end time, total duration
- **Sleep Stages** - awake, REM, light, deep sleep with durations
- **Sleep Latency** - time to fall asleep

#### 5. Nutrition
- **Hydration** - volume in mL, oz, cups
- **Nutrition** - calories, macronutrients, micronutrients
- **Meal Information** - meal type (breakfast, lunch, dinner, snack)

#### 6. Cycle Tracking
- **Menstruation Flow** - flow amount and type
- **Menstruation Period** - start and end dates
- **Ovulation** - positive, negative, test result
- **Cervical Mucus** - type and quantity
- **Sexual Activity** - protection status
- **Spotting** - yes/no

#### 7. Clinical Data
- **Blood Glucose** - mg/dL, mmol/L
- **Lab Test Results** - similar to Apple HealthKit

#### 8. Physical Activity Details
- **Exercise Type** - running, walking, cycling, swimming, etc.
- **Exercise Duration** - time in minutes/hours
- **Exercise Calories** - kcal burned
- **Exercise Route** - GPS data path (if available)

### Permission Requirements

**AndroidManifest.xml:**
```xml
<uses-permission android:name="android.permission.health.READ_HEALTH_DATA" />
<uses-permission android:name="android.permission.health.WRITE_HEALTH_DATA" />
```

**Runtime Permissions:**
- Granular permission requests per data type
- User approves each category individually
- Health Connect app must be installed on device
- User can manage permissions in Health Connect app

**Requirements:**
- Android API level 34+ (Android 14) recommended
- Health Connect Jetpack library
- Google Play Services (on Play Store devices)
- User consent for each data type read

**Metadata Available:**
- **Timestamps:** Start and end time (millisecond precision)
- **Device/Source:** Which app or device provided data
- **Accuracy:** Measurement precision
- **Units:** Always included
- **Entry Method:** Manual vs automatic/sensor

---

## Cross-Platform Comparison

### Common Data Types (Both Platforms)
These data types are available on both iOS and Android with consistent structure:

| Data Type | Apple HealthKit | Google Health Connect | Notes |
|-----------|----------------|----------------------|-------|
| **Weight** | ✓ | ✓ | Both support kg/lbs |
| **Height** | ✓ | ✓ | Both support metric/imperial |
| **Steps** | ✓ | ✓ | Daily count and historical |
| **Distance** | ✓ | ✓ | Walking/running distance |
| **Heart Rate** | ✓ | ✓ | BPM, resting HR, HRV |
| **Blood Pressure** | ✓ | ✓ | Systolic/diastolic |
| **Sleep** | ✓ | ✓ | Duration, stages |
| **Active Energy** | ✓ | ✓ | Calories burned |
| **Body Temperature** | ✓ | ✓ | °C/°F |
| **Blood Glucose** | ✓ | ✓ | mg/dL, mmol/L |
| **Respiratory Rate** | ✓ | ✓ | Breaths per minute |
| **SpO2** | ✓ | ✓ | Oxygen saturation |
| **Nutrition** | ✓ | ✓ | Calories, macros, hydration |
| **Exercise** | ✓ | ✓ | Type, duration, calories |
| **Body Fat %** | ✓ | ✓ | Percentage |

### Platform-Specific Features

**Apple-Only:**
- ECG measurements (Apple Watch)
- Atrial fibrillation detection
- Walking steadiness/asymmetry metrics
- Environmental sound levels
- More detailed mobility analysis
- Integration with Apple ecosystem (Watch, iPad, Mac)

**Android-Only:**
- More granular exercise types
- Broader device ecosystem (Samsung, Fitbit, Garmin, etc.)
- More flexible third-party app integrations
- Earlier API access for some features

### Unit Conversions
Both platforms handle units automatically:

| Measurement | iOS Units | Android Units | Notes |
|------------|-----------|---------------|-------|
| Weight | kg, lbs | kg, lbs | 1 kg = 2.20462 lbs |
| Height | cm, in | cm, in, ft+in | 1 in = 2.54 cm |
| Temperature | °C, °F | °C, °F | °F = (°C × 9/5) + 32 |
| Glucose | mg/dL, mmol/L | mg/dL, mmol/L | mg/dL = mmol/L × 18.02 |
| Distance | km, mi | km, mi | 1 mi = 1.60934 km |

### Time Precision
- **Apple:** Millisecond precision (Unix timestamp)
- **Android:** Millisecond precision (Unix timestamp)
- **Both:** Support historical queries with date ranges
- **Best Practice:** Store all timestamps in UTC on server

---

## Integration Complexity Assessment

### Apple HealthKit

**Complexity:** ⭐⭐⭐ (Medium - 3/5)

**Advantages:**
- Mature, stable framework (since iOS 8)
- Excellent documentation (with Apple Developer account)
- Strong type safety with Swift
- Consistent API across iOS versions
- Good debugging tools in Xcode
- Deep integration with Apple Watch

**Challenges:**
- Requires Mac for development
- Requires Xcode
- Simulator has limited HealthKit support
- Testing on physical device required
- Some features require Apple Developer Program ($99/year)

**Development Requirements:**
- macOS with Xcode
- iOS deployment target: iOS 13+ (for full features)
- Swift or Objective-C
- HealthKit framework entitlement

### Google Health Connect

**Complexity:** ⭐⭐⭐⭐ (Medium-High - 4/5)

**Advantages:**
- Modern, actively developed framework
- Centralizes data from all health apps
- Cross-app data sharing
- User privacy controls
- Works on wide range of devices

**Challenges:**
- Newer framework (introduced 2023, replacing Google Fit)
- Documentation still evolving
- Android version compatibility (API 34+ recommended)
- Device fragmentation (different OEM implementations)
- Health Connect app must be installed separately
- More complex testing matrix (device/OS combinations)

**Development Requirements:**
- Android Studio
- Minimum SDK: API 26 (Android 8) with compatibility layer
- Recommended SDK: API 34 (Android 14) for full features
- Kotlin or Java
- Health Connect Jetpack library
- Google Play Services (optional but recommended)

---

## Recommended MVP Integration Strategy

### Phase 1: Manual Entry (Current MVP Scope)
**Timeline:** Week 1-4
**Features:**
- Manual entry of weight, height
- Manual entry of basic vitals (heart rate, blood pressure, temperature)
- Web-based interface only
- No mobile integration yet

### Phase 2: Mobile Foundation
**Timeline:** Week 5-8
**Features:**
- Build basic iOS and Android apps
- Implement authentication
- Manual data entry on mobile
- Sync with server

### Phase 3: Health Framework Integration
**Timeline:** Week 9-12
**Features:**
- Implement HealthKit on iOS
- Implement Health Connect on Android
- Support top 5 most important data types:
  1. Weight
  2. Heart Rate
  3. Blood Pressure
  4. Sleep (duration)
  5. Steps (count)
- Background sync every 15-30 minutes
- Historical data import (last 30 days)

### Phase 4: Expanded Data Types
**Timeline:** Week 13-16
**Features:**
- Add all common data types
- Support for exercise tracking
- Nutrition tracking
- Advanced sleep analysis
- Menstrual cycle tracking

---

## Data Model Recommendations

### Enhanced health_metrics Table

```sql
ALTER TABLE health_metrics ADD COLUMN metric_source VARCHAR(50) 
  CHECK (metric_source IN ('manual', 'healthkit', 'healthconnect', 'third_party_device', 'unknown'));

ALTER TABLE health_metrics ADD COLUMN source_device_id VARCHAR(255);
  -- Stores identifier for source device/app (e.g., "com.apple.health.Health", "com.fitbit.FitbitMobile")

ALTER TABLE health_metrics ADD COLUMN accuracy DECIMAL(5,2);
  -- Sensor accuracy for automatic measurements (0.0-1.0, where 1.0 = perfect)

ALTER TABLE health_metrics ADD COLUMN metadata JSONB;
  -- Flexible storage for platform-specific data:
  -- iOS: {"HKDevice": "iPhone14,2", "HKSource": "com.apple.Health"}
  -- Android: {"device": "Samsung Galaxy S21", "package": "com.sec.android.app.health"}
```

### New Table: health_metric_sources
```sql
CREATE TABLE health_metric_sources (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    platform VARCHAR(20) NOT NULL, -- 'ios' or 'android'
    device_name VARCHAR(255),
    source_bundle_id VARCHAR(255), -- App/package ID
    first_sync TIMESTAMP DEFAULT NOW(),
    last_sync TIMESTAMP DEFAULT NOW(),
    is_active BOOLEAN DEFAULT TRUE,
    
    UNIQUE(user_id, platform, source_bundle_id)
);

CREATE INDEX idx_metric_sources_user ON health_metric_sources(user_id);
```

### New Table: sync_history
```sql
CREATE TABLE sync_history (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    platform VARCHAR(20) NOT NULL,
    sync_type VARCHAR(50) NOT NULL, -- 'initial', 'incremental', 'manual'
    records_imported INTEGER DEFAULT 0,
    records_failed INTEGER DEFAULT 0,
    sync_duration_seconds INTEGER,
    error_message TEXT,
    synced_from TIMESTAMP,
    synced_to TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_sync_history_user ON sync_history(user_id, created_at DESC);
```

---

## Sync Strategy

### Initial Sync (First Connection)
When user first connects health framework:
1. Request last 30 days of data (common window)
2. Import in batches to avoid overwhelming server
3. Show progress to user
4. Handle errors gracefully
5. Store sync timestamp for incremental updates

### Incremental Sync (Background)
Every 15-30 minutes:
1. Query for new data since last sync
2. Send new records to server
3. Handle conflicts (same metric, multiple sources)
4. Update last sync timestamp

### Conflict Resolution Strategy
When same metric type exists from multiple sources:
1. **Automatic Entry** (sensor/device) > **Manual Entry**
2. **More Recent** > **Older** (for time-series data)
3. **More Accurate** > **Less Accurate** (based on metadata)
4. **User Preference** (if user sets preferred source)

### Battery Optimization
- Limit sync frequency when battery < 20%
- Use WorkManager (Android) and Background Tasks (iOS)
- Batch requests to minimize wake-ups
- Sync only when on Wi-Fi (user preference)
- Respect battery saver mode

---

## Security & Privacy Considerations

### Data Transmission
- **Always use HTTPS** (TLS 1.3)
- **Encrypt sensitive data** at REST on server
- **Never store credentials** on device (use tokens)
- **Certificate pinning** for API calls

### Data Storage
- **Encrypt at rest** using database encryption
- **Separate encryption keys** per user
- **No plaintext passwords** (bcrypt/scrypt/Argon2)
- **Secure key derivation** for data access

### User Privacy
- **Clear permission requests** explaining why data is needed
- **Granular controls** - user chooses what to share
- **Easy data deletion** - "nuke option" from intro.md
- **No data sharing** with third parties without explicit consent
- **Transparent data usage** - show user what's stored

### Compliance
- **GDPR** (Europe)
- **HIPAA** (if handling protected health information in US)
- **CCPA** (California)
- **App Store Review Guidelines** (Apple)
- **Google Play Policy** (Android)

---

## Open Questions & Further Research

### Priority 1 (MVP Blocking)
1. **Conflict Resolution Algorithm**
   - What if user manually enters weight but scale also sent data?
   - Need comprehensive conflict resolution policy

2. **Background Sync Optimization**
   - Optimal sync interval for battery vs data freshness
   - How to handle offline scenarios

3. **Data Retention Policy**
   - How long to keep historical data?
   - Should old data be archived or deleted?

### Priority 2 (Post-MVP)
4. **Third-Party Device Integration**
   - Fitbit, Garmin, Oura Ring, Whoop, etc.
   - Each requires separate API integration

5. **Data Export Format**
   - What format for user downloads?
   - JSON, CSV, FHIR (HL7), or custom?

6. **Advanced Analytics**
   - Trends, correlations, predictions
   - Privacy-preserving computations?

7. **Cross-Platform Sync**
   - What if user has both iOS and Android devices?
   - How to merge data from both?

### Priority 3 (Future)
8. **Real-Time Monitoring**
   - Live heart rate, blood glucose alerts?
   - Push notification strategy

9. **Data Visualization**
   - Charts, graphs, heatmaps
   - What library to use?

10. **International Units**
    - Automatic unit conversion based on user location?
    - Support for medical vs customary units?

---

## Implementation Checklist

### Pre-Development
- [ ] Finalize data model with source tracking
- [ ] Design conflict resolution algorithm
- [ ] Create API endpoints for bulk data import
- [ ] Set up database encryption

### iOS Development
- [ ] Add HealthKit capability in Xcode
- [ ] Write permission request code
- [ ] Implement HealthKit queries for top 5 data types
- [ ] Implement background sync with BGTaskScheduler
- [ ] Test on physical device (simulator has limited support)

### Android Development
- [ ] Add Health Connect dependencies
- [ ] Add permissions to AndroidManifest
- [ ] Write permission request code
- [ ] Implement Health Connect queries for top 5 data types
- [ ] Implement background sync with WorkManager
- [ ] Test on multiple Android versions/devices

### Backend Development
- [ ] Create bulk import API endpoints
- [ ] Implement conflict resolution logic
- [ ] Add sync history tracking
- [ ] Optimize database indexes for time-series queries
- [ ] Implement data deletion endpoint ("nuke")

### Testing
- [ ] Unit tests for data parsing
- [ ] Integration tests for sync logic
- [ ] Manual testing on physical devices
- [ ] Battery usage profiling
- [ ] Security audit
- [ ] Load testing with thousands of records

---

## Conclusion

**Feasibility:** ✅ **Highly Feasible**

Both mobile platforms provide robust, well-documented frameworks for health data access. The integration is straightforward for common data types (weight, height, heart rate, blood pressure, sleep, steps).

**Recommendation for MVP:**
- Start with **Phase 1** (manual entry) to validate core architecture
- Move to **Phase 2** (mobile apps) for basic platform functionality
- Implement **Phase 3** (health frameworks) with top 5 data types
- Expand in **Phase 4** based on user feedback

**Timeline Estimate:**
- Phase 1: 4 weeks (manual entry web app)
- Phase 2: 4 weeks (mobile app foundation)
- Phase 3: 4 weeks (health framework integration)
- Phase 4: 4 weeks (expanded data types)

**Total to Full Mobile Integration:** ~16 weeks (4 months)

---

## References

### Official Documentation
- [Apple HealthKit Documentation](https://developer.apple.com/documentation/healthkit)
- [Google Health Connect Documentation](https://developer.android.com/health-connect)
- [Apple Human Interface Guidelines - Health](https://developer.apple.com/design/human-interface-guidelines/health)
- [Google Play - Health Apps Policy](https://play.google.com/console/about/health/)

### Data Type References
- [HealthKit HKObjectType Constants](https://developer.apple.com/documentation/healthkit/hkobjecttype)
- [Health Connect Data Types](https://developer.android.com/reference/kotlin/androidx/health/data/class)
- [Common Data Elements - FHIR](https://hl7.org/fhir/observation.html)

### Code Examples
- Apple Sample Code: HKWorkoutSession, HKHealthStore
- Android Sample Code: Health Connect Samples on GitHub

---

**Next Steps:**
1. Review this research with stakeholders
2. Prioritize which data types for MVP
3. Choose mobile development framework (React Native vs native)
4. Begin implementation with Phase 1 (manual entry)