TimeZones and Time Conversion

The charting object has the ability to translate timezones. It accomplishes this through the use of the third party library stxTimeZoneData.js and the setTimeZone(dataZone, displayZone) convenience function.

Note: if you need timezone translation, be sure to include the stxTimeZoneData.js file which contains the full database of timezone information.

The library keeps track of 2 different timezones:

  • The timezone of the data you are sending from your quote feed : dataZone
  • The timezone to display on the chart : `displayZone'

These 2 timezones can be different and do not have to match, but they do have to be individually set so the library knows how to properly translate between the 2.

The default behavior of the charting library is to display data in the the -local timezone of the browser-.

How Is Local Timezone Of Browser Determined?

The "browser time" is determined because your browser automatically knows where it is by the nature of the operating system (it knows its offset from GMT).

So the first thing the chart needs to do is determine the difference in timezones from your server data and the browser itself. There are three possibilities:

1- If you pass data in UTC form then it will automatically know the timezone of your market data because it is a component of the UTC format. A UTC time is in format:

1997-07-16T19:20:30+01:00

This is per the W3 standard: http://www.w3.org/TR/NOTE-datetime and the browser will automatically do the timezone conversion when it creates a JavaScript Date object. You would set this as a string in your data:

dataObj={
    Date: "1997-07-16T19:20:30+01:00",
    Close: 100.12,
    Open: 100.11
    etc
}

Alternatively if you already have a JavaScript Date object from your infrastructure then set the DT field:

var dt=new Date(134534934343); // For instance, epoch comes from your server

dataObj={
    DT: dt,
    Close: 100.12,
    Open: 100.11
    etc
}

An important note on UTC dates:

You must be careful to send in a UTC string or JavaScript date that properly represents the exchange timezone.

Midnight UTC could very well be the next day or the previous day in other timezones. You must always ask yourself, what time is it in the data source location?

For example, if you send a date of 2015-08-05T00:00:00.000Z to represent a daily tick for a NYSE instrument, you would be making a mistake since that is really 2015-08-04 18:00:00.000 NY time (UTC is 6 hours ahead). The correct UTC time to send for a US market day, for example, would be 2015-08-05T06:00:00.000Z.

Now, if your date did not have the timezone built into the date (2015-08-05 00:00:00.000, for example) , then you would use the setTimeZone method to let the chart know if any conversions are needed.

The library generates 2 dates; the data date (DT) and the display date (displayDate). And they can be different depending on your settings. You will see them both in browser time when you inspect the raw data using a debugging console.

2- If your server is not sending timezone information (199-07-16T19:20:30) but you know the timezone of the server then you can explicitly set that timezone by calling stxx.setTimeZone(dataTimeZone) where the dataTimeZone is the known timezone of your server (for instance Americas/New_York). Do this of course before loading any of your data! The chart will use the stxTimeZoneData.js library to translate those dates to the local time of the browser through lookups to Daylight Savings Time information in stxTimeZoneData.js. It's worth noting that DayLightSavingsTime has changed over the years and so a historical chart will be accurate thanks to the historical information contains in stxTimeZoneData.js. If using this method, the chart will store the explicit timezone in STXChart.dataZone.

3- If the timezone is not specified and the date is not in UTC format then there is no way to translate the time. The chart object will assume the data is already in local time and simply print the date on the chart as it comes from the server. So, if you don't want any timezone translation then simply do not send the timezone!

User Selection Of Timezone

With our standard templates, users can select a timezone from a drop down list (found in the "cog" menu). When a user selects a timezone then a -second- translation occurs from the browser's timezone to the selected one. Say for instance a user travels from New York to Hong Kong on a business trip. He trades stocks on the New York Stock Exchange and is familiar with the opening and closing times when he lives in New York. However he has reset his computer to Hong Kong time because he has meetings in Hong Kong and needs his calendar to be accurate. This user can set his charts to New York time, overriding the browser.

When a user sets a timezone, the method stxx.setTimeZone(null, userSelectedTimeZone) is called, and the requested user time zone stored in STXChart.displayZone. As a developer you can of course call this method programatically.

User Timezone translation is only applicable to intraday charts. For other periodicity (daily, weekly, monthly), the data timezone will be used, so be careful to use a time that properly represents the beginning of the trading day from the location where the data belongs to ( see An important note on UTC dates). Midnight (00:00:00) UTC is not midnight NYSE time.

stxTimeZoneData.js

This file contains a precompiled database of timezones in JavaScript object format. To set either the timezone of the data (dataZone) or the timezone of the user (displayZone) you should pick an appropriate timezone from this database (a field from the object).

Example: sets data timezone to New York and customer timezone to Hong Kong

stxx.setTimeZone("America/New_York","Asia/Hong_Kong");

A comprehensive list of available time zones are available in STX.TimeZoneWidget.timeZoneMap, under stx.js

The following code sample shows how you can normalize a date from the browser timezone to the timezone required for your master data. And then if needed, translate that to the timezone the user has selected to view.

    var dt= new Date();
    var milli=dt.getSeconds()*1000+dt.getMilliseconds();

    // 'this' is your chart object.

    // first, if the library knows the time zone of the data, adjust it from the browser's time zone to the timezone you know the quote feed is using.
    if(this.dataZone){
        var newDT=new timezoneJS.Date(dt.getFullYear(), dt.getMonth(), dt.getDate(), dt.getHours(), dt.getMinutes(), this.dataZone);
        dt=new Date(newDT.getTime()+milli);
    }

    // then, if this date will be shown to the user in a different timezone, convert it from the data time zone to the user selected time zone
    if(this.displayZone){
        var newDT=new timezoneJS.Date(dt.getTime(), this.displayZone);
        dt=new Date(newDT.getFullYear(), newDT.getMonth(), newDT.getDate(), newDT.getHours(), newDT.getMinutes());
        dt=new Date(dt.getTime()+milli);
    }

    // this is your final date in the time zone the user wants for the chart
    var dateForUser=dt;

Disabling Automatic UTC Conversion

By default, if the data you pass to the chart is UTC (containing timezone offset) then the chart will automatically convert the time to the user's local browser. There are some cases where you may not want this to happen. For instance, you may intentionally want user's to always see the actual exchange timezones.

To override the default conversions set stxx.chart.xAxis.adjustTimeZone=false

FAQ

  • Exactly what happens (in the code) when you don't use setTimezone()?

The date will be stored assuming it is already in browser timezone, unless you send a UTC formatted Date or a DT; which already implicitly contain the timezone.

  • What role the browser/computer timezone plays?

The library will store all of the dates you send from your feed in Browser timezone (DT field) and then from there offset it to the display timezone if one indicated.

  • Does the chart engine use any heuristics to try to detect timezone based on the format of 'Date'?

Only if sending a UTC formatted 'Date', otherwise it will assume 'Date' is in browser timezone unless you tell it otherwise.

  • What happens if you set DT explicitly? (ie, do DT and Date have different roles, or are they interchangeable?)

DT never needs to have a timezone assigned. It is implicit in the format. Date needs to have a timezone assigned unless the string is already in browser time (for example, your dates come in NY time and only people in NY will use the charts) or you send a UTC formatted string. If both present, 'DT' will take precedence.

Still confused about time zones? Read this story....

Ok, think about this. Assume to day is 7/7/17 in NY.

Let's say you are displaying daily ticks on your chart and your friend in London is reading you the data real time over the phone. London is 6 hours ahead of NY.

The date for today's IBM tick trading on the NYSE must be between 7-7-15 00:00:00 ET and 7-7-15 23:59:59 ET, or it is not for today. I live in NY so his happens to be is my local time. If I was giving you the information, I would just look at my watch and give you that time. No conversions needed. I am exactly where the data is being produced.

But for your fiend living in London (UTC time) my midnight is 6 am on his next day. Right?

Lets assume for a second that IBM trades all day ( 00:00 to 23:59 NY Time) . So if he wants to give you the tick prices the second the market opens, he had to wake up at 6 AM on 7-8-15 his day to catch the NYSE opening. If he wakes up at midnight on 7-8-15 his time, over here it is 6 PM on 7-7-15. So he missed the opening. If he wakes up at midnight his time on 7-7-15, here it would be 6 PM on 7-6-15, so he is 6 hours too early.

Similarly, if you tell me that the tick belongs to 2015-07-07T00:00:00.000Z, you are really saying that it belongs to 7-6-15 6 PM in NY because NY is 6 hours behind London. So I am going take that tick and throw it in the 7-6-15 bucket.

Again, the times can be in any timezones you want as long as they convert to a date/time that matches the actual time of the exchange. The trading day for the NYSE does not start at midnight in London. It starts at midnight in NY. (again for argument sake we are assuming the market opens at midnight)

You can't send me a daily tick for something that trades in the US with a date from the UK (UTC) ... right? it will be off by 6 hours.... But you can send me a UTC date, if it really represent the NY time the tick date belongs to. In this case your UTC date must be 6 hours behind to make sense.