Xiaomi Health Cloud Open Platform User

Documentation
At this stage, this product is only officially open to Xiaomi ecological chain companies and partners.

1. Overview
Xiaomi Health Cloud is an open platform built on the Xiaomi Cloud platform. It can store and manage sports and fitness data
collected by various devices of users. These data are collected and processed by various devices used by users, and then uploaded
to Xiaomi Health Cloud through applications for storage and management.
The main functions of Xiaomi Health Cloud:

 Capable of storing data from any wearable device or sensor

 Stored data can be accessed by any application
 When users upgrade their devices or applications, data usage will not be affected
 Support user rights management and protect user privacy

If the user has a device that can collect fitness data, the usage process and scenarios of Xiaomi Health Cloud are as
follows

1. The user determines the type of data that the device can collect, and then selects the corresponding data types defined by
Xiaomi Health Cloud.
2. For each selected data type, create a corresponding data source ( DataSource ) and obtain the corresponding data source ID
3. Collect data and mark each data with the corresponding data source ID, and then upload it to Xiaomi Health Cloud
4. If users need to download and use this data, they can also use the corresponding data source ID to download the data from
Xiaomi Health Cloud

2. Basic Concepts
Xiaomi Health Cloud defines a set of concepts that are used to describe data organization formats and user activities.

DataSource
The data source is a description of user data. Xiaomi Health Cloud uses data sources to identify the data uploaded by users. Each
data must have one and only one data source identifier. Therefore, when users upload a set of data, they must first create a data
source or use an existing data source to identify this set of data. Similarly, when users download data, they also need to specify
which data source identifier to download.
The data source identifies the data from four aspects

1. Some basic information of the data source: data source name, data source type, etc.
2. Device information for collecting data: device model, name, UID, etc.
3. Application information of the uploaded data: application name, version number, etc.
4. Data type information: corresponds to the specific data type

Data Type
Data type is the basic data organization format for uploading, downloading and storing in Xiaomi Health Cloud. Before using Xiaomi
Health Cloud, users must determine the type of data collected by their devices, and then select the data type defined by Xiaomi
Health Cloud to organize the data. Then they can create the corresponding data source and upload and download their own data.
Currently, users can only use the data types defined by Xiaomi Health Cloud, and cannot customize data types. If users do need to
use custom data types, please contact us: [email protected] . Currently, new data types can only be added offline, and then
redeploy and publish the service.

Device
The device describes the sensor device information when the user collects data, and is also the source of the original data.

Application
The application describes the application information for creating a data source, and can also describe the application information
used to upload and download user data.

DataPoint
A data point describes the data collected by a device at a certain moment or within a certain time interval. These data need to
conform to a certain data type. Each data point must have a timestamp (EndTime) when the data is collected. If the data point is
instantaneous data, the start time (startTime) does not need to be provided; if the data point represents data within a certain time
interval, the start time (StartTime) of the interval period needs to be provided.
When each data point is uploaded to the server, it must be identified with a data source ID information, indicating which data
source the data point belongs to. In fact, when users interact with the server to manage data points, any operation must provide
data source ID information.

Dataset
A dataset is a data structure concept when the client and server interact with each other to operate data points. Since each data
point is usually small and the frequency of data point collection is high, uploading each collected data point to the server once, or
downloading data points one by one, will cause great pressure on the server. Therefore, Xiaomi Health Cloud uses datasets to
organize scattered data points and interact with the server in units of datasets.
For example, when uploading data points, users need to collect a certain number of data points, organize these data points into a
data set, and then upload this data set to the server. When downloading, you also need to specify the data source information and
time range first, and then download a data set from the server.

3. Data Format
This section describes in detail the field information and organization format of each data format.

Application
Application describes the application information used to create the data source, and can also describe the application information
used to upload and download user data

Option
Field Name type al illustrate

name Strin require Application name. This name does not need to be unique, and the same user can
g d use the same application name in multiple data sources.

packageNa Strin optiona The package name of the application

 Option
Field Name type al illustrate

me g l

detailsUrl Strin optiona The callback URL through which users can view application details
g l

os Strin optiona The name of the system platform that the application runs on, such as Android,
g l iOS

version Strin optiona The application version number. If the application is updated in a way that affects
g l the way data is calculated, the user should update this version number.

DataPoint
DataPoint is the smallest storage unit of Xiaomi Health Cloud for sports and fitness data, and is also the unit of data collection. Each
data point represents a data record at a certain time point or time interval.

Option
Field Name type al illustrate

dataTypeName Strin require Data type name, which is the name of DataType and can only be the
g d name of DataType built into Xiaomi Health Cloud. User-defined extended
data types are not currently supported.
 Option
Field Name type al illustrate

