Get access to health information like step count, sleep totals, etc.
The HealthService provides your app access to the step count and sleep activity of the user.
Return the sum of a HealthMetric's values over a time range. The time_start and time_end parameters define the range of time you want the sum for.
The value returned will be an average since midnight, weighted for the length of the specified time range. This may change in the future.
The metric to query for data.
UTC time of the earliest data item to incorporate into the sum.
UTC time of the most recent data item to incorporate into the sum.
The sum of that metric over the given time range, if available.
Return the sum of a HealthMetric's values over a time range. The time_start and time_end parameters define the range of time you want the sum for.
The value returned will be based on daily totals, weighted for the length of the specified time range. This may change in the future.
The metric to query for data.
UTC time of the earliest data item to incorporate into the sum.
UTC time of the most recent data item to incorporate into the sum.
The sum of that metric over the given time range, if available.
Convenience wrapper for health_service_sum() that returns the sum for today.
The metric to query for data.
The sum of that metric's data for today, if available.
Convenience wrapper for health_service_sum() that returns the sum for today.
The metric to query.
The sum of that metric's data for today, if available.
Return the average value of a metric's sum over a given time range between time_start and time_end. Using this call you can specify the time range that you are interested in getting the average for, as well as a scope specifier on how to compute that average. For example, if you want to get the average number of steps taken from 12 AM (midnight) to 9 AM across all days you would specify: time_t time_start = time_start_of_today(), time_t time_end = time_start + (9 * SECONDS_PER_HOUR), and HealthServiceTimeScope scope = HealthServiceTimeScopeDaily. If you want the average number of steps taken on a weekday (Monday to Friday) and today is a Monday (in the local timezone) you would specify: time_start = time_start_of_today(), time_end = time_start + SECONDS_PER_DAY, and scope = HealthServiceTimeScopeDailyWeekdayOrWeekend.
Which HealthMetric to query.
UTC time of the start of the query interval.
UTC time of the end of the query interval.
HealthServiceTimeScope value describing how the average should be computed.
The average of the sum of the given metric over the given time range, if available.
Return the value of a metric's sum over a given time range between time_start and time_end. Using this call you can specify the time range that you are interested in getting the average for, as well as a scope specifier on how to compute an average of the sum. For example, if you want to get the average number of steps taken from 12 AM (midnight) to 9 AM across all days you would specify: time_t time_start = time_start_of_today(); time_t time_end = time_start + (9 * SECONDS_PER_HOUR); HealthValue value = health_service_sum_averaged(HealthMetricStepCount, time_start, time_end, HealthServiceTimeScopeDaily);
If you want the average number of steps taken on a weekday (Monday to Friday) and today is a Monday (in the local timezone) you would specify: time_start = time_start_of_today(); time_end = time_start + SECONDS_PER_DAY; HealthValue value = health_service_sum_averaged(HealthMetricStepCount, time_start, time_end, HealthServiceTimeScopeDailyWeekdayOrWeekend);
Note that this call is the same as calling health_service_aggregate_averaged(metric, time_start, time_end, HealthAggregationSum, scope)
Which HealthMetric to query.
UTC time of the start of the query interval.
UTC time of the end of the query interval.
HealthServiceTimeScope value describing how the average should be computed.
The average of the sum of the given metric over the given time range, if available.
Return a HealthActivityMask containing a set of bits, one set for each activity that is currently active.
A bitmask with zero or more HealthActivityMask bits set as appropriate.
Iterates backwards or forward within a given time span to list all recorded activities. For example, this can be used to find the last recorded sleep phase or all deep sleep phases in a given time range. Any activity that overlaps with time_start and time_end will be included, even if the start time starts before time_start or end time ends after time_end.
A bitmask containing set of activities you are interested in.
UTC time of the earliest time you are interested in.
UTC time of the latest time you are interested in.
The direction in which to iterate.
Developer-supplied callback that is called for each activity iterated over.
Developer-supplied context pointer that is passed to the callback.
Check if a certain combination of metric and time span is accessible by returning a value of HealthServiceAccessibilityMask. Developers should check if the return value is HealthServiceAccessibilityMaskAvailable before calling any other HealthService APIs that involve the given metric.
The metric to query for data.
Earliest UTC time you are interested in.
Latest UTC time you are interested in.
A HealthServiceAccessibilityMask representing the accessible metrics in this time range.
Check if a certain combination of metric and time span is accessible using health_service_sum by returning a value of HealthServiceAccessibilityMask. Developers should check if the return value is HealthServiceAccessibilityMaskAvailable before calling health_service_sum.
Note that this call is the same as calling health_service_metric_averaged_accessible(metric, time_start, time_end, HealthServiceTimeScopeOnce)
The metric to query for data.
Earliest UTC time you are interested in.
Latest UTC time you are interested in.
A HealthServiceAccessibilityMask representing the accessible metrics in this time range.
Check if a certain combination of metric, time span, and scope is accessible for calculating averaged data by returning a value of HealthServiceAccessibilityMask. Developers should check if the return value is HealthServiceAccessibilityMaskAvailable before calling any other HealthService APIs that involve the given metric with the given scope (like health_service_sum_averaged).
The metric to query for averaged data.
Earliest UTC time you are interested in.
Latest UTC time you are interested in.
HealthServiceTimeScope value describing how the average should be computed.
A value decribing whether averaged data is available.
Check if a certain combination of metric, time span, and scope is accessible for calculating summed, averaged data by returning a value of HealthServiceAccessibilityMask. Developers should check if the return value is HealthServiceAccessibilityMaskAvailable before calling health_service_sum_averaged.
Note that this call is the same as calling health_service_metric_aggregate_averaged_accessible(metric, time_start, time_end, HealthAggregationSum, HealthServiceTimeScopeOnce)
The metric to query for averaged data.
Earliest UTC time you are interested in.
Latest UTC time you are interested in.
HealthServiceTimeScope value describing how the average should be computed.
A value decribing whether averaged data is available.
Check if a certain combination of metric, HealthActivityMask and time span is accessible. Developers should check if the return value is HealthServiceAccessibilityMaskAvailable before calling any other HealthService APIs that involve the given activities.
A bitmask of activities you are interested in.
Earliest UTC time you are interested in.
Latest UTC time you are interested in.
A HealthServiceAccessibilityMask representing which of the passed HealthActivityMask values are available under the given constraints.
Subscribe to HealthService events. This allocates a cache on the application's heap of up to 2048 bytes that will be de-allocated if you call health_service_events_unsubscribe(). If there's not enough heap available, this function will return false and will not subscribe to any events.
Developer-supplied event handler function.
Developer-supplied context pointer.
true on success, false on failure.
Unsubscribe from HealthService events.
true on success, false on failure.
Return historical minute data records. This fills in the minute_data array parameter with minute by minute statistics of the user's steps, average watch orientation, etc. The data is returned in time order, with the oldest minute data returned at minute_data[0].
If the return value is zero, time_start and time_end are meaningless. It's not guaranteed that all records contain valid data, even if the return value is greater than zero. Check HealthMinuteData.is_invalid to see if a given record contains valid data.
Pointer to an array of HealthMinuteData records that will be filled in with the historical minute data.
The maximum number of records the minute_data array can hold.
On entry, the UTC time of the first requested record. On exit, the UTC time of the first second of the first record actually returned. If time_start on entry is somewhere in the middle of a minute interval, this function behaves as if the caller passed in the start of that minute.
On entry, the UTC time of the end of the requested range of records. On exit, the UTC time of the end of the last record actually returned (i.e. start time of last record + 60). If time_end on entry is somewhere in the middle of a minute interval, this function behaves as if the caller passed in the end of that minute.
Actual number of records returned. May be less then the maximum requested.
Get the preferred measurement system for a given HealthMetric, if the user has chosen a preferred system and it is applicable to that metric.
A metric value chosen from HealthMetric.
A value from MeasurementSystem if applicable, else MeasurementSystemUnknown.
Structure representing a single minute data record returned by health_service_get_minute_history(). The orientation field encodes the angle of the watch in the x-y plane (the "yaw") in the lower 4 bits (360 degrees linearly mapped to 1 of 16 different values) and the angle to the z axis (the "pitch") in the upper 4 bits. The vmc value is a measure of the total amount of movement seen by the watch. More vigorous movement yields higher VMC values.
Number of steps taken in this minute.
Quantized average orientation.
Vector Magnitude Counts (vmc).
true if the item doesn't represents actual data < and should be ignored.
Instantaneous light level during this minute.
heart rate in beats per minute
Reserved for future use.
Health metric values used to retrieve health data. For example, using health_service_sum().
The number of steps counted.
The number of seconds spent active (i.e. not resting).
The distance walked, in meters.
The number of seconds spent sleeping.
The number of sleep seconds in the 'restful' or deep sleep state.
The number of kcal (Calories) burned while resting due to resting metabolism.
The number of kcal (Calories) burned while active.
The heart rate, in beats per minute.
The resting heart rate, in beats per minute.
Health metric values used to retrieve health data. For example, using health_service_sum().
The number of steps counted.
The number of seconds spent active (i.e. not resting).
The distance walked, in meters.
The number of seconds spent sleeping.
The number of sleep seconds in the 'restful' or deep sleep state.
The number of kcal (Calories) burned while resting due to resting metabolism.
The number of kcal (Calories) burned while active.
The heart rate, in beats per minute. This is a filtered value that is at most 15 minutes old.
The raw heart rate value of the most recent sample, in beats per minute.
Used by health_service_sum_averaged() to specify how the average is computed.
No average computed. The result is the same as calling health_service_sum().
Compute average using the same day from each week. For example, every Monday if the passed in time range falls on a Monday.
Compute average using either weekdays (Monday to Friday) or weekends (Saturday and Sunday), depending on which day the passed in time range falls.
Compute average across all days of the week.
Used by health_service_aggregate_averaged() to specify what type of aggregation to perform. This aggregation is applied to the metric before the average is computed.
Sum the metric. The result is the same as calling health_service_sum_averaged(). This operation is only applicable for metrics that accumulate, like HealthMetricStepCount, HealthMetricActiveSeconds, etc.
Use the average of the metric. This is only applicable for metrics that measure instantaneous values, like HealthMetricHeartRateBPM.
Use the minimum value of the metric. This is only applicable for metrics that measure instantaneous values, like HealthMetricHeartRateBPM.
Use the maximum value of the metric. This is only applicable for metrics that measure instantaneous values, like HealthMetricHeartRateBPM.
Used by health_service_aggregate_averaged() to specify what type of aggregation to perform. This aggregation is applied to the metric before the average is computed.
Sum the metric. The result is the same as calling health_service_sum_averaged(). This operation is only applicable for metrics that accumulate, like HealthMetricStepCount, HealthMetricActiveSeconds, etc.
Use the average of the metric. This is only applicable for metrics that measure instantaneous values, like HealthMetricHeartRateBPM.
Use the minimum value of the metric. This is only applicable for metrics that measure instantaneous values, like HealthMetricHeartRateBPM.
Use the maximum value of the metric. This is only applicable for metrics that measure instantaneous values, like HealthMetricHeartRateBPM.
Health-related activities that can be accessed using health_service_peek_current_activities() and health_service_activities_iterate().
No special activity.
The 'sleeping' activity.
The 'restful sleeping' activity.
The 'walk' activity.
The 'run' activity.
Health-related activities that can be accessed using.
No special activity.
The 'sleeping' activity.
The 'restful sleeping' activity.
The 'walk' activity.
The 'run' activity.
The 'generic' activity.
Iteration direction, passed to health_service_activities_iterate(). When iterating backwards (HealthIterationDirectionPast), activities that have a greater value for time_end come first. When iterating forward (HealthIterationDirectionFuture), activities that have a smaller value for time_start come first.
Iterate into the past.
Iterate into the future.
Possible values returned by health_service_metric_accessible(). The values are used in combination as a bitmask. For example, to check if any data is available for a given request use: bool any_data_available = value & HealthServiceAccessibilityMaskAvailable;.
Return values are available and represent the collected health information.
The user hasn't granted permission.
The queried combination of time span and HealthMetric or HealthActivityMask is currently unsupported.
No samples were recorded for the given time span.
Health event enum. Passed into the HealthEventHandler.
All data is considered as outdated and apps should re-read all health data. This happens after an app is subscribed via health_service_events_subscribe(), on a change of the day, or in other cases that significantly change the underlying data.
Recent values around HealthMetricStepCount, HealthMetricActiveSeconds, or HealthMetricWalkedDistanceMeters have changed.
Recent values around HealthMetricSleepSeconds, HealthMetricSleepRestfulSeconds, HealthActivitySleep, and HealthActivityRestfulSleep changed.
A metric has either entered or exited the range set by health_service_register_metric_alert.
Recent values around HealthMetricHeartRateBPM or HealthMetricRestingHeartRateBPM have changed.
Health event enum. Passed into the HealthEventHandler.
All data is considered as outdated and apps should re-read all health data. This happens after an app is subscribed via health_service_events_subscribe(), on a change of the day, or in other cases that significantly change the underlying data.
Recent values around HealthMetricStepCount, HealthMetricActiveSeconds, or HealthMetricWalkedDistanceMeters have changed.
Recent values around HealthMetricSleepSeconds, HealthMetricSleepRestfulSeconds, HealthActivitySleep, and HealthActivityRestfulSleep changed.
A metric has crossed the threshold set by health_service_register_metric_alert.
Value of HealthMetricHeartRateBPM or HealthMetricHeartRateRawBPM has changed.
Light level enum.
Types of measurement system a HealthMetric may be measured in.
The measurement system is unknown, or does not apply to the chosen metric.
The metric measurement system.
The imperial measurement system.
Type used as a handle to a registered metric alert (returned by health_service_register_metric_alert)
Type used as a handle to a registered metric alert (returned by health_service_register_metric_alert)
Type used to represent HealthMetric values.
Expresses a set of HealthActivity values as a bitmask.
Callback used by health_service_activities_iterate().
Which activity the caller is being informed about.
Start UTC time of the activity.
End UTC time of the activity.
The context parameter initially passed to health_service_activities_iterate().
true if you are interested in more activities, or false to stop iterating.
Developer-supplied event handler, called when a health-related event occurs after subscribing via health_service_events_subscribe();.
The type of health-related event that occured.
The developer-supplied context pointer.
Convenience function for peeking at the current value of a metric. This is useful for metrics like HealthMetricHeartRateBPM that represent instantaneous values. It is NOT applicable for metrics like HealthMetricStepCount that must be accumulated over time (it will return 0 if passed that type of metric). This call is equivalent to calling health_service_aggregate_averaged(metric, time(NULL), time(NULL), HealthAggregateAvg, HealthServiceTimeScopeOnce)
The metric to query.
The current value of that metric, if available.
Convenience function for peeking at the current value of a metric. This is useful for metrics like HealthMetricHeartRateBPM that represent instantaneous values. It is NOT applicable for metrics like HealthMetricStepCount that must be accumulated over time (it will return 0 if passed that type of metric). This call is equivalent to calling health_service_aggregate_averaged(metric, time(NULL), time(NULL), HealthAggregationAvg, HealthServiceTimeScopeOnce)
The metric to query.
The current value of that metric, if available.
Return the value of an aggregated metric over a given time range. This call is more flexible than health_service_sum_averaged because it lets you specify which aggregation function to perform.
The aggregation function aggregation is applied to the metric metric over the given time range time_start to time_end first, and then an average is computed based on the passed in scope.
For example, if you want to get the average number of steps taken from 12 AM (midnight) to 9 AM across all days you would specify: time_t time_start = time_start_of_today(); time_t time_end = time_start + (9 * SECONDS_PER_HOUR); HealthValue value = health_service_aggregate_averaged(HealthMetricStepCount, time_start, time_end, HealthAggregationSum, HealthServiceTimeScopeDaily);
If you want to compute the average heart rate on Mondays and today is a Monday, you would specify: time_t time_start = time_start_of_today(), time_t time_end = time_start + SECONDS_PER_DAY, HealthValue value = health_service_aggregate_averaged(HealthMetricHeartRateBPM, time_start, time_end, HealthAggregationAvg, HealthServiceTimeScopeWeekly); To get the average of the minimum heart rate seen on Mondays for example, you would instead pass in HealthAggregationMin
Certain HealthAggregation operations are only applicable to certain types of metrics. See the notes above on HealthAggregation for details. Use health_service_metric_aggregate_averaged_accessible to check for applicability at run time.
Which HealthMetric to query.
UTC time of the start of the query interval.
UTC time of the end of the query interval.
the aggregation function to perform on the metric. This operation is performed across the passed in time range time_start to time_end.
HealthServiceTimeScope value describing how the average should be computed. Use HealthServiceTimeScopeOnce to not compute an average.
The average of the aggregation performed on the given metric over the given time range, if available.
Return the value of an aggregated metric over a given time range. This call is more flexible than health_service_sum_averaged because it lets you specify which aggregation function to perform.
The aggregation function aggregation is applied to the metric metric over the given time range time_start to time_end first, and then an average is computed based on the passed in scope.
For example, if you want to get the average number of steps taken from 12 AM (midnight) to 9 AM across all days you would specify: time_t time_start = time_start_of_today(); time_t time_end = time_start + (9 * SECONDS_PER_HOUR); HealthValue value = health_service_aggregate_averaged(HealthMetricStepCount, time_start, time_end, HealthAggregationSum, HealthServiceTimeScopeDaily);
If you want to compute the average heart rate on Mondays and today is a Monday, you would specify: time_t time_start = time_start_of_today(), time_t time_end = time_start + SECONDS_PER_DAY, HealthValue value = health_service_aggregate_averaged(HealthMetricHeartRateBPM, time_start, time_end, HealthAggregationAvg, HealthServiceTimeScopeWeekly); To get the average of the minimum heart rate seen on Mondays for example, you would instead pass in HealthAggregationMin
Certain HealthAggregation operations are only applicable to certain types of metrics. See the notes above on HealthAggregation for details. Use health_service_metric_aggregate_averaged_accessible to check for applicability at run time.
Which HealthMetric to query.
UTC time of the start of the query interval.
UTC time of the end of the query interval.
the aggregation function to perform on the metric. This operation is performed across the passed in time range time_start to time_end.
HealthServiceTimeScope value describing how the average should be computed. Use HealthServiceTimeScopeOnce to not compute an average.
The average of the aggregation performed on the given metric over the given time range, if available.
A mask value representing all available activities.
A mask value representing all available activities.
Check if a certain combination of metric, time span, aggregation operation, and scope is accessible for calculating aggregated, averaged data by returning a value of HealthServiceAccessibilityMask. Developers should check if the return value is HealthServiceAccessibilityMaskAvailable before calling health_service_aggregate_averaged.
The metric to query for averaged data.
Earliest UTC time you are interested in.
Latest UTC time you are interested in.
The aggregation to perform
HealthServiceTimeScope value describing how the average should be computed.
A value decribing whether averaged data is available.
Check if a certain combination of metric, time span, aggregation operation, and scope is accessible for calculating aggregated, averaged data by returning a value of HealthServiceAccessibilityMask. Developers should check if the return value is HealthServiceAccessibilityMaskAvailable before calling health_service_aggregate_averaged.
The metric to query for averaged data.
Earliest UTC time you are interested in.
Latest UTC time you are interested in.
The aggregation to perform
HealthServiceTimeScope value describing how the average should be computed.
A value decribing whether averaged data is available.
Set the desired sampling period for heart rate readings. Normally, the system will sample the heart rate using a sampling period that is automatically chosen to provide useful information without undue battery drain (it automatically samples more often during periods of intense activity, and less often when the user is idle). If desired though, an application can request a specific sampling period using this call. The system will use this as a suggestion, but does not guarantee that the requested period will be used. The actual sampling period may be greater or less due to system needs or heart rate sensor reading quality issues. Each time a new heart rate reading becomes available, a HealthEventHeartRateUpdate event will be sent to the application's HealthEventHandler. The sample period request will remain in effect the entire time the app is running unless it is explicity cancelled (by calling this method again with 0 as the desired interval). If the app exits without first cancelling the request, it will remain in effect even for a limited time afterwards. To determine how long it will remain active after the app exits, use health_service_get_heart_rate_sample_period_expiration_sec. Unless the app explicitly needs to access to historical high-resolution heart rate data, it is best practice to always cancel the sample period request before exiting in order to maximize battery life. Historical heart rate data can be accessed using the health_service_get_minute_history call.
The fastest sampling rate that will be acknowledged by the system is 60 seconds. Values passed in that are smaller than 60 seconds will be changed to 60 seconds. The end result of this is that a HealthEventHeartRateUpdate will be sent to the application's HealthEventHandler no more frequently than 60 seconds.
desired interval between heart rate reading updates. Pass 0 to go back to automatically chosen intervals.
true on success, false on failure
Set the desired sampling period for heart rate readings. Normally, the system will sample the heart rate using a sampling period that is automatically chosen to provide useful information without undue battery drain (it automatically samples more often during periods of intense activity, and less often when the user is idle). If desired though, an application can request a specific sampling period using this call. The system will use this as a suggestion, but does not guarantee that the requested period will be used. The actual sampling period may be greater or less due to system needs or heart rate sensor reading quality issues. Each time a new heart rate reading becomes available, a HealthEventHeartRateUpdate event will be sent to the application's HealthEventHandler. The sample period request will remain in effect the entire time the app is running unless it is explicitly cancelled (by calling this method again with 0 as the desired interval). If the app exits without first cancelling the request, it will remain in effect even for a limited time afterwards. To determine how long it will remain active after the app exits, use health_service_get_heart_rate_sample_period_expiration_sec. Unless the app explicitly needs to access to historical high-resolution heart rate data, it is best practice to always cancel the sample period request before exiting in order to maximize battery life. Historical heart rate data can be accessed using the health_service_get_minute_history call.
desired interval between heart rate reading updates. Pass 0 to go back to automatically chosen intervals.
true on success, false on failure
Return how long a heart rate sample period request (sent via health_service_set_heart_rate_sample_period) will remain active after the app exits. If there is no current request by this app, this call will return 0.
The number of seconds the heart rate sample period request will remain active after the app exits, or 0 if there is no active request by this app.
Return how long a heart rate sample period request (sent via health_service_set_heart_rate_sample_period) will remain active after the app exits. If there is no current request by this app, this call will return 0.
The number of seconds the heart rate sample period request will remain active after the app exits, or 0 if there is no active request by this app.
Register for an alert when a metric crosses a given threshold. When the metric crosses this threshold (either goes above or below it), a HealthEventMetricRange event will be generated. To cancel this registration, pass the returned HealthMetricAlert value to health_service_cancel_metric_alert. The only metrics currently supported by this call are HealthMetricHeartRateBPM and HealthMetricRestingHeartRateBPM, but future versions may support additional metrics. To see if a specific metric is supported by this call, use time_t now = time(NULL); health_service_metric_aggregate_averaged_accessible(metric, now, now, HealthAggregateAvg, HealthServiceTimeScopeOnce)
the threshold value
handle to the alert registration on success, NULL on failure
Register for an alert when a metric crosses the given threshold. When the metric crosses this threshold (either goes above or below it), a HealthEventMetricAlert event will be generated. To cancel this registration, pass the returned HealthMetricAlert value to health_service_cancel_metric_alert. The only metric currently supported by this call is HealthMetricHeartRateBPM, but future versions may support additional metrics. To see if a specific metric is supported by this call, use: `time_t now = time(NULL); HealthServiceAccessibilityMask accessible = health_service_metric_aggregate_averaged_accessible(metric, now, now, HealthAggregationAvg, HealthServiceTimeScopeOnce); bool alert_supported = (accessible & HealthServiceAccessibilityMaskAvailable); ` In the current implementation, only one alert per metric can be registered at a time. Future implementations may support two or more simulataneous alert registrations per metric. To change the alert threshold in the current implementation, cancel the original registration using health_service_cancel_metric_alert before registering the new threshold.
the threshold value
handle to the alert registration on success, NULL on failure
Cancel an metric alert previously created with health_service_register_metric_alert.
the HealthMetricAlert previously returned by health_service_register_metric_alert
true on success, false on failure
Cancel an metric alert previously created with health_service_register_metric_alert.
the HealthMetricAlert previously returned by health_service_register_metric_alert
true on success, false on failure
Convenience macro to switch between two expressions depending on health support. On platforms with health support the first expression will be chosen, the second otherwise.
Convenience macro to switch between two expressions depending on health support. On platforms with health support the first expression will be chosen, the second otherwise.
Do you have questions about the Pebble SDK?
Do you need some help understanding something on this page?
You can either take advantage of our awesome developer community and check out the SDK Help forums, or you can send us a message through the website!