Data annotations

Context matters. How was data recorded? What sensor captured it? In which timezone? Was it manually entered or automatically detected? We provide all annotations so you can make informed decisions

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.

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.

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

{
    "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

"additionalDetails": {
    "generation": "smartphone"
}

Parameter	Description
"manual_entry"	Data was manually entered by a user
"manual_measurement"	Data was recorded by a sensor measurement manually triggered by a user
"automated_measurement"	Data was recorded by a passive sensor measurement
"smartphone"	Data was recorded by a smartphone sensor
"tracker"	Data was recorded by a wearable sensor or medical device
"third_party"	Data was recorded by a third-party app
"calculation"	Data was calculated by Thryve (e.g., daily steps if not provided by manufacturer)

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

"additionalDetails": {
    "medicalGrade": true
}

Value	Description
True	Data was recorded by a sensor that can be considered medical/clinical grade
False	Data was recorded by a sensor with no clinical validation

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

"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.

"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

{
  "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.