startTimeNanos Long optiona The start time of DataPoint, timestamp type. Some DataTypes represent
l data of a time interval, in which case DataPoint needs to provide
startTimeNanos, while some DataTypes represent instantaneous data, in
which case DataPoint does not need to provide startTimeNanos

endTimeNanos Long require DataPoint end time, timestamp type. All DataTypes require endTimeNanos
d

computationTimeMi Long optiona The calculation timestamp of DataPoint, timestamp type. This field is used
llis l for version checking during transmission. If the user needs to replace an
existing DataPoint b in Xiaomi Health Cloud with a DataPoint a, then the
calculationTimeMillis of a must be newer than the calculationTimeMillis of
b. At the same time, it is also necessary to ensure that the
calculationTimeMillis of a must exist. In addition, if b does not set the
calculationTimeMillis, it is considered to be older than a.

modifiedTimeMillis Long optiona Indicates the time when the datapoint was last modified
l

originDataSourceId Strin optiona If the datapoint is contained in a dataset from a derived data source, the
g l user needs to provide a value for this field to indicate which data source
originally created the datapoint.

rawTimestampNano Long optiona The data point is read from the device sensor, and the time when the raw
s
 Option
Field Name type al illustrate

l data is read.

value Valu require The value carried by the data point may be multiple values, depending on
e d whether the data type of the data point is one-dimensional or multi-
dimensional. The number and type of values contained in the data point
must be consistent with the DataType to which it belongs.

Dataset
A dataset is a data structure concept when a client and a server interact with each other to operate data points.

Option
Field Name type al illustrate

dataSourceId String require Data source Id, which is the DataStreamId returned when creating the
d DataSource. After creating the DataSource, the user needs to store the
dataStreamId in the returned message and use it in the subsequent
datasets.

minStartTime Long require If the DataPoint contained in the Dataset has startTimeNanos, then this
Ns d value is the minimum startTimeNanos of all DataPoints in this Dataset,
otherwise this value is the minimum endTimeNanos of all DataPoints in this
Dataset

maxEndTime Long require This value is the maximum endTimeNanos of all DataPoints in this Dataset
 Option
Field Name type al illustrate

Ns d

nextPageToke String optiona The paging identifier of the dataset. In a user request, when there are too
n l many data points that meet the conditions (more than 1000), the server will
only fill 1000 data points in the returned dataset and then set a
nextPageToken identifier. When the user continues to request subsequent
data, it is necessary to carry this nextPageToken as a paging identifier, and
the server will scan the data from the next page based on the paging
identifier.

point DataPoi require The dataset contains a list of data points. For more information about data
nt d points, please refer to the DataPoint documentation.

DataSource
<The data source is a description of the user's data. Xiaomi Health Cloud uses the data source to identify the data uploaded by the
user. Each data must have one and only one data source identifier/p>

Option
Field Name type al illustrate

name String optiona Data source name. For the same user, the name can be repeated. The
l data source name is human-readable and should have actual meaning.
 Option
Field Name type al illustrate

type Integer require Data source type. Currently, there are only two types of data source
d types: raw and derived. Since the data is read by the sensor device
through the app and then uploaded to MiFitStore through the app, if the
app processes the data, then the data source type should be derived,
otherwise it should be raw. The data source type is an enumeration value:

 raw
 derived

When creating a data source, you should provide an enumerated integer

value instead of a string. For details, please refer to
the DataSourceType documentation

dataStreamId String optiona Data source ID value, which is generated by the server. For the same
l user, the data source's dataStreamId is unique.
Users do not need to provide dataStreamId when creating a data source.
After the server successfully creates a data source, it will include
dataStreamId in the return message. Users should obtain the
dataStreamId of the data source from the return message, and then
provide the dataStreamId in subsequent interactions with the data
source.

dataStreamNa String optiona Data stream name. For the same user, the data stream name can be
me l repeated. The data stream name corresponds to the name of the sensor
that collects the data.

dataType DataType require The data type of the data source identification data, please refer to the
d DataType document for details

device Device require Data source identifies the device information of the data. For details,
d please refer to the Device document
 Option
Field Name type al illustrate

application Applicatio require The data source identifies the application information of the data. For
n d details, please refer to the Application document

DataSourceType - Data source type

DataSourceType describes whether the application processes the data collected by the sensor. The data collected by the sensor is
raw data, which needs to be uploaded to MiFitStore through the app. If the app processes the data collected by the sensor before
uploading the data, then DataSourceType should be set to derived, otherwise it should be raw

Type Value Type Name

1 raw

2 derived

DataType - Data type

