Resources

Understand the two wearable data categories in Junction: Summaries for daily aggregates and Timeseries for granular time-stamped measurements.

Overview

There are two broad resource categories provided by Junction:

• A Summary type is a summarization of a specific calendar day or a session.
• A Timeseries type is a time-ordered collection of data samples.

There is no relation in resource availability between these two categories. Some providers do offer both, while some providers offer only one category. For example:

• Fitbit provides daily activity summaries, as well as some high-frequency activity timeseries data.
• Oura provides only a daily activity summary, without any complementary high-frequency activity timeseries data.

There is also no strict relation between a field in a Summary type and a Timeseries type. For example:

• The existence of a sleep_efficiency summary field does not imply that there is a corresponding sleep_efficiency timeseries.
• The existence of a Glucose Timeseries type does not imply that there is a corresponding glucose summary field.
• A Timeseries type could derive multiple summary fields, e.g., heart rate statistics and HR zones.

Summary types

Granularity	Resources
Daily	activity
Session	sleep, sleep_cycle, workouts, body, meal, menstrual_cycle, electrocardiogram, workout_stream
Single	profile

Discrete Timeseries types

Each value is associated with a single point in time.

Category	Resources
Cardiorespiratory	respiratory_rate
Vitals	blood_oxygen, blood_pressure, glucose, heartrate, hrv, electrocardiogram_voltage
Wellness	stress_level
Body	fat, weight

Interval Timeseries types

Each value is associated with a half-open time interval ([start, end)).

Category	Resources
Activity	calories_active, calories_basal, distance, floors_climbed, steps, workout_duration, fall, wheelchair_push, stand_duration, stand_hour
Body	body_temperature, body_temperature_delta, insulin_injection, waist_circumference, body_mass_index, lean_body_mass, basal_body_temperature
Vitals	afib_burden, heart_rate_alert, forced_expiratory_volume_1, forced_vital_capacity, peak_expiratory_flow_rate, inhaler_usage, heart_rate_recovery_one_minute
Cardiorespiratory	vo2_max
Nutrition	carbohydrates, caffeine, water
Wellness	mindfulness_minutes, sleep_apnea_alert, sleep_breathing_disturbance, uv_exposure, daylight_exposure, handwashing
Workout Stream	workout_distance, workout_swimming_stroke
Diary	note

Timeseries Data Sampling Rates

Junction records and forwards timeseries data from the data provider, without any upsampling or downsampling applied. Even within the same data provider, these data may come from different devices or data sources with varying sampling rates.

Because of this, you should not make assumptions about any particular timeseries resource having a fixed sampling rate.

For technical design and capacity planning purposes, you may model after the following three categories of timeseries resources:

Very High Frequency Timeseries

Second-level peak sampling rate; typically 1000s to low 10000s samples per day.

Peak rate	Example Scenario
1 sample every 3 seconds	Apple Watch workouts
1 sample every 15 seconds	Garmin
1 sample every 1-15 minutes	Apple Watch, Fitbit

Resources that fall into this category:

Resource	Events	Notable Providers
heartrate	daily.data.heartrate.*	Apple, Fitbit, Garmin
calories_active	daily.data.calories_active.*	Apple, Fitbit, Garmin

High Frequency Timeseries

Minute-level peak sampling rate; typically 100s samples per day.

Peak rate	Example Scenario
1 sample every 1 minute	Fitbit Intraday timeseries data
1 sample every 15 minutes	Garmin all-day activity timeseries data (“epochs”)

Resources that fall into this category:

Resource	Events	Notable Providers
steps	daily.data.steps.*	Apple, Fitbit, Garmin
calories_basal	daily.data.calories_basal.*	Apple
distance	daily.data.distance.*	Apple, Fitbit, Garmin
glucose	daily.data.glucose.*	LibreView, Dexcom
stress_level	daily.data.stress_level.*	Garmin
hrv	daily.data.hrv.*	Garmin, Fitbit
respiratory_rate	daily.data.respiratory_rate.*	Garmin, Fitbit
blood_oxygen	daily.data.blood_oxygen.*	Fitbit
daylight_exposure	daily.data.daylight_exposure.*	Apple
stand_duration	daily.data.stand_duration.*	Apple

