ZoomCharts Documentation

Time Zone Support

Time Chart supports specifying a custom time zone for both each data source and the time axis. The recommended approach is that the data is always returned in UTC but the time axis uses a time zone that the user has selected manually.

Note that proper support of time zones with daylight saving time was implemented in version 1.12.0.

Supported time zones

Time Chart uses moment-timezone library to support different time zones and their daylight saving rules.

A list of valid time zone identifiers can be found on Wikipedia.

The chart also supports a special time zone identifier local which, if specified, will translate to the time zone used by the end-users browser. Note however that this is only supported for the time axis configuration and will result in a warning in the console because due to browser limitations it is not always possible to correctly determine the time zone. See moment documentation for details.

Data sources

The time zone for the data is specified in the data response (data file) and not in the settings. The default time zone of the chart data sources is UTC.

This time zone is used to parse time values that do not specify explicit time offset. For example 2015-01-01 12:00:00 would be assumed to be the time in the time zone of the data while for 2015-01-01 12:00:00+02:00 the offset included offset +02:00 would be used instead.

Note that numeric timestamps are always assumed to be UTC. For example, if you specify value 1420149600000 it is parsed as 2015-01-01 22:00:00+00:00. However in this case if the data time zone is Europe/Riga, the time will be converted to that time zone, resulting in 2015-01-02T00:00:00+02:00 which is the same value just with a different offset.

Any value even with explicit time zone information is then adjusted to the time zone of the data. This is important when the data unit is day, week, month or year since in this case the time axis time zone has no effect.

Display - time axis

Time axis time zone is specified in the chart configuration and controls how the data is adjusted only when viewing data in units less than a day (hour, minute, second, millisecond). It is also used for showing milestones and current time marker on the chart.

The default time zone used to display values is UTC. Please read the Supported time zones section on the limitations of using local as the time zone.

For example, consider that the data contains a timestamp 2015-01-01 12:00:00+05:00. The data time zone is Europe/Riga but the time axis time zone is America/New_York. First the time is parsed and adjusted to Europe/Riga, resulting in 2015-01-01 09:00:00+02:00. After that the value is adjusted to America/New_York, creating 2015-01-01 02:00:00-05:00. This is the value the chart will use when displaying the data - 2AM on January 1st, 2015.

Performance considerations

Converting time from one timezone to another is relatively expensive operation. Although it is done only once when the data is received, it can decrease user experience on slower devices. For example, during the initial tests on an average laptop, adjusting 100000 timestamps took 2 seconds on Chrome and 10 seconds on IE11. If string timestamps were used, the times were 6 and 18 seconds respectively.

For maximum performance, you should use UTC for both data and time axis and use only numeric timestamps.

Another aspect to consider is the size of the moment-timezone library that is included by default as it includes every time zone with all historical rules.

If you are not using local to specify the time zone or the data range is limited to certain years you could remove the data you do not need from the file to reduce the file size. See data builder for details.

The custom file should be included together with moment.js before initializing TimeChart - the chart will then automatically pick up the custom file instead of using the file it is bundled with.