The ChartIQ OHLC Format for Time-Series Data

This tutorial explains the input format for time-series chart data. Whenever data is sent into a chart, it must conform to the format defined below.

Please read Data Integration: Considerations and Overview if you haven't already.

Note: Date values for all input data must be consistent with the chart's periodicity! See Periodicity and Your Master Data for a complete explanation.

The ChartIQ Data Format

Data can be entered into a chart using different methods (i.e. pushed, pulled, or streamed), but the data format is always the same: a JavaScript array of OHLC time-series objects. OHLC simply stands for Open-High-Low-Close...named after the most commonly reported price movements for a financial instruments.

The full breakdown of ChartIQ's OHLC object format (i.e. a single array element in the data) is shown below:

Field Required Description
DT Maybe A JavaScript Date() object or a value that can be coerced into a Date() object (epoch or a ISO 8601 standard string) representing the start time of the bar or tick.
Date Maybe A date string in format described below, representing the start time of the bar or tick
Close Maybe Closing price for the bar. Excluding or setting this field to null will cause the chart to display a gap for this bar.
Open Maybe Opening price for the bar. Required for candle charts only.
High Maybe High price for the bar. Required for candle charts only.
Low Maybe Low price for the bar. Required for candle charts only.
Volume No Trading volume for the bar
Adj_Close No Closing price adjusted price after splits or dividends. This is only necessary if you wish to give users the ability to display both adjusted and unadjusted values.

Important:

  • Only date (either DT or Date) is required. All other fields are optional.
  • Field names are Capitalized.
  • Open, High, Low, Close & Volume must be numbers, not strings. (Use parseFloat to convert if your data server provides strings.)
  • JavaScript epochs are the number of milliseconds since 1970 GMT. If your server sends "unix epochs" (number of seconds since 1970) then be sure to multiply by 1,000.
  • The time portion of the 'DT' field is ignored and no time zone conversions are done for "daily", "weekly" or "monthly" charts. If using 'Date', you must clear out the time portion manually before loading.
  • The date for an OHLC bar is the starting point for the interval. For instance, a 5 minute bar represents activity from 05:00:00.000 to 05:04:59:999.
Supported date string formats
  • 'yyyymmddhhmmssmmm'
  • 'yyyymmddhhmm'
  • 'yyyymmdd'
  • 'yyyy-mm-ddThh:mm:ss.SSS'
  • 'yyyy-mm-dd hh:mm:ss AM/PM'
  • 'yyyy-mm-dd hh:mm:ss'
  • 'yyyy-mm-dd'
  • 'mm-dd-yyyyThh:mm:ss.SSS'
  • 'mm-dd-yyyy hh:mm:ss'
  • 'mm-dd-yyyy'

Notes:

  • Both slashes (/) and hyphens (-) are supported
  • The date format must follow "US style" rather than "European style". The month comes before the day.

For more details on the difference between Date and DT see the Dates and Timezones tutorial.

Examples

The following example shows a data array with just two OHLC objects. Note the objects in the array must be ordered from oldest to newest -- this means that your data[0] object will be the oldest and your data[length-1] object will be the most current.

[
    {
        "Date":"1993-01-29",
        "Open":43.97,
        "High":43.97,
        "Low":43.75,
        "Close":43.94,
        "Volume":1003200
    },
    {
        "Date":"1993-02-01",
        "Open":43.97,
        "High":44.25,
        "Low":43.97,
        "Close":44.25,
        "Volume":480500
    }
]

Here's a snippet from a more realistic dataset of daily data for a symbol (i.e. a specific security):

[
{"Date":"1993-01-29","Open":43.97,"High":43.97,"Low":43.75,"Close":43.94,"Volume":1003200},
{"Date":"1993-02-01","Open":43.97,"High":44.25,"Low":43.97,"Close":44.25,"Volume":480500},
{"Date":"1993-02-02","Open":44.22,"High":44.38,"Low":44.13,"Close":44.34,"Volume":201300},
{"Date":"1993-02-03","Open":44.41,"High":44.84,"Low":44.38,"Close":44.81,"Volume":529400},
{"Date":"1993-02-04","Open":44.97,"High":45.09,"Low":44.47,"Close":45,"Volume":531500},
{"Date":"1993-02-05","Open":44.97,"High":45.06,"Low":44.72,"Close":44.97,"Volume":492100},
{"Date":"1993-02-08","Open":44.97,"High":45.13,"Low":44.91,"Close":44.97,"Volume":596100},
{"Date":"1993-02-09","Open":44.81,"High":44.81,"Low":44.56,"Close":44.66,"Volume":122100},
{"Date":"1993-02-10","Open":44.66,"High":44.75,"Low":44.53,"Close":44.72,"Volume":379600},
. . . ]

Here's a snippet with 5-minute data for a symbol:

