Health Platform API

Health Platform API is an Android API that provides developers with a single interface for reading, writing, and sharing a user’s historic health, wellness, and fitness data. With Health Platform, users have control of their data. Users control which apps have read or write access to different types of data. Health Platform API data types include height, heart rate, and more.

The Health Platform API gives users a storage and sharing mechanism that allows them to select which apps can access and display their personal health, fitness, and wellness data. This then allows app developers to show users a more complete view of their health, and allows users to more effectively monitor their data.

The Health Platform API software developer kit gives Android app developers everything they need to provide access to a user’s health and wellness data on select Samsung devices, and allows different apps to perform bulk operations, such as inserting, deleting, and reading data.

Get started

When using Health Platform, keep the following things in mind:

  • Client apps must obtain granular permissions for read or write access from the user.
  • The user can deny permissions or revoke permissions at any point afterwards.
  • Health Platform API supports only select Samsung devices.
  • HealthDataClient is the client for Health Platform and an entry point to the Health Platform.

The following image shows the necessary integration steps that developers must follow:

integration-steps

Release files

The Health Platform V1 release contains the following:

  • Client SDK: Include this SDK in your application to use the Health Platform API. The SDK is a Maven repo you can directly include in your application Gradle build files (more instructions below).

Install Health Platform

Install Health Platform using the following steps:

In the app’s root build.gradle file, add the repo, as shown in the following example:

allprojects {
    ...
    repositories {
        ...
        google()
    }
}

Add a dependency on the Health Platform SDK in your module’s build.gradle file, as shown in the following example:

dependencies {
   …
  implementation 'com.google.android.libraries.healthdata:health-data-api:1.0.0-alpha01'
}

Data

Health Platform stores and structures health and fitness data. It also considers core differences between how data of a given type is measured; for example, a heart rate measurement is taken immediately, but a step count is taken over a period of time.

Here’s a look at the central objects in Health Platform and how they differ:

  • RawData: A measurement and data record.
  • DataType: A specifier for common types of health and fitness data, such as heart rate, body fat, or body temperature, and their formats, such as fields, read-only, optional.
  • SampleData: A RawData object that is an instantaneous measurement, such as heart rate, blood pressure, or running speed.
  • IntervalData: A RawData object that is a cumulative measurement taken over a period of time, such as number of steps taken, distance traveled, or calories burned.
  • SeriesData: A RawData object that encapsulates a sequence of measurements over a period of time. SeriesData is particularly suited for high-frequency sensor data, such as continuous heart rate samples during an activity session.

Each of the three RawData classes above correspond to a specific subclass of DataType. SampleData, IntervalData, and SeriesData correspond to SampleDataType, IntervalDataType, and SeriesDataType, respectively. Each RawData object is assigned a unique identifier (UID) by the Health Platform when inserted. You can use this UID to reference a specific RawData object in read, update, or delete requests.

Data types

Health Platform includes a wide set of data types that are commonly used across health and fitness apps. Data stored with the available data types provide users with a comprehensive view of their historical health, fitness, and wellness data, giving insight into their daily activities.

Each data type is defined by its data format, which includes:

  • Fields: Specific or generic fields associated with the data type. For example, the SpO2 data type (blood oxygen saturation) has fields like Title, Notes, or Percentage.
  • Type: long, double, String, or Enum.
  • Attribute: read-only, required, optional, or validation range.

List of data types

Make the most of Health Platform by understanding the available data types. Health Platform currently supports the data types shown in the following table. The data types are organized according to their format (sample, interval or series):

SampleDataTypes:

