Aggregating data in Health Connect includes basic aggregations or aggregating data into buckets. The following workflows show you how to do both.
Basic aggregation
To use basic aggregation on your data, use the aggregate function
on your HealthConnectClient object. It accepts an
AggregateRequest object where you add the metric types
and the time range as its parameters. How basic aggregates are called depends on
the metric types used.
Cumulative aggregation
Cumulative aggregation computes the total value.
The following example shows you how to aggregate data for a data type:
suspend fun aggregateDistance(
healthConnectClient: HealthConnectClient,
startTime: Instant,
endTime: Instant
) {
try {
val response = healthConnectClient.aggregate(
AggregateRequest(
metrics = setOf(DistanceRecord.DISTANCE_TOTAL),
timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
)
)
// The result may be null if no data is available in the time range
val distanceTotalInMeters = response[DistanceRecord.DISTANCE_TOTAL]?.inMeters ?: 0L
} catch (e: Exception) {
// Run error handling here
}
}
Filter by data origin
You can also filter aggregate data by its origin. For example, only including data written by a specific app.
The following example shows how to use dataOriginFilter and
AggregateRequest to aggregate steps from a specific app:
suspend fun aggregateStepsFromSpecificApp(
healthConnectClient: HealthConnectClient,
startTime: Instant,
endTime: Instant,
appPackageName: String
) {
try {
val response = healthConnectClient.aggregate(
AggregateRequest(
metrics = setOf(StepsRecord.COUNT_TOTAL),
timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
dataOriginFilter = setOf(DataOrigin(appPackageName))
)
)
// The result may be null if no data is available in the time range
val totalSteps = response[StepsRecord.COUNT_TOTAL] ?: 0L
} catch (e: Exception) {
// Run error handling here
}
}
Statistical aggregation
Statistical aggregation computes the minimum, maximum, or average values of records with samples.
The following example shows how to use statistical aggregation:
suspend fun aggregateHeartRate(
healthConnectClient: HealthConnectClient,
startTime: Instant,
endTime: Instant
) {
try {
val response =
healthConnectClient.aggregate(
AggregateRequest(
setOf(HeartRateRecord.BPM_MAX, HeartRateRecord.BPM_MIN),
timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
)
)
// The result may be null if no data is available in the time range
val minimumHeartRate = response[HeartRateRecord.BPM_MIN]
val maximumHeartRate = response[HeartRateRecord.BPM_MAX]
} catch (e: Exception) {
// Run error handling here
}
}
Buckets
Health Connect can also let you aggregate data into buckets. The two types of buckets you can use include duration and period.
Once called, they return a list of buckets. Note that the list can be sparse, so a bucket is not included in the list if it doesn't contain any data.
Duration
In this case, aggregated data is split into buckets within a fixed length of
time, such as a minute or an hour. To aggregate data into buckets, use
aggregateGroupByDuration. It accepts an
AggregateGroupByDurationRequest object where you add the
metric types, the time range, and the Duration as parameters.
The following shows an example of aggregating steps into minute-long buckets:
suspend fun aggregateStepsIntoMinutes(
healthConnectClient: HealthConnectClient,
startTime: LocalDateTime,
endTime: LocalDateTime
) {
try {
val response =
healthConnectClient.aggregateGroupByDuration(
AggregateGroupByDurationRequest(
metrics = setOf(StepsRecord.COUNT_TOTAL),
timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
timeRangeSlicer = Duration.ofMinutes(1L)
)
)
for (durationResult in response) {
// The result may be null if no data is available in the time range
val totalSteps = durationResult.result[StepsRecord.COUNT_TOTAL]
}
} catch (e: Exception) {
// Run error handling here
}
}
Period
In this case, aggregated data is split into buckets within a date-based amount
of time, such as a week or a month. To aggregate data into buckets, use
aggregateGroupByPeriod. It accepts an
AggregateGroupByPeriodRequest object where you add the
metric types, the time range, and the Period as parameters.
The following shows an example of aggregating steps into monthly buckets:
suspend fun aggregateStepsIntoMonths(
healthConnectClient: HealthConnectClient,
startTime: LocalDateTime,
endTime: LocalDateTime
) {
try {
val response =
healthConnectClient.aggregateGroupByPeriod(
AggregateGroupByPeriodRequest(
metrics = setOf(StepsRecord.COUNT_TOTAL),
timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
timeRangeSlicer = Period.ofMonths(1)
)
)
for (monthlyResult in response) {
// The result may be null if no data is available in the time range
val totalSteps = monthlyResult.result[StepsRecord.COUNT_TOTAL]
}
} catch (e: Exception) {
// Run error handling here
}
}
Read restrictions
By default, all applications can read data from Health Connect for up to 30 days prior to when any permission was first granted.
If you need to extend read permissions beyond any of the
default restrictions, request the
PERMISSION_READ_HEALTH_DATA_HISTORY.
Otherwise, without this permission, an attempt to read records older than
30 days results in an error.
Permissions history for a deleted app
If a user deletes your app, all permissions, including the history permission, are revoked. If the user reinstalls your app and grants permission again, the same default restrictions apply, and your app can read data from Health Connect for up to 30 days prior to that new date.
For example, suppose the user deletes your app on May 10, 2023 and then reinstalls the app on May 15, 2023, and grants read permissions. The earliest date your app can now read data from by default is is April 15, 2023.
Aggregate data affected by user-selected apps priorities
End users can set priority for the Sleep and Activity apps that they have integrated with Health Connect. Only end users can alter these priority lists. When you perform an aggregate read, the Aggregate API accounts for any duplicate data and keeps only the data from the app with the highest priority. Duplicate data could exist if the user has multiple apps writing the same kind of data—such as the number of steps taken or the distance covered—at the same time.
For information on how end users can prioritize their apps, see Manage Health Connect data.
The user can add or remove apps as well as change their priorities. A user might want to remove an app that is writing duplicate data so that the data totals on the Health Connect screen are identical to the app they have given the highest priority. The data totals are updated in real time.
Even though the Aggregate API calculates Activity and Sleep apps' data by deduping data according to how the user has set priorities, you can still build your own logic to calculate the data separately for each app writing that data.
Only the Activity and Sleep data types are deduped by Health Connect, and the data totals shown are the values after the dedupe has been performed by the Aggregate API. These totals show the most recent full day where data exists for steps and distance. For other types of apps, the total numbers of all such apps combined are shown in the data totals in Health Connect.
Background reads
You can request that your application run in the background and read data from Health Connect. If you request the Background Read permission, your user can grant your app access to read data in the background.
Supported aggregate data types by record
This table lists all the supported aggregate data types by Health Connect record.