Date and time

Date formats

The API accepts dates in ISO8601 / RFC3339 format. Both UTC timestamps (ending in Z, example 2024-07-01T12:00:00Z) and timestamps with an offset (ending in “+05:00”, example 2024-07-01T12:00:00+05:00) are accepted.

The API will always return dates in UTC (ending in Z, example 2024-07-01T12:00:00Z)

Time zones

The ISO8601 / RFC3339 date format supports specifying a fixed UTC offset, but it doesn’t support specifying a timezone name like Europe/Madrid. This is a problem for timezones that use Daylight Savings Time (DST), since their UTC offset changes depending on the time of the year.

For example, central Europe is at UTC+1 in winter and UTC+2 in summer. If you want check-out time to be “at 12PM, local time” you can’t just append a fixed UTC offset. +01:00 is correct in winter but wrong in summer, and +02:00 vice-versa.

The solution is to use a date-time library to convert dates to UTC before sending them to the API. Example for Javascript using moment.js:

// Convert local time to UTC
moment.tz('2024-01-01T12:00:00', 'Europe/Madrid').tz("UTC").format()
// Returns: '2024-01-01T11:00:00Z'

Schedules

The only place in the API that uses local time is the schedule object. The reason is you typically want a schedule like Mon-Fri 9AM-6PM to be applied in local time, so it automatically adjusts as local time enters and exists DST.

The schedule is interpreted according to the timezone specified in the site object. This way the same schedule can be used in multiple sites in different timezones, and it’ll work correctly in the local timezone for each.