Getting started
Chart interface
Web components
Chart internals
Data integration
Frameworks and bundlers
Mobile development
Time Span Events
Term structures

Dates, Times, and Time Zones

The ChartIQ library displays "time series" charts. Time series charts display dates on the x-axis. To understand the x-axis, it is critical to understand how the library works with dates.

Developers feed an array of data points into a chart (Data Loading Tutorials). Each data point requires values ('Last','Open','High','Low','Close',etc) and a date (DT or Date). The array of these data points is plotted to create a chart.

Often, the server is in a different time zone than the user. We call the server's time zone the "dataZone" and the user's time zone the "displayZone". By default, the displayZone is set to the time zone of the user's browser and operating system. This means that data sent by the server is converted to the browser's time zone before being displayed on the x-axis.

Both the "dataZone" and "displayZone" can be set programmatically to specific time zones using the setTimeZone API call. More on this in the following sections.

See CIQ.timeZoneMap to review a list of all chatIQ supported timezones and instructions on how to add more!

Dates and times

Why are there two possible fields to represent a date?


Use 'DT' when you have a JavaScript Date() object or a value that can be coerced into a Date() object. For instance, DT can take an epoch (number of milliseconds since 1970 GMT) or a ISO 8601 standard string. JavaScript dates are time zone aware. This is because they are implicitly based on UTC (universal time). Each of the coercable formats (epoch, ISO 8601) contain a time zone offset that allows the browser to convert to local time.

Example, data being sent to the library with an epoch :

