The Wear Health Services API (WHS) is a mandatory component for all devices running Wear OS 3 and higher, as it provides a consistent integration surface for health and fitness developers. Build your app to adjust gracefully to many devices and their differing capabilities to maintain compatibility across devices and avoid user experience problems. In order to do so, declare dependencies only for the clients that your app uses. Additionally, allow your app the flexibility to display or remove optional advanced metrics based on their availability.
Different sensors generate data at different frequencies that vary per device based on the underlying hardware and sensor platform. For example, a device might return heart rate at one timestamp and location at another. Create apps that can receive independent data streams at different timestamps or at overlapping timestamps.
This guide describes the expected behaviors and data types supported by various clients within Wear Health Services.
Exercise client
The following sections describe the expected behaviors and data types of the
ExerciseClient.
Expected behaviors
For the ExerciseClient, some exercise types are dependent on the availability
of certain data types. For example, wheelchair exercises are only available if
wheelchair pushes are supported. Enable and disable these options based on their
availability on a given device.
Most exercise data types are sampled and delivered at one second intervals, with some exceptions:
- In some situations, some exercise data types are updated more than once per second. For example, when the user is running, the step count is updated more than once per second.
- For some data types, an update is delivered only if the current value is different from the previous value.
Data delivery can be either streaming or batched. Data is streamed while the application processor is on, which is typically when the display is on and interactive. Once the display goes off or into ambient mode (on but non-interactive), the data is batched in order to save power. The batched data is delivered to the application either when the application processor turns on again, either due to the watch comes out of ambient mode, or when the buffers for batching are full, which varies by device. The sampling rate remains the same while the device is in ambient mode, so a batch that is delivered still has high frequency data points.
Data Types are derived solely from data generated by sensors on the watch. For example, location data comes entirely from the watch and not the phone.
Data types
The ExerciseClient API allows you to start, pause, resume and stop workouts
of distinct types. For each exercise, WHS defines a set of data types that are
made available to you for that exercise type. This saves power and simplifies
your app logic, as sensors that are not required for a given exercise aren’t
turned on. For example, when beginning a run, location data is only provided and
tracked for an outdoor run. When starting a biking exercise, steps are not
provided or tracked. The following sections provide a description of the data
types that are supported in ExerciseClient.
Guaranteed exercise data types
The following exercise data types are available on all devices.
- Sample data types have a corresponding _STATS Data Type that returns minimum, maximum, and average values from the exercise. For example, PACE stats can be pulled with the PACE_STATS Data Type.
- Interval data types have a corresponding _TOTAL Data Type that returns the cumulative value from the exercise. For example, DISTANCE stats can be pulled with the DISTANCE_TOTAL Data Type.
| Metric | Expected data | Notes on expected behaviors |
| HEART_RATE_BPM | Beats per minute [DataType: Double] | All devices sample heart rate once per second during an exercise. Some devices report a BPM value every second. Some devices only report BPM when it has changed since the previous value. Don’t expect to receive a BPM value at each one second interval on all devices. |
| LOCATION | Latitude and longitude [DataType: Double] | Location data is based on watch GPS only. Don’t expect location data to come from Fused Location Provider or other Android services). Each data point also includes an accuracy value (also known as a horizontal position error) and availability. |
| STEPS | [Data type: Long] | Step count is a running total over the duration of the exercise, not including time when exercise is paused |
| DISTANCE | Meters [Data type: Double] | Computed from GPS-based location when available, and from steps otherwise. Total refers to the total over the duration of the exercise, not including the time when the exercise is paused. |
| SPEED | [meters / second] [Data type: Double] | Returns minimum, maximum, and average values. These are over the duration of the exercise, not including the time when the exercise is paused. |
| PACE | [seconds / meter] [Data type: Double] | Default value is 0 if the speed is 0. Averages are over the duration of the exercise, not including the time when the exercise is paused. |
| ELEVATION_GAIN | Meters. [Data type: Double] | Positive changes in elevation. The total is reported over the duration of the exercise, not including the time when the exercise is paused. |
| TOTAL_CALORIES | kCal [Data type: Double] | Active calories burned added to the Basal Metabolic Rate. The calories emitted here take into account the user’s height, weight, age and gender as specified in system settings. Calories do not take into account any user profile data collected in your app. The total reported is over the duration of the exercise, not including the time when the exercise is paused. |
Optional exercise data types
The following list of data types is available only on certain devices. See the Jetpack reference for a full list of DataTypes. If a DataType is not in the preceding “required/guaranteed” list, then it is optional.
See the following examples of optional data types. This list is not exhaustive:
| Metric | Expected data | Notes on expected behaviors |
| ABSOLUTE_ELEVATION | [Data type: Double] | |
| ELEVATION_LOSS | Meters [Data type: Double] | Negative changes in elevation. The value is positive. For example, an elevation loss of 1m is returned as 1, not -1. |
| STEPS_PER_MINUTE | [Data type: Long] | |
| WHEELCHAIR_PUSHES | [Data type: Long] | A count of wheelchair pushes for use in wheelchair-based exercises. |
| REP_COUNT | [Data type: Long] | |
| SWIM_STROKE_COUNT | [Data type: Long] | |
| SWIM_LAP_COUNT | [Data type: Long] |
Data types per exercise
Different data types are returned for each exercise type. The data types that
are returned are consistent with the needs of the exercise. For example, the
BIKING Exercise Type doesn’t return the STEPS Data Type. Please use the
Capabilities method at runtime to determine which data types are
supported on the user’s device.
At a minimum, all exercise types return heart rate and calorie data. Other exercises may support additional data types, depending on the requirements for the exercise.
Here are a few examples:
- Exercises such as meditation or pilates support only heart rate and calories
- Exercises such as basketball or badminton support heart rate, calories, distance, and steps.
- Exercises such as walking and running support heart rate, calories, distance, steps, speed, and pace
- Swimming supports heart rate, calories, distance, and swim laps
Passive Monitoring Client
The following Data Types are required for all devices running Wear OS to support apps that passively monitor health data such as heart rate and step count. Each of these Data Types must be derived solely from data generated by sensors on the watch.
Expected behaviors
To conserve power, sensor readings obtained using Passive Monitoring are stored on the MCU and batched to Health Services. These batched results are returned at different intervals depending on system behavior. Some examples include returning batches when sensor buffers are full, or when the user interacts with the display.
Don’t assume any predefined or predictable batching intervals for any data types.
Passive monitoring data types
| Metric | Expected data | Notes |
| HEART_RATE_BPM | Beats per minute [Data type: Double] | Devices may return heart rate readings at different intervals. Some devices may take reading every second. Other devices may take a reading every ten minutes. These intervals are not made available to apps. Apps should adapt gracefully to different sampling intervals. |
| STEPS_DAILY/STEPS | [Data type: Long] | Daily steps is the total number of steps taken since the last reset, which is triggered by WHS at midnight. This includes any steps taken while an active exercise is paused. Steps is a granular delta since the last check. |
| DISTANCE_DAILY/DISTANCE | meters [Data type: Double] | Computed from Accelerometer/Steps. Don’t calculate during GPS to ensure that users who have turned off location services can still receive accurate step counts. |
| SPEED | [meters / second] [Data type: Double] | |
| CALORIES_DAILY | kCal [Data type: Double] | Calories for the day, including active calories and BMR. The calorie figure that is emitted here takes into account the user’s height, weight, age and gender as specified in system settings. Calories are not adjusted according to any user profile data collected in your app. |
| RUNNING_STEPS (optional) | [Data type: Long] | Delta of steps both during an exercise and otherwise. Track both at the same time. |
| WALKING_STEPS (optional) | [Data type: Long] | |
| ELEVATION_GAIN | meters [Data type: Double] | Includes only the positive deltas in elevation |
| ELEVATION_LOSS | meters [Data type: Double] | Includes only the negative deltas in elevation |
| FLOORS_DAILY | [Data type: Double] | Can be represented as “partial” floors |
Passive monitoring daily goals
| Metric | Expected data | Notes |
| STEPS_DAILY | [Data type: Long] | Daily steps, including any steps taken while an active exercise is paused, is the total number of steps taken since the last reset. WHS resets at midnight. |
| FLOORS_DAILY | [Data type: Double] | Can be represented as “partial” floors of stairs. |
| CALORIES_DAILY | kCal [Data type: Double] | Calories for the day, which includes active calories and BMR. |
| DISTANCE_DAILY | meters [Data type: Double] | Computed from accelerometer or step count. Don't calculate this using the GPS so that users who have turned off location services can still receive accurate step counts. |
| DAILY_ELEVATION_GAIN | meters [Data type: Double] | Includes only the positive deltas in elevation |
MeasureClient
Use MeasureClient
to measure the heart rate at a given moment.
Expected behaviors
MeasureClient and PassiveClient are similar in some ways. They both provide
non-batched health stats unrelated to an exercise. You can use both to measure
heart rate, but the main difference is that MeasureClient includes
heart rate data availability, but PassiveClient doesn't include availability
info.
Data types
| Metric | Expected data | Notes |
| HEART_RATE_BPM | Beats per minute [Data type: Double] | Also includes availability |
Supported features
In addition to Exercise Data Types and Passive Monitoring Data Types, devices support additional features for triggering events such as starting an exercise and measuring state such as asleep versus awake. Some of these features exist across all devices, and others exist only on some devices.
Event triggers
All devices support the following common triggers:
- Daily goals for distance and steps
- Exercise goals for steps, distance, and duration.
Other devices may support more advanced event triggers. Some examples include the following:
- Counting laps when swimming
- Exercise goals for calories burned
- Exercise goals for instantaneous speed
States
All devices support basic state functionality. State functionality refers to whether a user is is currently in an active exercise or not
Other devices may provide additional state functionality. Some additional state functionality includes detecting if an exercise has been auto-paused or auto-resumed, or when the user is awake or asleep.
Health alerts in passive monitoring
Some devices support health alerts. These features aren't supported on all devices. Some health alerts include detecting heart rate abnormalities or detecting falls.
Recommended for you
- Note: link text is displayed when JavaScript is off
- Active data and exercises
- Health Services on Wear OS