[
{"Date":"2015-04-16 16:00","Open":152.13,"High":152.19,"Low":152.08,"Close":152.11,"Volume":4505569},
{"Date":"2015-04-17 09:30","Open":151.76,"High":151.83,"Low":151.65,"Close":151.79,"Volume":2799990},
{"Date":"2015-04-17 09:35","Open":151.79,"High":151.8,"Low":151.6,"Close":151.75,"Volume":1817706},
{"Date":"2015-04-17 09:40","Open":151.74,"High":151.96,"Low":151.74,"Close":151.84,"Volume":2127911},
{"Date":"2015-04-17 09:45","Open":151.84,"High":152.03,"Low":151.79,"Close":151.95,"Volume":1640306},
{"Date":"2015-04-17 09:50","Open":151.95,"High":152.09,"Low":151.84,"Close":152.07,"Volume":1420396},
{"Date":"2015-04-17 09:55","Open":152.07,"High":152.08,"Low":151.87,"Close":151.91,"Volume":1312368},
{"Date":"2015-04-17 10:00","Open":151.92,"High":152.02,"Low":151.88,"Close":151.95,"Volume":1351448},
{"Date":"2015-04-17 10:05","Open":151.95,"High":152.02,"Low":151.87,"Close":151.98,"Volume":1171601},
. . . ]

An example of "tick data". Tick data will have irregular intervals and only a closing price:

[
{"Date":"2015-04-16 09:00:01","Close":72.11,"Volume":505569},
{"Date":"2015-04-17 09:00:07","Close":71.79,"Volume":799990},
{"Date":"2015-04-17 09:00:08","Close":71.75,"Volume":817706},
{"Date":"2015-04-17 09:00:10","Close":71.84,"Volume":127911},
{"Date":"2015-04-17 09:00:21","Close":71.95,"Volume":640306},
{"Date":"2015-04-17 09:00:25","Close":72.07,"Volume":420396},
{"Date":"2015-04-17 09:00:30","Close":71.91,"Volume":312368},
{"Date":"2015-04-17 09:00:55","Close":71.95,"Volume":351448},
{"Date":"2015-04-17 09:00:56","Close":71.98,"Volume":171601},
. . . ]

Timezone Considerations

Ideally, your data server will support epochs (milliseconds since 1970) or ISO8601 format. ISO8601 is supported by the JavaScript Date object and looks like these:

2015-01-01T09:10:00Z - UTC time

2015-01-01T09:10:00.000Z - With milliseconds

2015-01-01T09:10:00.000-0500 - With timezone offset

Epochs and ISO8601 formats provide "timezone context". With such date formats, the chart can convert the times into a time that is convenient for the end user. By default, the chart will convert the times to display in the local timezone of the user (the browser's timezone). This is seen on the x-axis of an intraday chart.

Example: 2015-01-01T14:10:00Z will display as "09:10" to a user located in New York. It will display as "08:10" to a user located in Chicago. It will display as "14:10" to a user located in London.

If your server provides string format dates you should pass them as strings to the Date field on the OHLC object. These dates will be displayed to the user without conversion.

Example: 2015-01-01 14:10:00 will display as "14:10" to all users, regardless of their location.

If you know the timezone of your data server then you can provide this with CIQ.ChartEngine#setTimeZone, so that the chart knows the "timezone context." This will allow the chart engine to convert the times to the user's local time:

Example: 2015-01-01 14:10:00 will be converted to "09:10" (New York), "08:10" (Central), "14:10" (London) if you call stxx.setTimeZone("Europe/London") before passing data.

See Dates and Timezones for more details.

Extra OHLC Data

As long as the OHLC objects are properly formatted, you can include extra elements in each OHLC object. This extra data has no effect on how the chart is displayed.

Example:

[
{"Date": "2015-05-27T15:00:00+00:00", "Close": 42.49, "Extra1": 37.31, "YourStudy": 84.57},
{"Date": "2015-05-27T15:30:00+00:00", "Close": 42.45, "Extra1": 84.39, "YourStudy": 16.82}
. . .

A Special Case: Streaming last-Sale data

For OHLC input data there's one exception to the rule: CIQ.ChartEngine#appendMasterData can also support input of "last-sale" data. Last-sale data can be automatically distinguished by the "Last" price. When sending last-sale data, the chart will automatically construct OHLC bars. Note that when sending last-sale data, the "Volume" is interpreted as the volume for the trade (incremental volume). The actual displayed volume for a chart bar will be the sum of these trade volumes for that time period.

Example: Streaming last sale to the chart

[{"Date":"2015-04-16 09:00:01","Last":72.13,"Volume":505569}]

When passing last-sale data, the "Bid" and "Ask" price can also be passed for use in ChartIQ's optional Trade From Chart (TFC) plugin.

Example: Sending bid and ask for use by TFC plugin

[{"Date":"2015-04-16 09:00:01","Bid":72.05,"Ask":72:15,"Last":72.13,"Volume":505569}]
. . .

Next Steps: