Time Zones – KeyLines Docs

Time Zones

Features

Introduction

Every geographical region has its own standard time zone. Each zone has a UTC offset, which is the difference in hours and minutes from Universal Coordinated Time (UTC).

Many regions observe Daylight Saving Time (DST), where the offset changes during the seasons. Offset rules may also change for upredictable political reasons.

Date objects in JavaScript

You can create a Date object using the JavaScript Date constructor:

// Creates a Date object for the 26th December 2010, 9 AM
const date = new Date(2010, 11, 26, 9, 0, 0);

The JavaScript Date constructor treats most input formats as local time.

There are two exceptions that use UTC:

Date-time strings with a declared time zone in Date Time String Format (ISO 8601 standard)
Millisecond numbers

See also the MDN Docs on Date() constructor for more details.

JavaScript has a functionality to map between UTC and the user's local time zone, defined by the operating system. The browser knows the operating system's current time zone and uses this to offer conversions to UTC:

const hours = date.getUTCHours();

Note that most browsers don't allow for changes to time zone rules, so the UTC conversion may not be correct.

Time zones in KeyLines

The KeyLines API accepts dates as either Date objects or as millisecond numbers, but it always returns dates as Date objects.

There is no built-in way to manage time zones and displays dates exactly as they're passed in. You need to decide which time zone to use. The most common choices are either UTC or the user's time zone.

If you don't choose either of these options, you must convert the date to the right time zone before passing it to KeyLines.

Option 1: UTC dates on server and browser

If your users work with servers recording dates in UTC, they might want to see their data in UTC too. Construct your JavaScript dates using the times you get from the server directly.

For example, your server logs have an entry (in ISO 8601 standard) for May 22, 2016:

// YYYY-MM-DDTHH:mm:ss.sssZ, T = time, Z = UTC time with zero offset
const dateOnServer = '2016-05-22T07:58:33.592Z';

You would create a JavaScript Date object:

// Note months are zero based in JavaScript
const dateToUse = new Date(2016, 4, 22, 7, 58, 33, 592);

To pass this date to the time bar, use an item's dt property. The time bar displays the date 'as seen' - i.e., in UTC.

Option 2: UTC date on server, local time for the user

Your users may prefer to see the local time for a time zone instead of UTC dates from their server. It's best practice to let your users choose their time zone.

For example, your server logs have an entry (in ISO 8601 standard) for May 22, 2016:

const dateOnServer = '2016-05-22T07:58:33.592Z';

Use a library, such as Moment.js, to convert this to local time on the server before the data is sent. In our case, the data is now converted to Eastern Daylight Time (EDT):

const convertedDate = 'May 22, 2016 03:58:33.592';

This is four hours earlier because EDT is 4 hours behind UTC. If the date was outside Daylight Saving Time, your conversion would be five hours behind.

As the data arrives in local time, you can use the standard JavaScript constructor:

item.dt = new Date(data.time);

Your users will now see EDT in the time bar.

Time bar and filtering time

For convenience and better performance, the time bar API accepts millisecond numbers for dates.

KeyLines interprets the value from the number of epoch milliseconds since January 1, 1970, 00:00:00 UTC. The time bar uses UTC to display the values, which means that the same values are shown for all users regardless of their time zone.

// 3pm at May 11, 2015 in UTC - for everyone in the world
const ms = 1431356400000;

To avoid unwanted time zone conversions, we recommend using milliseconds when calling timebar.getIds() and timebar.range().

Note: Date ranges returned by any part of the time bar API (click, hover and pointer-down events or timebar.range() used as a getter) are in local time. To recover the equivalent milliseconds, use:

const ms = Date.UTC(
  dt.getFullYear(),
  dt.getMonth(),
  dt.getDate(),
  dt.getHours(),
  dt.getMinutes(),
  dt.getSeconds(),
  dt.getMilliseconds(),
);