Home

Huami Web API Documents for Developers

Huami provides Web API for accessing user activity data tracked with Huami wearable-devices. Anyone can develop an application to access user’s data on their behalf, as long as the user has granted consent to do so.

1. Overview

Welcome to the Huami API document.

Huami is the second largest manufacturer of wearables in the world. Our mission is to seamlessly connect our biomechanical signals and daily activities with smart data services to promote an active and healthy lifestyle while making our lives easier.

2. App Registration

Please send registration email to partner@huami.com, with a short introduction to your organization and your application. In the follow-up registration emails, typically you need to provide information about an application such as:

Application name

Logo (CDN) URLs for the application

Logo should contain name, and there should be one logo per language, such as English, Chinese, Japanese, Korean, and so on. URLs should all be httpS. E.g.

httpS://CDN/en.SVG
httpS://CDN/zh.SVG

(CDN) URLs for users to obtain details of the application during authorization & admin

There should be one URL per language, such as English, Chinese, Japanese, Korean, and so on. E.g.

httpS://CDN/en.HTML
httpS://CDN/zh.HTML

A short description of the application

A link to the application’s privacy policy

A list of redirect URIs. This is required for Web apps only. If you build native Android and/or iOS apps, redirect URIs can be skipped. Instead, our User Consent SDK will return the authorization result.

Redirect URIs

Redirect URIs are a critical part of the OAuth flow. After a user successfully authorizes an application, the authorization server will redirect the user back to the application with either an authorization code or an access token in the URL. Because the redirect URI will contain sensitive information, it is critical that the service doesn’t redirect the user to arbitrary locations.

For users' privacy, non-app-protocol URIs should be httpS instead of http.

Unless ending with unencoded # or ?, # or ? will be appended. If URI contains unencoded #, ? will be appended unless ending with # or ?. Otherwise # will be appended unless ending with # or ?.

Scopes

Scope

Description

profile

The profile scope is the basic user information

activity

The activity scope includes activity data, such as steps, distance, calories consumed, and active minutes

sleep

The sleep scope includes sleep logs and computed summary, such as sleep start time, wake time, duration of sleep

The motion scope includes raw motion sensor data per minute of a day, consists of 1440(total minutes of one day)*3 bytes

notifyme

allows 3rd-party applications to send notifications to a user, who typically gets notified by wristband/watch vibration, and then views the text message on wearables. Optionally, the user can tap their wearables, to acknowledge they have read the message. The read receipt will be pushed back to the message sender, see 5. Subscriptions.

sport

Including summary data for user activities like cycling, running

sportDetail

Including detail data for user activities like cycling, running

3. Authentication

OAuth 2.0 is supported for user authorization and API authentication. As the OAuth 2.0 framework defines, your applications need to obtain an Access Token when a Huami user authorizes your app to access their data. The Access Token should always be included in every HTTP request to Huami Web API. A Refresh Token should be preferrably obtained at the same time. For security season, Access Token has a short lifetime, while Refresh Token is designed to renew Access Tokens.

Obtaining User Consent and Tokens (SDK for Native Mobile App)

Huami provides SDK for native mobile apps. End users do not necessarily enter their user name and password again, but simply click agree button to grant consent. The SDK launches Huami Mifit app or Huami Amazfit app, which users usually have already installed and signed in to view their activity data on a daily basis.
See the document below to integrate Huami User Consent SDK to your app.

can be multiple, for protected user data not to be authorized by default, e.g. "profile" property "weight" isn’t included by default, 3rd party can ask for "weight" explicitly by specifying "scope=profile+weight" (after encoding space ' ' to '+')

-PROPERTY

No

can be multiple, to reduce bandwidth, e.g. "heartrate-sync" to exclude Sync Time

DEVICE

No

can be multiple, data @ all devices will be authorized if none specified. equator/MoonBeam/arc/pace so far

D9~18

No

can be multiple, data @ all dates/times will be authorized if none specified.
D for day, such as

lower case 's' for Sunday

'M' for Monday

'T' for Tuesday

'W' for Wednesday

't' for Thursday

'F' for Friday

upper case 'S' for Saturday

Time range is optional, data @ whole day will be authorized if none specified. E.g. 10~18 for 10am through 6pm, default starting time is 0 if unspecified & default ending time is 24 if unspecified

data

properties

profile

userId

gender

height

weight (excluded by default)

nickName

avatar