Sparse Timeseries

All timeseries resources not specified as (Very) High Frequency fall into this category.

Day-level peak sampling rate; typically no more than 5 per day.

Peak rate	Example Scenario
1 sample every day	Apple Watch wrist temperature delta
1 sample every 15 minutes	Garmin all-day activity timeseries data (“epochs”)
Unpredictable / Never	Heart Rate Alerts, Sleep Apnea Alerts

Summary types by providers

Timeseries types by providers

Fetching via the API

Summary resources can be fetched from our /summary/<resource>/<user_id> API, while everything else via /timeseries/<user_id>/<resource>.

For example, Workouts is made up of fields specific to a workout, like calories, distance and duration. When you make a request to /summary/workouts/<user_id> you get the following fields:

{
  "workouts": [
    {
      "user_id": "a6fea8eb-402f-4578-96ba-189df1a8ca75",
      "user_key": "a6fea8eb-402f-4578-96ba-189df1a8ca75",
      "id": "12398c74-ea41-4d9c-a1b7-8c529ee67e46",
      "title": null,
      "timezone_offset": 3600,
      "average_hr": 147,
      "max_hr": 178,
      "distance": 31557.85,
      "time_start": "2022-07-29T12:05:49+00:00",
      "time_end": "2022-07-29T13:26:08+00:00",
      "calories": 729.0,
      "sport": {
        "id": 108,
        "name": "Road Biking",
        "slug": "road_biking"
      },
      "hr_zones": [
        5,
        76,
        288,
        1467,
        2148,
        835
      ],
      "moving_time": 4819,
      "total_elevation_gain": 374.0,
      "elev_high": null,
      "elev_low": null,
      "average_speed": 6.548,
      "max_speed": 17.448,
      "average_watts": null,
      "device_watts": null,
      "max_watts": null,
      "weighted_average_watts": null,
      "map": null,
      "provider_id": "9297103021",
      "source": {
        "name": "Garmin",
        "slug": "garmin",
        "logo": "https://storage.googleapis.com/vital-assets/garmin.png"
      }
    }
  ]
}

Heartrate on the other hand, is a timeseries resource. You can fetch it via timeseries/<user_id>/heartrate and it looks like this:

[
  {
    "timestamp": "2022-04-29T08:35:57+00:00",
    "timezone_offset": 3600,
    "value": 174.0,
    "type": null,
    "unit": "bpm"
  },
  {
    "timestamp": "2022-04-30T11:22:38+00:00",
    "timezone_offset": 3600,
    "value": 79.0,
    "type": null,
    "unit": "bpm"
  },
  {
    "timestamp": "2022-04-30T11:22:39+00:00",
    "timezone_offset": 3600,
    "value": 80.0,
    "type": null,
    "unit": "bpm"
  },
  {
    "timestamp": "2022-04-30T11:22:40+00:00",
    "timezone_offset": 3600,
    "value": 78.0,
    "type": null,
    "unit": "bpm"
  },
  {
    "timestamp": "2022-04-30T11:22:41+00:00",
    "timezone_offset": 3600,
    "value": 78.0,
    "type": null,
    "unit": "bpm"
  }
]

Different providers (e.g., Garmin) have different resources available. As an example, Garmin doesn’t have Glucose as a resource.

Fields by Provider

Resources alone are not the whole story. Depending on the provider, a field might not be available. For example, both Garmin and Strava provide Workouts, yet the former doesn’t have elev_high or elev_low.

Providers marked with * mean that Junction calculates the field’s value. In some cases, they might come as null, since we weren’t able to make the calculation.

Even if a field is listed for a provider, it doesn’t mean it will always contain data. For example, Fitbit is capable of generating HRV data. However, HRV data is only available for specific high-end devices. Another common scenario is Apple HealthKit data. If the user doesn’t give permission to a particular field, it won’t be available. Be mindful of these situations and similar ones.

Activity

Body

Sleep

Workout