Health Metrics

Health metrics represent the various measurements and data points collected by your Apple Health app and connected devices. In JSON exports, health metrics are stored in the metrics array.

Metric Name Format

All metric names in JSON exports use snake_case format (lowercase with underscores). For example:

• "Step Count" becomes "step_count"
• "Blood Pressure" becomes "blood_pressure"
• "Heart Rate" becomes "heart_rate"
• "Walking + Running Distance" becomes "walking_running_distance"

Structure

The metrics array contains objects, each representing a specific health metric type. Most health metrics follow a common structure:

{
  "name": "step_count",
  "units": "count",
  "data": [
    {
      "qty": 8500,
      "date": "2024-02-06 14:30:00 -0800"
    }
  ]
}

Common Fields

• name (String): The name of the health metric in snake_case format (e.g., "step_count", "heart_rate", "active_energy")
• units (String): The unit of measurement (e.g., "count", "bpm", "kcal")
• data (Array): An array of data points, each containing:
  • qty (Number): The quantity value
  • date (Date): Timestamp in format yyyy-MM-dd HH:mm:ss Z

Special Metric Formats

Some health metrics have unique structures that differ from the common format:

Blood Pressure

Blood pressure readings include both systolic and diastolic values:

{
  "name": "blood_pressure",
  "units": "mmHg",
  "data": [
    {
      "date": "2024-02-06 14:30:00 -0800",
      "systolic": 120,
      "diastolic": 80
    }
  ]
}

Fields:

• systolic (Number): The systolic (upper) blood pressure reading
• diastolic (Number): The diastolic (lower) blood pressure reading

Heart Rate

Heart rate data includes minimum, average, and maximum values:

{
  "name": "heart_rate",
  "units": "bpm",
  "data": [
    {
      "date": "2024-02-06 14:30:00 -0800",
      "Min": 65,
      "Avg": 72,
      "Max": 85
    }
  ]
}

Fields:

• Min (Number): Minimum heart rate during the measurement period
• Avg (Number): Average heart rate during the measurement period
• Max (Number): Maximum heart rate during the measurement period

Sleep Analysis

Sleep data structure varies depending on whether data aggregation is enabled in your export settings.

Aggregated Sleep Data

When aggregation is enabled, sleep data is summarized by day:

{
  "name": "sleep_analysis",
  "units": "hr",
  "data": [
    {
      "date": "2024-02-06",
      "totalSleep": 7.5,
      "asleep": 7.0,
      "core": 3.5,
      "deep": 1.5,
      "rem": 2.0,
      "sleepStart": "2024-02-05 23:00:00 -0800",
      "sleepEnd": "2024-02-06 06:30:00 -0800",
      "inBed": 8.0,
      "inBedStart": "2024-02-05 22:45:00 -0800",
      "inBedEnd": "2024-02-06 06:45:00 -0800"
    }
  ]
}

Fields:

• totalSleep (Number): Total time asleep in hours
• asleep (Number): Total time in any sleep state
• core (Number): Core sleep duration in hours
• deep (Number): Deep sleep duration in hours
• rem (Number): REM sleep duration in hours
• sleepStart (Date): When sleep actually started
• sleepEnd (Date): When sleep actually ended
• inBed (Number): Total time in bed in hours
• inBedStart (Date): When you got into bed
• inBedEnd (Date): When you got out of bed

Unaggregated Sleep Data

When aggregation is disabled, individual sleep segments are included:

{
  "name": "sleep_analysis",
  "units": "hr",
  "data": [
    {
      "startDate": "2024-02-05 23:00:00 -0800",
      "endDate": "2024-02-05 23:30:00 -0800",
      "qty": 0.5,
      "value": "Core",
      "deep": 0.0,
      "rem": 0.0,
      "sleepStart": "2024-02-05 23:00:00 -0800",
      "sleepEnd": "2024-02-06 06:30:00 -0800",
      "inBed": 8.0,
      "inBedStart": "2024-02-05 22:45:00 -0800",
      "inBedEnd": "2024-02-06 06:45:00 -0800"
    }
  ]
}

Fields:

• startDate (Date): Start time of the sleep segment
• endDate (Date): End time of the sleep segment
• qty (Number): Duration of the segment in hours
• value (String): Sleep state - one of:
  • "Awake"
  • "Asleep" (uncategorized sleep phase)
  • "In Bed"
  • "Core"
  • "REM"
  • "Deep"
  • "Unspecified"

Note: "Asleep" refers to an uncategorized sleep phase (rather than total time asleep). This may occur if the data source does not support sleep phase tracking.

Blood Glucose

Blood glucose readings include meal timing information:

{
  "name": "blood_glucose",
  "units": "mg/dL",
  "data": [
    {
      "date": "2024-02-06 08:00:00 -0800",
      "qty": 95,
      "mealTime": "Before Meal"
    }
  ]
}

Fields:

• qty (Number): Blood glucose level
• mealTime (String): One of:
  • "Before Meal"
  • "After Meal"
  • "Unspecified"

Sexual Activity

Sexual activity entries track protection usage:

{
  "name": "sexual_activity",
  "units": "count",
  "data": [
    {
      "date": "2024-02-06 20:00:00 -0800",
      "Unspecified": 0,
      "Protection Used": 1,
      "Protection Not Used": 0
    }
  ]
}

Fields:

• Unspecified (Number): Count when protection status is unknown
• Protection Used (Number): Count when protection was used
• Protection Not Used (Number): Count when protection was not used

Handwashing

Handwashing events track completion status:

{
  "name": "handwashing",
  "units": "count",
  "data": [
    {
      "date": "2024-02-06 12:00:00 -0800",
      "qty": 1,
      "value": "Complete"
    }
  ]
}

Fields:

• qty (Number): Number of handwashing events
• value (String): One of:
  • "Complete"
  • "Incomplete"

Toothbrushing

Toothbrushing events track completion status:

{
  "name": "toothbrushing",
  "units": "count",
  "data": [
    {
      "date": "2024-02-06 08:00:00 -0800",
      "qty": 1,
      "value": "Complete"
    }
  ]
}

Fields:

• qty (Number): Number of toothbrushing events
• value (String): One of:
  • "Complete"
  • "Incomplete"

Insulin Delivery

Insulin delivery entries include the reason for delivery:

{
  "name": "insulin_delivery",
  "units": "IU",
  "data": [
    {
      "date": "2024-02-06 08:00:00 -0800",
      "qty": 5,
      "reason": "Bolus"
    }
  ]
}

Fields:

• qty (Number): Amount of insulin delivered
• reason (String): One of:
  • "Bolus" (mealtime insulin)
  • "Basal" (background insulin)

Common Health Metrics

Some commonly exported health metrics include (all metric names are in snake_case format):

• step_count - Daily step counts
• walking_running_distance - Distance covered
• active_energy - Calories burned through activity
• resting_heart_rate - Heart rate at rest
• heart_rate - Heart rate measurements
• respiratory_rate - Breathing rate
• body_temperature - Body temperature readings
• blood_oxygen_saturation - SpO2 levels
• weight_&_body_mass - Body weight measurements
• body_mass_index - Calculated BMI values
• height - Height measurements
• dietary_water - Fluid consumption
• mindful_minutes - Meditation or mindfulness time

Tips

• Time Grouping: Use time grouping settings in your export configuration to control how data is aggregated (by second, minute, hour, day, etc.)
• Data Aggregation: Enable data aggregation to summarize sleep and other metrics by day for easier analysis
• Selective Export: You can choose which specific health metrics to include in your export to reduce file size and processing time

Related Documentation

• JSON Export Format Overview
• Manual Export Guide
• Automations Overview