activity_daily

date (always included)

lastSyncTime

steps

distance

calories

activity_hourly

date (always included)

lastSyncTime

time (always included)

steps

calories

sleep_daily

date (always included)

lastSyncTime

start

stop

deepSleepTime

shallowSleepTime

wakeTime

sleep_hourly

date (always included)

lastSyncTime

start

stop

mode

motion

date (always included)

lastSyncTime

activeness

mode

steps

heartrate

date (always included)

lastSyncTime

heartRateData

User denying or failed authorization will also be redirected E.g. (see above for # or ? appending)

httpS://REGISTERed#error=ERROR&state=BLACK_BOX

Authorization Code Grant Flow

Authorization Code Grant Flow is a preferred for security. Please see RFC 6749. Authorization Code will be redirected for above "response_type=code" E.g.

httpS://REGISTERed?code=AUTHORIZATION&state=BLACK_BOX

Exchanging an Authorization Code for an Access Token

Once your service receives an Authorization Code, use it to exchange for access token.

Do not store your client secret in your client appliction. Making the request from a backend server protects your client secret from being stolen.

The authorization code will expire after 5 minutes and you will receive error like {"code":-1004, "message":"Invalid parameter 'code'"}

Implicit Grant Flow

In the implicit flow, instead of issuing the client an authorization code, the client is issued an access token directly. However, this convenience should be weighed against the security implications of using implicit grants, such as being exposed to unauthorized parties (when the access token is transmitted in the URI fragment), or misuse of access token to impersonate resource owner.

Making Requests

To make a request to the HuaMi Data API using OAuth 2.0, simply add an Authorization header to the HTTP request with the user’s access token. See 4. Accessing Data for detailed description of all data APIs.

Token Life Cycle

Access Token

The default lifetime of accessToken is 90 days, if user revoke the authorization to 3rd party, the token will be out of work immediately. If developer has special requirement, contact the service provider to modify the token lifetime

Refresh Token

The default lifetime of refreshToken is 10 years.

4. Accessing Data

5. Subscriptions

Subscription notification is not available yet.

Subscription notification is a near real-time solution to allow third-party applications to be notified when certain event happpens on Huami users. Your applications can listen and wait to receive the lastest user state-changed events, rather than constantly polling on user data.

This is a complementary technology to calling Web API. The content in notifications may not have all information your application needs. In that case, you application must make appropriate Web API calls to retrieve the actual data, see 4. Accessing Data. Also, for many reasons, notifications do NOT guarantee 100% delivery success rate. Your application design should accommodate that, e.g. retrieve user data, periodically or when your application being brought to foreground.

Notifications are essentially HTTP requests made by Huami to a URI you registered. Thus you will implement a service behind the URI, to process incoming requests and to interpret the event content inside.

To receive notification, your application also needs to obtain user consent, see 3. Authentication. Huami does NOT send you the notifications of users whose consent is NOT current. Similarly, only data types of the scopes allowed by the user will be sent.

Implementing Subscription Web API

You can choose any modern Web technology to implement your service, following the API definition below.

Design for High Availabity and Low Latency

Your service should respond as soon as possible. Store received events locally and process them later asynchorously. If your service cannot respond in two seconds, Huami will mark your service as failed to respond. Huami will retry three times in one minute, and eventually stop your subscription without warning.

HTTPS Only

To provent user data from being compromised on Internet trafic, Huami always sends HTTPS requests to default port 443. You must register a URI starting with HTTPS://.

Self-signed certificates are not supported.

Verifying the Request

Huami puts a Huami-Signature header in every request for security. Your service must verify the imcoming requests have not been tampered. Signature verfication success proves the content of the request is indeed generated by Huami.

Attachers may resend or playback the request if they ever captured the request payload. Your service should handle those repeated requests, just like the same notification has been delivered more than once.

Huami-Signature

Signature is computed from the notification request payload with the standard RSA-SHA1 algorithm. The signature will be BASE64 encoded and then URL encoded. Pseudo code:

Your service decodes the signature in the opposite way as Huami did, then verifies the signature with the request body. If signature verification fails, your service should stop processing that notification.

Registering Subscription

Once you have completed your service code and deployed it on production environment, see 2. App Registration to register the URI. You are all set.

6. Help

If you encounter any issue, please try to search historical issue list first. If there is no similar issue or question, feel free to create a new one, and we will respond to all open issues in time.