DataType.BasalMetabolicRateDataType BASAL_METABOLIC_RATE Required
DataType.BloodGlucoseDataType BLOOD_GLUCOSE Required and Optional
DataType.BloodPressureDataType BLOOD_PRESSURE Required and Optional
DataType.BodyFatDataType BODY_FAT Required
DataType.BodyTemperatureDataType BODY_TEMPERATURE Required and Optional
DataType.BoneMassDataType BONE_MASS Required
DataType.CervicalMucusDataType CERVICAL_MUCUS Optional
DataType.CervicalPositionDataType CERVICAL_POSITION Optional
DataType.CyclingPedalingCadenceDataType CYCLING_PEDALING_CADENCE Required
DataType.DateOfBirthDataType DATE_OF_BIRTH Read Only
DataType.GenderDataType GENDER Read Only
DataType.HeartRateDataType HEART_RATE Required
DataType.HeightDataType HEIGHT Required
DataType.HipCircumferenceDataType HIP_CIRCUMFERENCE Required
DataType.HrvDifferentialIndexDataType HRV_DIFFERENTIAL_INDEX Required
DataType.HrvRmssdDataType HRV_RMSSD Required
DataType.HrvSDataType HRV_S Required
DataType.HrvSd2DataType HRV_SD2 Required
DataType.HrvSdannDataType HRV_SDANN Required
DataType.HrvSdnnDataType HRV_SDNN Required
DataType.HrvSdnnIndexDataType HRV_SDNN_INDEX Required
DataType.HrvSdnnIndexDataType HRV_SDNN_INDEX Required
DataType.HrvSdsdDataType HRV_SDSD Required
DataType.HrvTinnDataType HRV_TINN Required
DataType.LeanBodyMassDataType LEAN_BODY_MASS Required
DataType.LocationDataType LOCATION Required
DataType.MenstruationDataType MENSTRUATION Optional
DataType.OvulationTestDataType OVULATION_TEST Required
DataType.OxygenSaturationDataType OXYGEN_SATURATION Required
DataType.PaceDataType PACE Required
DataType.PowerDataType POWER Required
DataType.RespiratoryRateDataType RESPIRATORY_RATE Required
DataType.RestingHeartRateDataType RESTING_HEART_RATE Required
DataType.SexualActivityDataType SEXUAL_ACTIVITY Required
DataType.SpeedDataType SPEED Required
DataType.StepsCadenceDataType STEPS_CADENCE Required
DataType.Vo2MaxDataType VO2_MAX Required/Optional
DataType.WaistCircumferenceDataType WAIST_CIRCUMFERENCE Required
DataType.WeightDataType WEIGHT Required

IntervalDataTypes:

DataType.ActiveEnergyDataType ACTIVE_ENERGY_BURNED Required
DataType.ActiveTimeDataType ACTIVE_TIME Read Only
DataType.ActivityEventDataType ACTIVITY_EVENT Required
DataType.ActivityLapDataType ACTIVITY_LAP Optional
DataType.ActivitySessionDataType ACTIVITY_SESSION Required
DataType.BasalEnergyDataType BASAL_ENERGY_BURNED Read Only
DataType.DistanceDataType DISTANCE Required
DataType.ElevationGainedDataType ELEVATION_GAINED Required
DataType.FloorsClimbedDataType FLOORS_CLIMBED Required
DataType.HydrationDataType HYDRATION Required
DataType.NutritionDataType NUTRITION Optional
DataType.RepetitionsDataType REPETITIONS Required
DataType.SleepSessionDataType SLEEP_SESSION Optional
DataType.SleepStageDataType SLEEP_STAGE Required
DataType.StepsDataType STEPS Required
DataType.SwimmingStrokesDataType SWIMMING_STROKES Required/Optional
DataType.TotalEnergyDataType TOTAL_ENERGY_BURNED Read Only

SeriesDataTypes:

DataType.CyclingPedalingCadenceSeriesDataType CYCLING_PEDALING_CADENCE Required
DataType.HeartRateSeriesDataType HEART_RATE Required
DataType.LocationSeriesDataType LOCATION Required
DataType.PaceSeriesDataType PACE Required
DataType.PowerSeriesDataType POWER Required
DataType.SpeedSeriesDataType SPEED Required
DataType.StepsCadenceSeriesDataType STEPS_CADENCE Required

Developer functions

The following describes the set of standard data functions available within Health Platform. The platform provides standard insert, update, and delete functions for raw data.

Read AggregatedData

The platform allows clients to apply an aggregation function over types of AggregatedData, which are listed below:

  • StatisticalData: Provides the average, minimum, or maximum values in a set of SampleData or SeriesData, such as the minimum and maximum heart rate during an activity session.
  • CumulativeData: Provides the sum total of IntervalData values, such as the total step count within a daily interval.
  • CountData: Provides a simple count of the number of underlying RawData objects, such as the number of activity sessions in a given week. Count data can be computed for sample, interval, and series data types.

Connecting to the Health Platform API

HealthDataClient is the entry point to the Health Platform API.

The following steps describe how to connect to Health Platform:

  1. Use HealthDataService.getClient to create new HealthDataClient instances.
  2. The client app must then request permission from the user using the requestPermissions (Set) method.

HealthDataClient automatically manages its connection to the underlying storage layer and handle all IPC and serialization of outgoing requests and incoming responses.