What it is ?: A set of JS methods (specific public interface).
What should I do to use it ?: You should create a JS object which will receive the data by some way and respond to Charting Library requests.
Data caching (history & symbol info) is implemented in Charting Library. When you create an object implementing described interface, just pass it to Library widget constructor through [[datafeed
argument|Widget-Constructor#datafeed-mandatory]].
Methods
- [[onReady|JS-Api#onreadycallback]]
- [[searchSymbols|JS-Api#searchsymbolsuserinput-exchange-symboltype-onresultreadycallback]]
- [[resolveSymbol|JS-Api#resolvesymbolsymbolname-onsymbolresolvedcallback-onresolveerrorcallback]]
- [[getBars|JS-Api#getbarssymbolinfo-resolution-from-to-onhistorycallback-onerrorcallback-firstdatarequest]]
- [[subscribeBars|JS-Api#subscribebarssymbolinfo-resolution-onrealtimecallback-subscriberuid-onresetcacheneededcallback]]
- [[unsubscribeBars|JS-Api#unsubscribebarssubscriberuid]]
- [[calculateHistoryDepth|JS-Api#calculatehistorydepthresolution-resolutionback-intervalback]]
- [[getMarks|JS-Api#getmarkssymbolinfo-startdate-enddate-ondatacallback-resolution-optional]]
- [[getTimescaleMarks|JS-Api#gettimescalemarkssymbolinfo-startdate-enddate-ondatacallback-resolution]]
- [[getServerTime|JS-Api#getservertimecallback]]
:chart: [[Trading Terminal]] specific:
- [[getQuotes|JS-Api#chart-getquotessymbols-ondatacallback-onerrorcallback]]
- [[subscribeQuotes|JS-Api#chart-subscribequotessymbols-fastsymbols-onrealtimecallback-listenerguid]]
- [[unsubscribeQuotes|JS-Api#chart-unsubscribequoteslistenerguid]]
- :chart: [[subscribeDepth|JS-Api#chart-subscribedepthsymbolinfo-callback-string]]
- :chart: [[unsubscribeDepth|JS-Api#chart-unsubscribedepthsubscriberuid]]
onReady(callback)
-
callback
: function(configurationData)-
configurationData
: object (see below)
-
This call is intended to provide the object filled with configuration data.
This data affects some of chart behavior aspects so it is called [[server-side customization|Customization Overview#customization-done-through-data-stream]].
Charting Library expects you will call callback and pass your datafeed configurationData
as an argument.
Configuration data is an object; for now, 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 (see below).
exchanges
= [] leads to exchanges filter absence in Symbol Search list. Use value
= "" if you want to create wildcard filter (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.
symbolsTypes
= [] leads to types filter absence in Symbol Search list. Use value
= "" if you want to create wildcard filter (all types)
supported_resolutions
An array of supported resolutions. Resolution must be a string. Format is described in another [[article|Resolution]].
'resolutions'=undefined or [] leads to resolutons widget having its default content (see http://tradingview.com/e/ ). Example: [1, 15, 240, "D", "6M"]
will give you "1 minute, 15 minutes, 4 hours, 1 day, 6 months" in resolution widget.
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 in 2 parts: a root and an expiration.
Sample regex: : /^(.+)([12]!|[FGHJKMNQUVXZ]\d{1,2})$/
. It will be applied to the instruments whose type
is futures
.
searchSymbols(userInput, exchange, symbolType, onResultReadyCallback)
-
userInput
: string. It is text entered by user in 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 e.t.c. (chosen by user). Empty value means no filter was specified. -
onResultReadyCallback
: function(result)-
result
: array (see below)
-
This call is intended to provide the list of symbols matching to user's search query. result
is expected to be smth like this:
[
{
"symbol": ,
"full_name": // e.g., BTCE:BTCUSD
"description": ,
"exchange": ,
"ticker": ,
"type": "stock" | "futures" | "bitcoin" | "forex" | "index"
}, {
// .....
}
]
If no symbols are found, then callback should be called with an empty array. See more details about ticker
value [[here|Symbology#ticker]]
resolveSymbol(symbolName, onSymbolResolvedCallback, onResolveErrorCallback)
-
symbolName
: string. Symbol name orticker
if provided. -
onSymbolResolvedCallback
: function([[SymbolInfo|Symbology#symbolinfo-structure]]) -
onResolveErrorCallback
: function(reason)
Charting Library will call this function when it need to get [[SymbolInfo|Symbology#symbolinfo-structure]] by symbol's name.
getBars(symbolInfo, resolution, from, to, onHistoryCallback, onErrorCallback, firstDataRequest)
-
symbolInfo
: [[SymbolInfo|Symbology#symbolinfo-structure]] object -
resolution
: string -
from
: unix timestamp, leftmost required bar time -
to
: unix timestamp, rightmost required bar time -
onHistoryCallback
: function(array ofbar
s,meta
= { noData = false })-
bar
: object{time, close, open, high, low, volume}
-
meta
: object{noData = true | false, nextTime - unix time}
-
-
onErrorCallback
: function(reason) -
firstDataRequest
: boolean to identify the first history call for this symbol/resulution. When it istrue
you can ignoreto
(which depends on browser'sDate.now()
) and return bars up to current bar (including it).
This function is called when chart needs a history fragment defined by dates range. The charting library expects onHistoryCallback
to be called just once after receiving all the requesting history. No further calls are expected.
Important: nextTime
is a time of the next bar in the history. It should be set when there is no data in the requested period only.
Important: noData
should be set when there is no data in the requested period and earlier only.
Remark: bar.time
is expected to be the amount of milliseconds since Unix epoch start in UTC timezone.
Remark: bar.time
for daily bars is expected to be a trading day (not session start day) at 00:00 UTC. Charting Library aligns time according to Session from SymbolInfo
Remark: bar.time
for monthly bars is the first trading day of the month without the time part
subscribeBars(symbolInfo, resolution, onRealtimeCallback, subscriberUID, onResetCacheNeededCallback)
-
symbolInfo
: [[SymbolInfo|Symbology#symbolinfo-structure]] object -
resolution
: string -
onRealtimeCallback
: function(bar)-
bar
: object{time, close, open, high, low, volume}
-
-
subscriberUID
: object -
onResetCacheNeededCallback
(since 1.7): function() to be executed when bars data has changed
Charting Library calls this function when it wants to receive realtime updates for a symbol. Chart expects you will call onRealtimeCallback
every time you want to update the most recent bar or to append a new one.
Remark: When you call onRealtimeCallback
with bar having time equal to most recent bar's time, the whole 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 bar with time
1419411578413
already exists and is the most recent one - Library replaces the whole bar so now the most recent bar is
{1419411578413, 10, 14, 9, 14}
Remark 2: Is it possible either to update the most recent bar or to append a new one with onRealtimeCallback
. You've get an error if you call this function trying to update a bar in history.
Remark 3: For now, there is no way to change bars in history after the chart received it.
unsubscribeBars(subscriberUID)
-
subscriberUID
: object
Library calls this function when is doesn't want to receive updates for this subscriber any more. subscriberUID
will be the same object which Library passed to subscribeBars
before.
calculateHistoryDepth(resolution, resolutionBack, intervalBack). Optional.
-
resolution
: requested symbol's resolution -
resolutionBack
: desired history period dimension. Supported values:D
|M
-
intervalBack
: amount orresolutionBack
periods which Library is going to request
Charting Library calls this function when it is going to request some history data to give you an ability to override required history depth. It passes some arguments so you could know how much bars is it going to get. Here are a few 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 want to override anything. If you do, it should return an object {resolutionBack, intervalBack}
. Properties meaning is similar to respective arguments' one.
Example:
Assume the implementation is
Datafeed.prototype.calculateHistoryDepth = function(resolution, resolutionBack, intervalBack) {
if (period == "1D") {
return {
resolutionBack: 'M',
intervalBack: 6
};
}
}
This means when Charting Library will request the data for '1D' resolution, the history will be 6 months in depth. In all other cases the history depth will have the default value.
getMarks(symbolInfo, startDate, endDate, onDataCallback, resolution). Optional.
-
symbolInfo
: [[SymbolInfo|Symbology#symbolinfo-structure]] object -
startDate
: unix timestamp (UTC). Leftmost visible bar's time. -
endDate
: unix timestamp (UTC). Rightmost visible bar's time. -
onDataCallback
: function(array ofmark
s) -
resolution
: string
Library calls this function to get [[marks|Marks-On-Bars]] for visible bars range. Chart expects you to call onDataCallback
only once per each getMarks
call. mark
is an object having following properties:
- id: unique mark id. Will be passed to a [[respective callback|Widget-Methods#onbarmarkclickedcallback]] 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: minimal size of mark (diameter, pixels)
A few marks per bar are allowed (for now, maximum is 10). Marks out of bars are not allowed.
Remark: This function will be called only if you declared your back-end is [[supporting marks|JS-Api#supports_marks]].
getTimescaleMarks(symbolInfo, startDate, endDate, onDataCallback, resolution). Optional.
-
symbolInfo
: [[SymbolInfo|Symbology#symbolinfo-structure]] object -
startDate
: unix timestamp (UTC). Leftmost visible bar's time. -
endDate
: unix timestamp (UTC). Rightmost visible bar's time. -
onDataCallback
: function(array ofmark
s) -
resolution
: string
Library calls this function to get timescale marks for visible bars range. Chart expects you to call onDataCallback
only once per each getTimescaleMarks
call. mark
is an object having following properties:
- id: unique mark id. Will be passed to a [[respective callback|Widget-Methods#ontimescalemarkclickedcallback]] 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 out of bars are not allowed.
Remark: This function will be called only if you declared your back-end is [[supporting marks|JS-Api#supports_timescale_marks]].
getServerTime(callback)
-
callback
: function(unixTime)
This function is called if configuration flag supports_time
is set to true
when chart needs to know the server time. The charting library expects callback to be called once. The time is provided without milliseconds. Example: 1445324591
. It is used to display Countdown on the price scale.
:chart: [[Trading Terminal]] specific
:chart: getQuotes(symbols, onDataCallback, onErrorCallback)
-
symbols
: array of symbols names -
onDataCallback
: function(array ofdata
)-
data
: [[symbol quote data|Quotes#symbol-quote-data]]
-
-
onErrorCallback
: function(reason)
This function is called when chart needs quotes data. The charting library expects onDataCallback to be called once when all requesting data received. No further calls are expected.
:chart: subscribeQuotes(symbols, fastSymbols, onRealtimeCallback, listenerGUID)
-
symbols
: array of symbols to be updated rarely (suggested frequency is once per minute). These symbols are in the watch list but they are not visible at the moment. -
fastSymbols
: array of symbols to be updated quite frequently (once in 10 seconds or more often) -
onRealtimeCallback
: function(array ofdata
)-
data
: [[symbol quote data|Quotes#symbol-quote-data]]
-
-
listenerGUID
: unique identifier of the listener
Trading Terminal calls this function when it wants to receive realtime quotes for a symbol. Chart expects you will call onRealtimeCallback
every time you want to update quotes.
:chart: unsubscribeQuotes(listenerGUID)
-
listenerGUID
: unique identifier of the listener
Trading Terminal calls this function when is doesn't want to receive updates for this listener any more. listenerGUID
will be the same object which Library passed to subscribeQuotes
before.
:chart: subscribeDepth(symbolInfo, callback): String
-
symbolInfo
: [[SymbolInfo|Symbology#symbolinfo-structure]] object -
callback
: function(depth)-
depth
: object{snapshot, asks, bids}
-
snapshot
: Boolean - iftrue
asks
andbids
have full set of depth, otherwise they contain only updated levels. -
asks
: Array of{price, volume}
-
bids
: Array of{price, volume}
-
-
Trading Terminal calls this function when it wants to receive realtime level 2 (DOM) for a symbol. Chart expects you will call callback
every time you want to update depth data.
This method should return unique identified (subscriberUID) that will be used to unsubscribe data.
:chart: unsubscribeDepth(subscriberUID)
-
subscriberUID
: String
Trading Terminal calls this function when is doesn't want to receive updates for this listener any more. subscriberUID
will be the same object which you have returned from subscribeDepth
.