JS Api - kroim/charting-library-wiki GitHub Wiki

What is JS API

JS API is a set of JS methods that needs to be implemented in order to connect your data to the chart.

How to start

You should create a JS object that fetches data from your server when the Charting Library calls its methods.

When you create an object that implements the described interface simply pass it to Library widget constructor through the datafeed argument.

The Charting Library caches historical data on its own. You don't need to implement a client-side cache by yourself.

:chart: Trading Terminal specific:

getQuotes
subscribeQuotes
unsubscribeQuotes
subscribeDepth
unsubscribeDepth

onReady(callback)

callback: function(configurationData)
1. configurationData: object (see below)

This call is intended to provide the object filled with the configuration data. Charting Library assumes that you will call the callback function and pass your datafeed configurationData as an argument. Configuration data is an object; for now, the following properties are supported:

exchanges

An array of exchange descriptors. Exchange descriptor is an object {value, name, desc}. value will be passed as exchange argument to searchSymbols.

exchanges = [] leads to the absence of the exchanges filter in Symbol Search list. Use value = "" if you wish to include all exchanges.

symbols_types

An array of filter descriptors. Filter descriptor is an object {name, value}. value will be passed as symbolType argument to searchSymbols.

symbols_types = [] leads to the absence of filter types in Symbol Search list. Use value = "" if you wish to include all filter types.

supported_resolutions

An array of supported resolutions. Resolution must be a string. Format is described in another article.

supported_resolutions = undefined or supported_resolutions = [] leads to resolution widget including the default content.

Example: ["1", "15", "240", "D", "6M"] will give you "1 minute, 15 minutes, 4 hours, 1 day, 6 months" in resolution widget.

currency_codes

An array of supported currencies for currency conversion.

Example: ["USD", "EUR", "GBP"].

supports_marks

Boolean showing whether your datafeed supports marks on bars or not.

supports_timescale_marks

Boolean showing whether your datafeed supports timescale marks or not.

supports_time

Set this one to true if your datafeed provides server time (unix time). It is used to adjust Countdown on the Price scale.

futures_regex

Set it if you want to group futures in the symbol search. This REGEX should divide an instrument name into 2 parts: a root and an expiration.

Sample regex: : /^(.+)([12]!|[FGHJKMNQUVXZ]\d{1,2})$/. It will be applied to the instruments with futures as a type.

searchSymbols(userInput, exchange, symbolType, onResultReadyCallback)

userInput: string. It is text entered by user in the symbol search field.
exchange: string. The requested exchange (chosen by user). Empty value means no filter was specified.
symbolType: string. The requested symbol type: index, stock, forex, etc (chosen by user). Empty value means no filter was specified.
onResultReadyCallback: function(result)
1. result: array (see below)

This call is intended to provide the list of symbols that match the user's search query. result is expected to look like the following:

[
    {
        "symbol": "<short symbol name>",
        "full_name": "<full symbol name>", // e.g. BTCE:BTCUSD
        "description": "<symbol description>",
        "exchange": "<symbol exchange name>",
        "ticker": "<symbol ticker name, optional>",
        "type": "stock" // or "futures" or "bitcoin" or "forex" or "index"
    },
    {
        //    .....
    }
]

If no symbols are found, then callback should be called with an empty array. See more details about ticker value here

resolveSymbol(symbolName, onSymbolResolvedCallback, onResolveErrorCallback, extension)

symbolName: string. Symbol name or ticker if provided.
onSymbolResolvedCallback: function(SymbolInfo)
onResolveErrorCallback: function(reason)
extension: optional object with additional parameters. It has the following fields:
1. currencyCode: string. It may be provided to indicate the currency for conversion if currency_codes configuration field is set and currency_code is provided in the original symbol information. Read more about currency conversion.

Charting Library will call this function when it needs to get SymbolInfo by symbol name.

getBars(symbolInfo, resolution, from, to, onHistoryCallback, onErrorCallback, firstDataRequest)