dataObj = {
	DT: new Date(134534934343),
	Close: 100.12

Example, data being sent to the library in ISO 8601 format :

dataObj = {
	DT: new Date("1997-07-16T19:20:30+01:00"),
	Close: 100.12


Use 'Date' when your dates are in string format which do not contain any time zone information. A wide variety of string formats are accepted. When using 'Date' you must explicitly tell the chart which time zone the data is from (usually the server or exchange's time zone). The chart will convert the dates based on the time zone provided, which is done using setTimeZone(dataZone). (See Timezones below).

Example, data being sent to the library in string format :

dataObj = {
	Date: "1997/07/16 19:20:30",
	Close: 100.12

For a list of all supported string formats see the Input format Tutorial

Regardless of whether you provide DT or Date, the chart will convert and add the other. So if you provide DT, the chart will calculate the Date. If you provide the Date, then the chart will calculate the DT. If you examine the chart's masterData, dataSet or dataSegment you will see both dates.

Time zones

Everybody in the world lives in a time zone that is determined from an offset of Greenwich Mean Time (GMT). GMT is sometimes called "Universal Time" or "UTC". Your time zone is based on an offset from UTC. For many timezones, the offset will change throughout the year depending on whether daylight savings time (DST) is in effect.

The time displayed on your computer is determined by the time zone you've selected in your operating system. Your browser's clock is based on this time, and so the charting library is also based on this time. The default behavior of the charting library is to convert data from its source time zone to the time zone of the user's local computer.

Time zone conversion

When you provide a chart with data, the first thing it needs to do is calculate the difference in time zones from your server data (dataZone) and the browser itself. There are two possibilities:

  1. If you pass a DT (Javascript Date Object) then the chart automatically knows the time zone of your market data. The chart will automatically convert from your market data's time zone and print x-axis times in the browser's local time zone, unless otherwise instructed.

Example, instruct chart engine to display x axis in Hong Kong time even if data is provided as Javascript/ISO date:

stxx.setTimeZone(null, "Asia/Hong_Kong");
// load Javascript/ISO data
  • In this case always set the dataZone to null when calling setTimeZone
  • Never set the dataZone to a time zone when using time zone aware dates.
  1. If you pass a Date (string format), you must explicitly set the data time zone by calling setTimeZone(dataZone) where the dataZone is the known time zone of your server (e.g. America/New_York), or the chart engine will assume it is already in the browser's time zone.
  • if your data comes in Hong Kong time zone, but should be displayed in the user's local time zone:
// load data
  • if your data comes in Hong Kong time zone, but should be displayed in New York time zone:
stxx.setTimeZone("Asia/Hong_Kong", "America/New_York");
// load data
  • If you want the chart to always display in the server's time zone (no conversion) then do not set either dataZone or displayZone.

Convenience Functions

Time zone menu for users

The default template, sample-template-advanced.html, includes a cq-timezone-dialog web component that allows users to select their time zone (to override the browser's default). The component simply calls CIQ.ChartEngine#setTimeZone with the time zone selected by the user.

Example, user selected time zone :

var userSelected = "America/New_York"; // for instance, from a menu
stxx.setTimeZone(null, userSelected); // passing null as the first parameter won't affect a previously set dataZone

See CIQ.timeZoneMap to review a list of all chatIQ supported timezones and instructions on how to add more!

Market hours

The x-axis of a stock chart does not generally follow calendar time because few securities trade 24 hours per day, and almost no securities trade 7 days per week. For a stock chart to properly display portions of the x-axis, it must be aware of the hours that a security trades. It must know the exchange or market hours. Accurately iterating through "market hours" is important for such tasks as plotting out the future x-axis, accurately maintaining drawings across periodicities or detecting data gaps.

It is also important to note that only data within the defined market hours will be displayed on the chart even if more data is loaded.

Knowing the market hours for NYSE, the chart can accurately project the x-axis into the future. Note how the x-axis starts a new market day at 16:00 : X-Axis Projected Into The Future

The days, hours and holiday schedule for a market can be defined with a "Market Definition" object. Here is an example of a market definition object:

var myMarket = {
	name: "My Market",
	market_tz: "America/Chicago", // Note you must specify the time zone for the market!
	rules: [
		{ dayofweek: 0, open: "15:00", close: "24:00" }, // Sunday
		{ dayofweek: 1, open: "00:00", close: "24:00" },
		{ dayofweek: 2, open: "00:00", close: "24:00" },
		{ dayofweek: 3, open: "00:00", close: "24:00" },
		{ dayofweek: 4, open: "00:00", close: "24:00" },
		{ dayofweek: 5, open: "00:00", close: "18:00" },
		{ date: "*-12-25", open: "00:00", close: "00:00" } // closed on Christmas

ChartIQ maintains market definitions for major world markets. These can be found in the exchangeHours.js file (NYSE, GLOBEX and METALS are defined in the core library).

If you are dealing with a single exchange, then simply provide the market definition to your chart:


See CIQ.ChartEngine#setMarket for details.

Market factories

Supporting multiple exchanges with different markets requires implementing a "Market Factory". A Market Factory is simply a callback function that takes a stock symbol and returns a market definition. This concept is referred to as "symbology". One firm may use the symbol "IBM.NY" to represent IBM on the New York Stock Exchange. Another firm may use "IBM NYSE" or even just "IBM". A Market Factory must be written to parse your symbology, determine the market, and return the appropriate market definition class.

Here is an example market factory:

// Market Class Example 1
var NYSE = {
	name: "NYSE",
	market_tz: "America/New_York",
	rules: [] // define all necessary rules

// Market Class Example 2
var XLON = {
	name: "XLON",
	market_tz: "Europe/London",
	rules: [] // define all necessary rules

// symbolObject contains all info needed about a financial instrument (symbol)
var myFactory = function(symbolObject) {
	var symbol = symbolObject.symbol;

	if (symbol.indexOf(".NY") != -1) return NYSE;
	if (symbol.indexOf(".LS") != -1) return XLON;
	return NYSE; // default if no match

stxx.loadChart("IBM"); // library will call myFactory and assign a market to the chart

Whenever the user changes the symbol, the chart will make a call to the market factory and load the returned market definition file. It will do this before displaying the chart, so that the x-axis always accurately reflects the trading hours for the security.

The ChartIQ library contains a pre-defined factory, CIQ.Market.Symbology.factory that supports a common symbology used by Xignite and Yahoo Finance.

Convenience time zone conversion methods:


timezone.js contains a modified version of the third-party library timezone-js. All of the ChartIQ library functions that deal with time zones use timezoneJS.Date for date conversions.

A comprehensive list of available time zones are available in CIQ.timeZoneMap.

Actual time zones have changed over the years. Historical charts created by ChartIQ are accurate thanks to the historical information compiled by the Internet Assigned Numbers Authority (IANA). ChartIQ periodically updates the time zone database that is bundled into the library.

CIQ date formatting functions

// built-in library functions for date formatting
CIQ.strToDateTime("01/01/17 12:00:00"); // convert to Javascript date/time
CIQ.strToDate(datetimeString); // convert to Javascript date (no time)
CIQ.dateToStr(date, format); // convert date to a custom format
CIQ.mmddyyyy(date); // convert date to MM/DD/YYYY format
CIQ.mmddhhmm(date); // convert date to MM-DD hh:mm
CIQ.yyyymmdd(date); // convert date to YYYY-MM-DD format
CIQ.yyyymmddhhmm(date); // convert date to YYYYMMDDhhmm format
CIQ.yyyymmddhhmmssmmm(date); // convert date to YYYYMMDDhhmmssmmm format
CIQ.friendlyDate(date); // convert date to YYYY/MM/DD hh:mm format
CIQ.standardUTCDate(date); // convert date to YYYY-MM-DDThh:mm:ssZ format

Next steps