DataType defines the schema in which data is collected, stored, and used. DataType only defines the format in which data is
collected, stored, and displayed, and does not define how data is collected and displayed.
Xiaomi Health Cloud provides a variety of data types. The same type of data can be represented by different data types, depending
on how the data is displayed. For example: the data type com.xiaomi.micloud.fit.step_count.delta represents the number of steps
between two readings (the number of new steps); while the data type com.google.step_count.cumulative represents the total
number of steps since the beginning.
Each data type can contain several data fields (each field is a field), and can be divided into one-dimensional data types and
multidimensional data types according to the number of fields. One-dimensional data types contain only one field; while
multidimensional data types (such as location type, which has multiple fields such as latitude, longitude and accuracy) each field
represents a dimension. Each field of the same data type has a unique name, and the field also defines the format of the data (int,
float).
Data types can also be divided into instantaneous value types and non-instantaneous value types. Instantaneous value data types
refer to data collected at a certain point in time, while non-instantaneous value data types refer to data collected during a certain
period of time. The data point corresponding to the instantaneous value data type only needs to set the endTime, but not the
startTime; the data point corresponding to the non-instantaneous value data type needs to set both the startTime and the
endTime.

Data type name Data Type Description

TYPE_ACTIVITY_SAMPLE Instantaneous value, multidimensional data type.

(com.xiaomi.micloud.fit.activity.sample) Each data point represents the instantaneous sample
value of the current activity. The data point has two fields:

 activity: an integer value representing the activity

type (each activity type is represented by an
integer constant)
 confidence: is a float value between 0.0-100.0. If
the confidence is unknown, a negative number can
be used to represent the value of this field

If multiple activities are detected at the same time, and

each activity has a different confidence value, then
multiple data points can be used to represent them. These
data points use the same timestamp, but different values.

TYPE_ACTIVITY_SEGMENT Non-instantaneous value, one-dimensional data type.

(com.xiaomi.micloud.fit.activity.segment) Each data point represents a duration time interval and an
activity integer value. The
start and end times of multiple data points of an activity
cannot overlap, but can be discontinuous. If two activities
occur at the same time, the most significant one is
selected and the other is discarded.
Data type name Data Type Description

TYPE_BASAL_METABOLIC_RATE Instantaneous value, one-dimensional data type.

(com.xiaomi.micloud.fit.calories.bmr) Each data point represents the basal metabolic rate of
energy consumption when the user is at rest. The unit is
kcal/day.

TYPE_BODY_FAT_PERCENTAGE Instantaneous value, one-dimensional data type

(com.xiaomi.micloud.fit.body.fat.percentage) . Each data point represents a test result. The
measurement result represents the ratio between the total
body fat and body weight.

TYPE_CALORIES_EXPENDED Non-instantaneous value, one-dimensional data type.

(com.xiaomi.micloud.fit.calories.expended) Each data point represents the number of calories
consumed in the start and end time interval of the data
point, in kilocalories. The data value is of float type.
Both startTime and endTime need to be assigned values,
indicating the time interval of calories consumed.

TYPE_CYCLING_PEDALING_CADENCE Instantaneous value, one-dimensional data type

(com.xiaomi.micloud.fit.cycling.cadence) Each data point represents an instantaneous
measurement of the pedaling rate of a bicycle, in crank
revolutions per minute.

TYPE_CYCLING_PEADING_CUMULATIVE Non-instantaneous value, one-dimensional data type

(com.xiaomi.micloud.fit.cycling.pedaling.cumulative) Each data point represents the number of pedal rotations
from the start of counting to the current time. When using
this data type, each rotation can be counted multiple
times because the value of each data point is
monotonically increasing. If you want to count the number
of rotations within a time interval, you should use the
value at the end of the interval minus the value at the
start of the interval.
Note: In actual operation, the data source may reset count
Data type name Data Type Description

to 0. If possible, when creating a data point, the data

source should set the startTime of the data point to the
time when counting started this time. Accordingly, if the
value of a data point is 0, it means that the count has
been reset at this time.

TYPE_CYCLING_WHEEL_REVOLUTION Non-instantaneous value, one-dimensional data type.

(com.xiaomi.micloud.fit.cycling.wheel_revolution.cu Each data point represents the number of wheel rotations
mulative) from the start of counting to the current time. For details,
please refer to TYPE_CYCLING_PEADING_CUMULATIVE

TYPE_CYCLING_WHEEL_RPM Instantaneous value, one-dimensional data type.

(com.xiaomi.micloud.fit.cycling.wheel.revolutions) Each data point represents an instantaneous
measurement of the wheel rotation rate when riding a
bicycle. This rate is the number of wheel rotations per
minute.

TYPE_DISTANCE_DELTA Non-instantaneous value, one-dimensional data type.