symbolInfo: SymbolInfo object
resolution: string
from: unix timestamp, leftmost required bar time
to: unix timestamp, rightmost required bar time
onHistoryCallback: callback function for historical data. It should be called just once. This function has 2 arguments:
1. Array of bars. See below.
2. Meta information: See below.
onErrorCallback: callback function for errors. The only argument of this function is a text error message. This message is not displayed and is reserved for the future.
firstDataRequest: boolean to identify the first call of this method. When it is set to true you can ignore to (which depends on browser's Date.now()) and return bars up to the latest bar.

This function is called when the chart needs a history fragment defined by dates range.

Bar is an object with the following fields:

time: number. Amount of milliseconds since Unix epoch start in UTC timezone. time for daily bars is expected to be a trading day (not session start day) at 00:00 UTC. Charting Library adjusts time according to Session from SymbolInfo. time for monthly bars is the first trading day of the month without the time part.
open: number. Bar's open value
high: number. Bar's high value
low: number. Bar's low value
close: number. Bar's close value
volume: number. Bar's volume value

Meta information is an object with the following fields:

noData: boolean. This flag should be set if there is no data in the requested period.
nextTime: unix timestamp (UTC). Time of the next bar in the history. It should be set if the requested period represents a gap in the data. Hence there is available data prior to the requested period.

subscribeBars(symbolInfo, resolution, onRealtimeCallback, subscriberUID, onResetCacheNeededCallback)

symbolInfo: SymbolInfo object
resolution: string
onRealtimeCallback: function(bar)
1. bar: object {time, close, open, high, low, volume}
subscriberUID: object
onResetCacheNeededCallback (since version 1.7): function() to be executed when bar data has changed

Charting Library calls this function when it wants to receive real-time updates for a symbol. The Library assumes that you will call onRealtimeCallback every time you want to update the most recent bar or to add a new one.

Remark: When you call onRealtimeCallback with bar having time equal to the most recent bar's time then the entire last bar is replaced with the bar object you've passed into the call.

Example:

The most recent bar is {1419411578413, 10, 12, 9, 11}
You call onRealtimeCallback({1419411578413, 10, 14, 9, 14})
Library finds out that the bar with the time 1419411578413 already exists and is the most recent one
Library replaces the entire bar making the most recent bar {1419411578413, 10, 14, 9, 14}

Remark 2: Is it possible either to update the most recent bar or to add a new one with onRealtimeCallback. You'll get an error if you call this function when trying to update a historical bar.

Remark 3: There is no way to change historical bars once they've been received by the chart currently.

unsubscribeBars(subscriberUID)

subscriberUID: object

Charting Library calls this function when it doesn't want to receive updates for this subscriber any more. subscriberUID will be the same object that Library passed to subscribeBars before.

calculateHistoryDepth(resolution, resolutionBack, intervalBack)

Optional.

resolution: requested symbol resolution
resolutionBack: time period types. Supported values are: D | M
intervalBack: amount of resolutionBack periods that the Charting Library is going to request

Charting Library calls this function when it is going to request some historical data to give you an ability to override the amount of bars requested.

It passes some arguments so that you are aware of the amount of bars it's going to get. Here are some examples:

calculateHistoryDepth("D", "M", 12) called: the Library is going to request 12 months of daily bars
calculateHistoryDepth("60", "D", 15) called: the Library is going to request 15 days of hourly bars

This function should return undefined if you do not wish to override anything. If you do, it should return an object {resolutionBack, intervalBack}.

Example:

Let's assume that the implementation is as follows

Datafeed.prototype.calculateHistoryDepth = function(resolution, resolutionBack, intervalBack) {
    if (resolution === "1D") {
        return {
            resolutionBack: 'M',
            intervalBack: 6
        };
    }
}

When the Charting Library requests the data for 1D resolution, the history will be 6 months deep. In all other cases the history depth will have the default value.

getMarks(symbolInfo, from, to, onDataCallback, resolution)

Optional.

symbolInfo: SymbolInfo object
from: unix timestamp (UTC). Leftmost visible bar's time.
to: unix timestamp (UTC). Rightmost visible bar's time.
onDataCallback: function(array of marks)
resolution: string

The Library calls this function to get marks for visible bars range.

The Library assumes that you will call onDataCallback only once per getMarks call.

mark is an object that has the following properties:

id: unique mark ID. It will be passed to a respective callback when user clicks on a mark
time: unix time, UTC
color: red | green | blue | yellow | { border: '#ff0000', background: '#00ff00' }
text: mark popup text. HTML supported
label: a letter to be printed on a mark. Single character
labelFontColor: color of a letter on a mark
minSize: minimum mark size (diameter, pixels) (default value is 5)

A few marks per bar are allowed (for now, the maximum is 10). Marks outside of the bars are not allowed.

Remark: This function will be called only if you confirmed that your back-end is supporting marks.

getTimescaleMarks(symbolInfo, from, to, onDataCallback, resolution)

Optional.

symbolInfo: SymbolInfo object
from: unix timestamp (UTC). Leftmost visible bar's time.
to: unix timestamp (UTC). Rightmost visible bar's time.
onDataCallback: function(array of marks)
resolution: string

The Library calls this function to get timescale marks for visible bars range.

The Library assumes that you will call onDataCallback only once per getTimescaleMarks call.

mark is an object that has the following properties:

id: unique mark ID. Will be passed to a respective callback when user clicks on a mark
time: unix time, UTC
color: red | green | blue | yellow | ... | #000000
label: a letter to be printed on a mark. Single character
tooltip: array of text strings. Each element of the array is a new text line of a tooltip.

Only one mark per bar is allowed. Marks outside of the bars are not allowed.

Remark: This function will be called only if you confirmed that your back-end is supporting marks.

getServerTime(callback)

callback: function(unixTime)

This function is called if the configuration flag supports_time is set to true when the Charting Library needs to know the server time.

The Charting Library assumes that the callback is called once.

The time is provided without milliseconds.

It is used to display Countdown on the price scale.

Example: 1445324591.

Trading Terminal specific

getQuotes(symbols, onDataCallback, onErrorCallback)

:chart: Trading Terminal specific.

symbols: array of symbols names
onDataCallback: function(array of data)
1. data: symbol quote data
onErrorCallback: function(reason)

This function is called when the Charting Library needs quote data. The charting library assumes that onDataCallback is called once when all the requested data is received.

subscribeQuotes(symbols, fastSymbols, onRealtimeCallback, listenerGUID)

:chart: Trading Terminal specific.

symbols: array of symbols that should be updated rarely (once per minute). These symbols are included in the watchlist but they are not visible at the moment.
fastSymbols: array of symbols that should be updated frequently (once every 10 seconds or more often)
onRealtimeCallback: function(array of data)
1. data: symbol quote data
listenerGUID: unique identifier of the listener

Trading Terminal calls this function when it wants to receive real-time quotes for a symbol.

The Charting Library assumes that you will call onRealtimeCallback every time you want to update the quotes.

unsubscribeQuotes(listenerGUID)

:chart: Trading Terminal specific.

listenerGUID: unique identifier of the listener

Trading Terminal calls this function when it doesn't want to receive updates for this listener anymore.

listenerGUID will be the same object that the Library passed to subscribeQuotes before.

subscribeDepth(symbolInfo, callback): string

:chart: Trading Terminal specific.

symbolInfo: SymbolInfo object
callback: function(depth)
1. depth: object {snapshot, asks, bids}
  - snapshot: Boolean - if true asks and bids have full set of depth, otherwise they contain only updated levels.
  - asks: Array of {price, volume} (must be sorted by price in asc order)
  - bids: Array of {price, volume} (must be sorted by price in asc order)

Trading Terminal calls this function when it wants to receive real-time level 2 (DOM) for a symbol. The Charting Library assumes that you will call the callback every time you want to update DOM data.

This method should return a unique identifier (subscriberUID) that will be used to unsubscribe from the data.

unsubscribeDepth(subscriberUID)

:chart: Trading Terminal specific.

subscriberUID: String

Trading Terminal calls this function when it doesn't want to receive updates for this listener anymore.

subscriberUID will be the same object that was returned from subscribeDepth.