# Data annotations

Data annotations provide crucial metadata that helps you understand the context and quality of wearable data. These annotations appear in the `additionalDetails` object of epoch and daily, and can significantly impact how you interpret and use the data in your applications.

{% hint style="info" %}
Not all data sources provide every type of annotation. The availability of specific annotations depends on the capabilities and policies of each data source manufacturer.
{% endhint %}

### Timezone UTC Offset

When available, we store and provide the offset to UTC as an integer representing minutes.

**Key**: `timezoneOffset`\
**Type**: Integer (minutes to UTC)\
**Availability**: When timezone information is available from the data source

```json
{
    "startTimestamp": "2025-05-31T11:11:13+06:00",
    "endTimestamp": "2025-05-31T11:11:13+06:00",
    "timezoneOffset": 240,
    "dataTypeId": 0,
    "value": 0,
    "additionalDetails": {}
}
```

**Example**: A value of `240` means the data was recorded in a timezone that is UTC+4 (240 minutes ahead of UTC).

### Generation

When available, we annotate data with information about how it was generated, allowing you to assess data quality and decide whether to rely on it for specific use cases.

**Key**: `generation`\
**Type**: String\
**Availability**: When generation information is directly provided by the data source

<pre class="language-json"><code class="lang-json"><strong>"additionalDetails": {
</strong><strong>    "generation": "smartphone"
</strong>}
</code></pre>

<table><thead><tr><th width="251">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>"manual_entry"</code></td><td>Data was manually entered by a user</td></tr><tr><td><code>"manual_measurement"</code></td><td>Data was recorded by a sensor measurement manually triggered by a user</td></tr><tr><td><code>"automated_measurement"</code></td><td>Data was recorded by a passive sensor measurement</td></tr><tr><td><code>"smartphone"</code></td><td>Data was recorded by a smartphone sensor</td></tr><tr><td><code>"tracker"</code></td><td>Data was recorded by a wearable sensor or medical device</td></tr><tr><td><code>"third_party"</code></td><td>Data was recorded by a third-party app</td></tr><tr><td><code>"calculation"</code></td><td>Data was calculated by Thryve (e.g., daily steps if not provided by manufacturer)</td></tr></tbody></table>

### Medical Grade Certification

When we know a data point was recorded by a device certified by the FDA or equivalent regulatory agency, we annotate the data accordingly.

**Key**: `medicalGrade`\
**Type**: Boolean\
**Availability**: When device certification status is known

```json
"additionalDetails": {
    "medicalGrade": true
}
```

<table><thead><tr><th width="142">Value</th><th>Description</th></tr></thead><tbody><tr><td>True</td><td>Data was recorded by a sensor that can be considered medical/clinical grade</td></tr><tr><td>False</td><td>Data was recorded by a sensor with no clinical validation</td></tr></tbody></table>

### Trustworthiness Assessment

Some data sources like Garmin or Withings evaluate the reliability of measurements based on their algorithms and user feedback. We pass through these assessments to help you evaluate data quality.

**Key**: `trustworthiness`\
**Type**: String\
**Availability**: Only from data sources that provide trustworthiness assessments

```json
"additionalDetails": {
    "trustworthiness": "doubt_from_user"
}
```

| Parameter                           | Description                                                                                                                       |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `"unfavorable_measurement_context"` | Device manufacturer believes recording was made under suboptimal conditions (e.g., during movement when stillness is recommended) |
| `"doubt_from_device_source"`        | Device algorithms flagged the measurement as potentially unreliable                                                               |
| `"doubt_from_user"`                 | User manually tagged the recording as unlikely or implausible                                                                     |
| `"verified_from_device_source"`     | Device manufacturer considers the recording plausible and reliable                                                                |
| `"verified_from_user"`              | User manually verified the recording as accurate                                                                                  |

### **Chronological exactness**

This annotation indicates potential deviations from precise timestamps, measured in minutes.

**Key**: `chronologicalExactness`\
**Type**: Integer (minutes of potential deviation)\
**Availability**: When timestamp precision is uncertain

#### For Daily Data

For daily data, this annotation appears when users have started and ended their day in different timezones, making their "day" shorter or longer than 24 hours. We provide this deviation in minutes when we calculate daily data ourselves through our analytics.

```json
"additionalDetails": {
    "chronologicalExactness": 120
}
```

**Example**: A value of `120` means the day has been 2 hours longer than a normal 24h long day.

### Using Annotations in Your Application

#### Data Quality Assessment

Use generation and trustworthiness annotations to implement data quality filters:

* Prioritize `"automated_measurement"` over `"manual_entry"` for passive tracking
* Consider excluding data marked with `"doubt_from_device_source"` for critical health applications
* Use `medicalGrade: true` data for clinical or medical use cases

#### Timezone Handling

Always consider `timezoneOffset` when:

* Displaying data to users in their local timezone
* Correlating data across different time periods
* Analyzing patterns that depend on local time (sleep, meal times, etc.)

#### Timestamp Reliability

Factor in `chronologicalExactness` when:

* Correlating data from multiple sources
* Analyzing time-sensitive patterns
* Building features that require precise timing

#### Example Implementation

```json
{
  "startTimestamp": "2025-05-31T14:20:00-08:00",
  "endTimestamp": "2025-05-31T14:30:00-08:00",
  "timezoneOffset": -480,
  "dataTypeId": 1000,
  "value": 72,
  "additionalDetails": {
    "generation": "automated_measurement",
    "medicalGrade": false,
    "trustworthiness": "verified_from_device_source",
    "chronologicalExactness": 0
  }
}
```

This data point represents a heart rate measurement that was automatically recorded by a non-medical device in Pacific Standard Time, verified as reliable by the device, with precise timestamps.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.thryve.health/thryve-product-overview/understand/data-annotations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.