Timezone

The Timezone endpoint provides the user's UTC offset over a requested range as {date, value} rows, where value is the offset in minutes and date is the day that offset was recorded. Use this to convert UTC timestamps in timeseries and event data to the user's local time.

GET /v1/timeline/events/timezones/{user_id}

Parameters

Name	Type	In	Description
user_id	UUID	Path	The unique identifier for the user.
start_date	Date	Query	The start date for the query period (format: YYYY-MM-DD).
end_date	Date	Query	The end date for the query period (format: YYYY-MM-DD).
days	Int	Query	Days per page (default 7, max 30). Values above the max are clamped, not rejected. Ignored for text/csv.
cursor	Str	Query	Opaque pagination cursor from the previous page's next_cursor. application/json only.

Response Formats

Header Value	Format
application/json	JSON (default)
text/csv	CSV

Example Request (JSON)

cURL

curl -X GET "https://api.polsen.health/v1/timeline/events/timezones/YOUR_USER_ID?start_date=2024-04-01&end_date=2024-04-07" \
     -H "accept: application/json" \
     -H "X-API-KEY: YOUR_API_KEY"

Example Response

200 OK

{
  "data": [
    {
      "date": "2024-04-01",
      "value": 120
    },
    {
      "date": "2024-04-08",
      "value": 120
    }
  ],
  "next_cursor": null
}

When more pages remain, next_cursor is a token to pass back as cursor, and the response carries a Link: <...>; rel="next" header. Walk pages until next_cursor is null.

Rows are keyed on the day the offset was recorded

A row's date is the day the offset was recorded, which may fall before the page you requested: a day with no recorded offset inherits the most recent one from up to 14 days earlier. A source day is reported on the first page that reaches it and not repeated afterwards, so concatenating every page gives each date exactly once, in ascending order. A page can legitimately come back empty while later pages still hold data, so follow next_cursor rather than stopping at the first empty page.

Example Request (CSV)

cURL

curl -X GET "https://api.polsen.health/v1/timeline/events/timezones/YOUR_USER_ID?start_date=2024-04-01&end_date=2024-04-07" \
     -H "accept: text/csv" \
     -H "X-API-KEY: YOUR_API_KEY"

CSV is a bulk format: it returns the whole requested range in one response and ignores days. Passing cursor with Accept: text/csv is a 400.

Example Response (CSV)

200 OK

date,value
2024-04-01,120
2024-04-08,120

Applying timezones

To convert UTC timestamps to local time, look up the value (offset in minutes) for the date of each sample and add that offset. A positive value (e.g. 120) means UTC+02:00; a negative value means west of UTC.