Clarification on Date Parameter Interpretation for API Calls

[atjames]

We're working with the Fitbit Web API and need some clarification on how date parameters are interpreted for several of your endpoints. For the following endpoints, how should the date parameter be interpreted?

Get Sleep Log by Date:

• Endpoint: GET /1.2/user/-/sleep/date/{date}.json

• Documentation: https://dev.fitbit.com/build/reference/web-api/sleep/get-sleep-log-by-date/

• We understand this uses the user's local calendar date (per your documentation notes about dateOfSleep). Can you confirm?

Get Food Log:

• Endpoint: GET /1/user/-/foods/log/date/{date}.json

• Documentation: https://dev.fitbit.com/build/reference/web-api/nutrition/get-food-log/

• Is the date parameter interpreted as the user's local calendar date or UTC date?

Get Activity Log List:

• Endpoint: GET /1/user/-/activities/list.json?afterDate={date}&...

• Documentation: https://dev.fitbit.com/build/reference/web-api/activity/get-activity-log-list/

• Is the afterDate parameter interpreted as the user's local calendar date or UTC date?

We're experiencing a possible timezone-related issue on our end where users in timezones ahead of UTC experience delays in data updates. When Fitbit sends a webhook with a date field, we parse it as UTC and use that date directly to query your API. For users in timezones ahead of UTC (e.g., Singapore UTC+8), this creates a timing issue:

• User completes sleep at 2:00 AM local time on Jan 16

• At that moment, it's 6:00 PM UTC on Jan 15

• Webhook arrives with "date": "date_string" (user's local calendar date)

• We query /sleep/date/"date_string".json immediately

• At 6:00 PM UTC on Jan 15, querying for Jan 16 may return no data yet, causing a multi-hour delay until UTC "catches up" to that date

Should we query the API using the webhook date string directly (treating it as the user's local calendar date), or do we need to convert it based on the user's timezone first? Any clarification on how these date parameters should be interpreted would be helpful. 🙏

[Gondwana]

(Moved to Web API forum.)

[MariaFitbit · Accepted solution]

Hi @atjames , and welcome to the forums!

You can check out this information on Time Zones for getting Fitbit data: https://dev.fitbit.com/build/reference/web-api/developer-guide/application-design/#Time-Zones
As noted in the documentation, Fitbit does not support time zones for data, so the date and time of the user data is based on their local calendar date. Although, there are some endpoints that support query parameter "timezone=UTC" for returning data at UTC (ex: Heart Rate Time Series). Otherwise, you will need convert it to the user's timezone first before querying.

Let us know if you have further questions!