​
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, 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
Lab Testingcholesterol, igg, ige

​
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
Bodybody_temperature, body_temperature_delta, insulin_injection
Vitalsafib_burden, heart_rate_alert
Cardiorespiratoryvo2_max
Nutritioncarbohydrates, caffeine, water
Wellnessmindfulness_minutes
Diarynote

​
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

​
Sleep Stream

​
Workout

​
Workout Stream

Soon. Work in progress.

​
Profile

Soon. Work in progress.

Supported providersSynthetic Data (Sandbox)