Data Model

Your user's data is flowing in, and you want to build something awesome? Great! But first, you need to understand how we organize this data - picking the right approach will save you headaches later.

Thryve processes and stores wearable data using two primary temporal frameworks: epoch data and daily data. Understanding the distinction between these approaches is crucial for proper data interpretation and application development.

Aspect	Epoch Data	Daily Data
Time Reference	Absolute timestamps or timeframes	Calendar date in user's local timezone
Precision	High (seconds)	Low (daily aggregates)
Data Volume	Up to hundreds of records per day per data source per data type	One value per data source per data type per day
Uniqueness	dataSourceId, thirdPartyDataSourceId, dataTypeId, startTimestamp, generationType	dataSourceId, dataTypeId, day

Epoch data

Epoch data represents continuous, timestamped measurements collected at specific moments in time. This data maintains precise temporal accuracy and is ideal for detailed analysis of patterns, trends, and health and activity monitoring.

Key Characteristics

Granularity: Varies significantly based on data sources and devices used by the end user. Sensors in wearables typically record data at high sampling rates (50Hz and higher), which manufacturers transform into digestible values. The granularity of these processed values depends on the manufacturer's philosophy:

• Withings: Provides step data in chunks of a maximum 10 minutes (during walking periods)

• Polar: Aggregates data on an hourly level

• Fitbit: Only provides intraday data for sleep periods and workout recordings without special access

Granularity also depends on measurement context. Some data sources generate more granular data during workout recordings triggered by end users compared to passive measurements throughout the day.

Thryve always stores data at the highest possible granularity and does not pre-aggregate epoch data.

Temporal Precision:

• For point-in-time measurements (e.g., weight, sometimes heart rate), only startTimestamp is provided

• For duration-based data (e.g., activity periods, avg heart rate over a period), both startTimestamp and endTimestamp are provided

• All timestamps maintain seconds-level precision

Timestamp Formats: Data is provided by Thryve in your preferred format:

• ISO 8601 with timezone information (when available) and additional timezoneOffset in minutes to UTC - recommended for human-readable applications

• Unix timestamp in milliseconds (UTC) with timezoneOffset in minutes to UTC - recommended for programmatic processing

ISO 8601

{
  "startTimestamp": "2025-05-31T09:33:59+01:00",
  "endTimestamp": "2025-05-31T09:34:59+01:00",
  "timezoneOffset": 60,
  "dataTypeId": 0,
  "value": 0,
  "additionalDetails": {}
}

Unix timestamp in milliseconds

Daily data

Daily data represents aggregated measurements organized by calendar days in the user's local timezone. This data is designed for simplified consumption and day-over-day comparisons.

Key Characteristics

Enhanced data availability: Daily aggregates provided directly by data sources may extend beyond available epoch data for a given user and data source. For example, Fitbit provides intraday data only when users actively trigger activity recording, while daily values include passive measurements throughout the entire day.

Timezone Handling:

• The day field represents a calendar date in the user's local timezone

• timezoneOffset provides the offset to UTC in minutes

• For users traveling across timezones within a single day, timezoneOffset reflects the timezone where more data was recorded

Timestamp Formats: Data is provided by Thryve in your preferred format:

• ISO 8601 date: Simple date string (YYYY-MM-DD) representing a calendar date in the user's local timezone - recommended for user interfaces

• Unix timestamp: Milliseconds midnight UTC for the date - recommended for calculations and storage

timezoneOffset reflects the offsent in minutes to UTC timezone where data was recorded

Timezone Travel Detection: When users cross timezones during a calendar day, the actual duration of their "day" may not be exactly 24 hours. The chronologicalExactness field captures this deviation in minutes:

• Positive values: Day was longer than 24 hours (e.g., +60 minutes when traveling westward and "gaining" an hour)

• Negative values: Day was shorter than 24 hours (e.g., -60 minutes when traveling eastward and "losing" an hour)

• Null: Standard 24-hour day with no significant timezone changes

For values that are not exactly 24 hours, timezoneOffset reflects the timezone where more data was recorded.

Timezone Travel Detection logic only applies when data is aggregated and calculated by Thryve, not when daily data is directly provided by the data source.

Smart Overlap Detection: When daily data is calculated and aggregated by Thryve, intelligent mechanisms prevent value inflation through smart overlap detection within the same data type and data source. This ensures accurate aggregation when data is recorded simultaneously by multiple devices (e.g., both smartphone and fitness tracker), preventing double-counting of activities like steps or calories.

Smart Overlap Detection logic only applies when data is aggregated and calculated by Thryve, not when daily data is directly provided by the data source. Data sources may use similar logics, however, no official documentation on how aggregates are created is available.

ISO 8601

{
    "day": "2025-05-31",
    "timezoneOffset": 60,
    "dataTypeId": 0,
    "value": 0,
    "additionalDetails": {}
}

Unix timestamp in milliseconds

When to Use Each

Choose Epoch Data When:

• Building detailed health and activity dashboards or monitoring systems

• Requiring intraday breakdowns for comprehensive health and activity assessment

• Performing detailed temporal analysis or pattern recognition

• Analyzing user behavior patterns throughout specific time periods

• Correlating data across different timezones

Choose Daily Data When:

• Creating simple user-facing summaries and progress reports

• Building day-over-day comparison features

• Generating weekly or monthly trend reports

• Minimizing data processing complexity

• Reducing bandwidth requirements for mobile applications

Implementation Considerations

Data Volume: Epoch data can generate hundreds of records per day per data type, while daily data provides one consolidated value. Plan storage and bandwidth accordingly.

Timezone Complexity: Daily data simplifies timezone handling for basic use cases, while epoch data provides maximum flexibility for complex temporal analysis.