​
Overview

There are two broad resource categories provided by Vital:
  • 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 among 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 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

GranularityResources
Dailyactivity
Sessionsleep, sleep_cycle, workouts, body, meal, menstrual_cycle, electrocardiogram, workout_stream
Singleprofile

​
Discrete Timeseries types

Each value is associated with a single point in time.
CategoryResources
Cardiorespiratoryrespiratory_rate
Vitalsblood_oxygen, blood_pressure, glucose, heartrate, hrv, electrocardiogram_voltage
Wellnessstress_level
Bodyfat, weight

​
Interval Timeseries types

Each value is associated with a half-open time interval ([start, end[).
CategoryResources
Activitycalories_active, calories_basal, distance, floors_climbed, steps, workout_duration, fall, wheelchair_push, stand_duration, stand_hour
Bodybody_temperature, body_temperature_delta, insulin_injection, waist_circumference, body_mass_index, lean_body_mass, basal_body_temperature
Vitalsafib_burden, heart_rate_alert, forced_expiratory_volume_1, forced_vital_capacity, peak_expiratory_flow_rate, inhaler_usage, heart_rate_recovery_one_minute
Cardiorespiratoryvo2_max
Nutritioncarbohydrates, caffeine, water
Wellnessmindfulness_minutes, sleep_apnea_alert, sleep_breathing_disturbance, uv_exposure, daylight_exposure, handwashing
Workout Streamworkout_distance, workout_swimming_stroke
Diarynote

​
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 of 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 rateExample Scenario
1 sample every 3 secondsApple Watch workouts
1 sample every 15 secondsGarmin
1 sample every 1-15 minuteApple Watch, Fitbit
Resources that fall into this category:
ResourceEventsNotable Providers
heartratedaily.data.heartrate.*Apple, Fitbit, Garmin
calories_activedaily.data.calories_active.*Apple, Fitbit, Garmin

​
High frequency Timeseries

Minute-level peak sampling rate; typically 100s samples per day.
Peak rateExample Scenario
1 sample every 1 minuteFitbit Intraday timeseries data
1 sample every 15 minutesGarmin all-day activity timeseries data (“epochs”)
Resources that fall into this category:
ResourceEventsNotable Providers
stepsdaily.data.steps.*Apple, Fitbit, Garmin
calories_basaldaily.data.calories_basal.*Apple
distancedaily.data.distance.*Apple, Fitbit, Garmin
glucosedaily.data.glucose.*LibreView, Dexcom
stress_leveldaily.data.stress_level.*Garmin
hrvdaily.data.hrv.*Garmin, Fitbit
respiratory_ratedaily.data.respiratory_rate.*Garmin, Fitbit
blood_oxygendaily.data.blood_oxygen.*Fitbit
daylight_exposuredaily.data.daylight_exposure.*Apple
stand_durationdaily.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 rateExample Scenario
1 sample every dayApple Watch wrist temperature delta
1 sample every 15 minutesGarmin all-day activity timeseries data (“epochs”)
Unpredictable / NeverHeart 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 an 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 resources. You can fetch it via timeseries/<user_id>/heartrate and 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 ele_high nor ele_low.
Providers mark with * means that Vital calculates the field’s value. In some cases, they might came as null, since we weren’t able to make the calculation.
Even if a field is available for a provider, it doesn’t mean it’s available. 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