Intro

At Vital, a resource represents a set of fields. Each resource is an abstraction for the different categories of data available for each provider. We currently support two kinds of resources: summary and timeseries. Summary resources are made up of many fields. While timeseries represent the values of a single field over time.

Summary types

GranularityResources
Dailyactivity
Sessionsleep, workouts, body, meal, workout_stream, sleep_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
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
Cardiorespiratoryvo2_max
Sleephypnogram
Nutritionwater, caffeine
Wellnessmindfulness_minutes

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.