(com.xiaomi.micloud.fit.distance.delta) Each data point represents the distance traveled from the
last read to the present, in meters. The distance traveled
in a certain period of time can be obtained by calculating
the values of all data points in that period of time.
The startTime of a data point is the time when the
distance starts. The startTime of this data point must be
equal to or greater than the endTime of the previous data
point.

TYPE_HEART_RATE_BPM Instantaneous value, one-dimensional data type.

(com.xiaomi.micloud.fit.heart_rate.bpm) Each data point represents the instantaneous
measurement value of a heartbeat. This value is the
number of heartbeats one minute before the
measurement time.
Data type name Data Type Description

TYPE_HEIGHT Instantaneous value, one-dimensional data type.

(com.xiaomi.micloud.fit.height) Each data point represents a measurement of the user's
height in meters.

TYPE_LOCATION_SAMPLE Instantaneous value, multidimensional data type.

(com.xiaomi.micloud.fit.location.sample) Each data point represents the user's location at the
moment of measurement. This data point has 4 fields:

 latitude: float value representing latitude in degrees

 longitude: float value representing longitude in
degrees
 accuracy: float value indicating accuracy, in meters
 altitude: A float value representing the altitude in
meters. Most mobile devices provide altitude
information with a deviation of about 25 meters. To
improve accuracy, use the average of multiple
measurements or use another data source that can
accurately measure altitude. If altitude information
cannot be detected, this field can be left unset.

TYPE_LOCATION_TRACK Non-instantaneous value, multidimensional data type

(com.xiaomi.micloud.fit.location.track) Each data point represents a part of a track, and this data
point may not have an accurate timestamp
Its fields are the same as TYPE_LOCATION_SAMPLE. The
difference between the two is: location.sample has an
accurate timestamp, while location.track has an
inaccurate time interval. location.sample represents the
user's location at a certain point in time, while
location.track represents the user's location during a
certain time interval. For location.track, startTime must be
set, even if its startTime and endTime are the same
Data type name Data Type Description

location.track can be used to record the user's movement

trajectory during a certain activity

TYPE_POWER_SAMPLE Instantaneous value, one-dimensional data type.

(com.xiaomi.micloud.fit.power.sample) Each data point represents an instantaneous
measurement of power in watts. The field value is a float
type.

TYPE_SPEED Instantaneous value, one-dimensional data type

(com.xiaomi.micloud.fit.speed) . Each data point represents an instantaneous velocity on
the ground in meters per second. This value represents a
scalar value of the velocity, so it cannot be negative.

TYPE_STEP_COUNT_CADENCE Instantaneous value, one-dimensional data type.

(com.xiaomi.micloud.fit.step.count.cadence) Each data point represents a measurement of cadence,
which is the number of steps per minute. Cadence
is the sum of both feet. If a sensor can only measure the
cadence of one foot, then the value of the data point
should be twice the value measured by this sensor.

TYPE_STEP_COUNT_DELTA Non-instantaneous value, one-dimensional data type.

(com.xiaomi.micloud.fit.step.count.delta) Each data point represents the number of steps taken
from the last measurement to the current measurement.
When using this data type, each step can only be counted
once. As long as the data in a time period is added
together, the total number of steps taken in this time
period can be easily calculated.
For example, a person took a total of 5 steps and took 3
measurements. The measurement value may be [1, 2, 2].
Both startTime and endTime need to be set, and startTime
must be less than or equal to endTime.
 Data type name Data Type Description

TYPE_WEIGHT Instantaneous value, one-dimensional data type.

(com.xiaomi.micloud.fit.weight) Each data point represents the user's weight at the time of
measurement, in kilograms.

Device
Device describes the device information for collecting user sports and fitness data

Field Name type Optional

manufacturer String required

model String required

version String required

uid String required

type Integer required

DeviceType - Device type

DeviceType refers to the device type for collecting sports and fitness related data. Xiaomi Health Cloud defines some device types,
and currently the device type does not support user-defined extensions. For devices not defined by Xiaomi Health Cloud, the
unknown type should be used. Note: The device type is an enumeration type.
Type Value Type Name

1 unknown

2 phone

3 tablet

4 watch

5 chest_strap

6 scale

7 band

4. SDK download and access instructions

SDK operating release System version
platform date Download Link constraints Access Instructions

Android 2015-07-19 Click to Minimum support: Android Android SDK User

 SDK operating release System version
platform date Download Link constraints Access Instructions

download 2.2 Guide

iOS 2015-07-19 Click to Minimum support: iOS 5.0 iOS SDK User Guide
download

5. FAQ
If you encounter any problems during the integration process, please contact us: [email protected]. You can also add the QQ
group: 385428920, where engineers will answer your questions.