Get User Health Metrics
To get the authenticated user's health metrics send an HTTP GET to this URL:
If successful, the method returns a JSON encoded object that contains all the user health metrics. The object is indexed by metric type where each value is an array of [timestamp, value] tuples
Update health metrics
You can update health metrics by sending an HTTP POST request to this URL:
The update method performs an upsert. If the data is not present in the user's account it will be added. If the data is present it will be overwritten by the new value. To delete a value at a particular time pass in a null for the metric value.
If multiple duplicate metrics are present for the same time, later data will overwrite prior data.
The entire update is performed in a single atomic transaction; either all data will be updated or none will.
The POST data must contain JSON encoded health metric data. You may specify data in one of several formats depending on the scenario you need to support.
Scenario #1: Updating multiple metrics for one time point
If you want to update one or more metrics for a single point in time, pass in an object with the data specified below:
| Key | Data type | Description |
|---|---|---|
| timestamp | string (ISO 8601 DateTime) | The date/time of the metric data (required) |
| Metric ID [1] | real number | The value for the metric |
| ... | ||
| Metric ID [N] | real number | The value for the metric |
Where Metric ID is an identifier from the list of valid metric IDs
Examples
Add a weight of 68 kilograms and body fat measurement of 7.8% on January 1, 2016 at noon UTC:
{
"timestamp": "2016-01-01T12:00:00Z",
"weight": 68,
"bodyFat": 0.078
}
Scenario #2: Updating multiple metrics for multiple times
If you want to update one or more metrics for multiple points in time, for example to do a bulk upload, or if the user has recorded multiple entries since the last sync, pass in an object with the data specified below:
| Key | Data type | Description |
|---|---|---|
| Metric ID [1] | Samples object | List of time, value pairs |
| ... | ||
| Metric ID [N] | Samples object | List of time, value pairs |
Where Metric ID is an identifier from the list of valid metric IDs
Metric Samples
The samples object is an object whose keys are the date/time of the metric data, and whose value is the metric value:
| Key | Value |
|---|---|
| Timestamp [1] (ISO 8601 DateTime) | The value for the metric at time [1] |
| ... | |
| Timestamp [N] (ISO 8601 DateTime) | The value for the metric at time [N] |
Examples
Add HRV measurements for 3 days
{
"hrv": [
"2016-01-01T12:00:00Z": 78.2,
"2016-01-02T12:00:00Z": 75.2,
"2016-01-03T12:00:00Z": 66.9,
],
"rmssd": [
"2016-01-01T12:00:00Z": 60,
"2016-01-02T12:00:00Z": 65,
"2016-01-03T12:00:00Z": 63,
],
"pnn50": [
"2016-01-01T12:00:00Z": 0.123,
"2016-01-02T12:00:00Z": 0.098,
"2016-01-03T12:00:00Z": 0.162,
],
}
Valid metric IDs
The following table lists the valid metric ids.
| ID | Units | Description |
|---|---|---|
| active_calories | Kilojoules | Daily calories burned during activity |
| active_distance | Meters | Daily distance traveled during activity |
| active_time | Seconds | Daily time spent during activity |
| bmr_calories | Kilojoules | Daily basal metabolic rate |
| bodyFat | Percent (0 to 1) | The athlete's body fat percentage |
| active_time | Seconds | Daily time spent during activity |
| hrv | real number | The HRV score, as defined by the partner app. Typically a value from 0 to 100(ish) |
| highly_active_time | Seconds | Daily highly active time |
| maximumHeartrate | Beats per minute | The athlete's maximum heart rate |
| pnn50 | Percent (0 to 1) | The percentage of successive beats that vary by greater than 50 milliseconds |
| restingHeartrate | Beats per minute | The athlete's resting heart rate |
| rmssd | Miliseconds | The root mean square of successive distances for heart rate beats |
| sleep_phase_awake | Seconds | Daily time spent awake during sleep period |
| sleep_phase_deep | Seconds | Daily time spent in deep sleep |
| sleep_phase_light | Seconds | Daily time spent in light sleep |
| sleep_phase_rem | Seconds | Daily time spent in rem sleep |
| sleep_phase_unknown | Seconds | Daily time spent in an unknown sleep phase |
| sleep_time | Seconds | Daily total time spent sleeping |
| steps | Count | Daily total steps |
| weight | Kilograms | The athlete's body weight |
Metric Values
Most metrics support a single floating point value. If extended metric data is supported, provide it in a two value array:
[ <summary_value>, <extended_value> ]
Extended Values
You may provide 15-minute totals in the extended data as an array for the following metrics:
- active_calories
- active_distance
- active_time
- highly_active_time
- steps
The 15-minute intervals start at midnight local time, so element 0 is the total for 0:00 to 0:15, element 1 is for 0:15 to 0:30, 2 = 0:30 to 0:45, etc. The example below illustrates walking 20 steps between 1:00am and 1:15am, followed by 40 steps between 2:30am and 2:45am:
[ 0, 0, 0, 0, 20, 0, 0, 0, 0, 0, 40 ]
The sleep_time metric supports an extended value object with two elements: bedtime, waketime, both of which are the number of seconds offset from midnight. The example below illustrates the extended data to specify a 9pm bed time and 6am wake time:
{
bedTime: -10800
wakeTime: 21600
}
The following metrics support an extended value that specifies when sleep phases started and ended:
- sleep_phase_awake
- sleep_phase_deep
- sleep_phase_light
- sleep_phase_rem
- sleep_phase_unknown
Phase times are represented as an array of two element arrays where element 0 = seconds offset from midnight when phase started and element 1 = duration of phase. The example below illustrates a 10 minute phase that starts at 9pm, and a 20 minute phase which starts at 1am:
[ [ -10800, 600 ], [ 3600, 1200] ]