SportTracks REST API: Health Metrics

Get User Health Metrics

To get the authenticated user's health metrics send an HTTP GET to this URL:

https://api.sporttracks.mobi/api/v2/metrics

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:

http://api.sporttracks.mobi/api/v2/metrics

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

Daily Detail Metrics

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 ]

Daily Sleep Metric

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
}

Sleep Phase Metrics

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]
]