> ## Documentation Index
> Fetch the complete documentation index at: https://docs.junction.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

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

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

<iframe src="https://airtable.com/embed/shrYd0PGVhx5lTemu?backgroundColor=gray&layout=card" frameborder="0" allowfullscreen="true" width="100%" height="1200" loading="lazy">
  {" "}
</iframe>

## Timeseries types by providers

<iframe src="https://airtable.com/embed/shrtq9mZDz6BRXuz2?backgroundColor=gray&layout=card" frameborder="0" allowfullscreen="true" width="100%" height="1200" loading="lazy">
  {" "}
</iframe>

## Fetching via the API

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

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:

```json theme={null}
{
  "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:

```json theme={null}
[
  {
    "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`.

<Note>
  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.
</Note>

<Warning>
  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**.
</Warning>

### Activity

<iframe src="https://airtable.com/embed/shrD7PACtmC22z1am?backgroundColor=gray&layout=card" frameborder="0" allowfullscreen="true" width="100%" height="1200" loading="lazy">
  {" "}
</iframe>

### Body

<iframe src="https://airtable.com/embed/shrcmdPTp4rOx0mBp?backgroundColor=gray&layout=card" frameborder="0" allowfullscreen="true" width="100%" height="1200" loading="lazy">
  {" "}
</iframe>

### Sleep

<iframe src="https://airtable.com/embed/shr6TCkBRAtQMza6v?backgroundColor=gray&layout=card" frameborder="0" allowfullscreen="true" width="100%" height="1200" loading="lazy">
  {" "}
</iframe>

### Workout

<iframe src="https://airtable.com/embed/shrUXlA77h6Leg7tD?backgroundColor=gray&layout=card" frameborder="0" allowfullscreen="true" width="100%" height="1200" loading="lazy">
  {" "}
</iframe>