Timezone Information in Terra's wearable integration

Question

Hi, I have a question about timezone information in Terra’s wearable integrations.

For sleep records, does Terra receive the original timezone / UTC offset from the wearable provider before Terra normalises the data?

For example, if a provider such as Oura has a sleep timestamp like:

2023-08-22T22:36:58-04:00

does Terra receive the -04:00 offset as part of the original record?

I’d like to confirm this for Oura as well as other supported providers such as Garmin, Fitbit, etc.

Specifically:

Do the wearable providers send the original timezone/UTC offset to Terra? Does Terra preserve that original offset when normalising the data? Is the original offset available in the sleep data returned by Terra?

Vanessa · Accepted Answer

Hi Khadija,

Yes, Terra preserves the original UTC offset in sleep start_time and end_time whenever the provider includes it in the source record. For your Oura example (2023-08-22T22:36:58-04:00), Terra returns the ISO8601 timestamp with the -04:00 offset intact.

Two fields on the sleep payload tell you how to interpret the timestamps:

metadata.start_time and metadata.end_time: ISO8601 strings with microsecond precision. If the provider gives Terra a UTC offset in the source timestamp, Terra keeps that offset in the returned string.
metadata.timestamp_localization: 0 means the timestamps are UTC, 1 means they are the user's local time. When it is 1, the ISO string carries the local offset (or no offset, if the provider does not send one). This field is nullable, so if it is missing, fall back to reading the offset directly from the ISO string.

For the specific providers you asked about:

Oura sends bedtime_start and bedtime_end as ISO8601 with the offset embedded, and Terra keeps that offset on the returned sleep timestamps.
Garmin sends UTC seconds plus a separate startTimeOffsetInSeconds on the sleep summary. Terra combines the two, so the returned start_time / end_time include the user's local offset.
Fitbit returns naive local time on the sleep log itself (no offset in the raw timestamp), but exposes the user's UTC offset on the Fitbit user profile. Terra uses that profile offset to attach an offset to the sleep timestamps it returns.

If a provider does not surface timezone info at all, the sleep timestamp comes back as a naive local time with no offset appended. That is the "if absent, the time corresponds to the user's local time" case described on the sleep metadata model.

One practical heads-up for cross-data-type alignment: when you match a sleep session to its daily summary, the calendar date of the sleep end_time is more reliable than the offset, because bedtime and daily midnight can fall on different provider "days" during travel or DST transitions.

The full data model reference has the schema definitions in one place if you want to dig further: https://docs.tryterra.co/reference/health-and-fitness-api/data-models

If you want us to confirm the exact offset behavior for a specific user or provider in your account, drop the user ID into a ticket under "Support" on your Terra API dashboard and we will trace a real payload for you.