Chart

The chart service group's chart resource provides access to historical chart samples. We provide chart samples for a set number of horizons from 1 minute to 1 month. The amount of samples varies by instrument and asset class with some Forex data dating back as along as 2002.

Data Returned

The chart response may include a Data field containing an array of samples along with convenience information in other fields.

The data returned in a single chart sample depends on the asset type of the instrument. The following applies:

AssetType	Close	CloseAsk/ CloseBid	High	HighAsk/ HighBid	Interest	Low	LowAsk/ LowBid	Open	OpenAsk/ OpenBid	Time	Volume
CfdOnIndex
CfdOnFutures
FxSpot
Stock
CfdOnStock
ManagedFund
StockIndex
ContractFutures

Finding the first available sample

The ChartInfo group includes a FirstSampleTime field. This provides the time of the very first sample. Having this information is often useful if you want to show a chart with a horizontal slider at the bottom, and you want to give that slider the correct approximate length even if you do not want to initially fetch all of the chart samples.

Typical usage - Request/Response

The most common usage of the chart endpoint in a request/response mode is as follows:

• First make a simple get request specifying AssetType, Uic, Horizon and all field groups. This will return:
  • ChartInfo holds various convenience information which applies for all samples on the specified instrument/horizon
  • DisplayAndFormat holds information about how to format the prices in the samples.
  • Data includes the most recent 100 samples up to current time.
  • A DataVersion (see later)
• Then, at regular intervals make requests specifying AssetType, Uic, Horizon and:
  • Mode=From
  • Time= the value of the most recent sample, which you have in your Data array.

The Data array will now include "all" samples which exist from or after the specified time. Often this will just be a single sample.

Sample formation

A new sample is inserted in the array at the time when the sample should start. This sample's data will then be updated until the sample is completed and a new sample is started. You will thus typically see a newly created sample with volume=0 and open, high, low, close set to the same value. Over time, you will see the high and low move away from the open value, while the close will move up and down reflecting the current price of the instrument.

About Chart sample prices and correct usage of chart prices

While the close price of the most recent sample represents the most recent price for the specified instrument, you should not use this for display on a watchlist. The chart feed is intended for display on charts. For the most accurate and up to date instrument prices, you should use the /InfoPrices or /Prices endpoints in the Trade service group.

You should also not expect the most recent sample's close price to be 100% in sync with prices streamed from the Trade service group, as the way the two datasets are sampled and distributed in slightly different ways.

Typical usage - Streaming

Using chart streaming resembles the way described for request/response. When setting up the subscription, specify AssetType, Uic, Horizon and all field groups. This will return a snapshot containing the same information as explained above. From then on, just respond to incoming updates over the streaming connection.

About Chart Corrections

Historical chart data may change from time to time. For example, a 1:2 stock split will suddenly cut all historical prices as well as the current price in half.

In a request/response scenario, you should be watching for the DataVersion field. If this is updated, you should invalidate and re-fetch all samples for this instrument / time horizon. In a streaming scenario you will receive a __reset subscriptions event.

See also the live sample on the chart endpoint (with source).