6 Streaming data

Streaming data is a near-real-time mechanism, where IQFeed sends ongoing asynchronous update messages to IQML of tick (quote and trade) and news events.

These messages can either be queried asynchronously (via ad-hoc queries, as shown in §6.1-§6.4 below), or handled synchronously (using callbacks (§10) or alerts (§11)).

6.1 Streaming quotes

The streaming quotes mechanism has two distinct parts:

Request IQFeed to start sending a stream of quotes for a specified security. This is done by using the 'quotes' action and setting a NumOfEvents parameter to a positive >1 value.

Later, whenever you wish to process the latest quote(s), simply use the 'quotes' action and NumOfEvents of -1 (minus one). This will return the latest information (a data struct), without stopping the background streaming.

For example, to request 100 streaming quotes for a continuous VIX future contract:

IQML('quotes', 'Symbol','@VX#', 'NumOfEvents',100)

IQFeed will start sending quotes to IQML in the background, up to the specified NumOfEvents, without affecting normal Matlab processing. You can continue to work in Matlab, process/display information etc., while quotes accumulate in the background.

warningQuotes will only stream in the background in non-blocking mode. If you assign the IQML command results to a variable, the request is treated as blocking and IQML will wait for all the events to accumulate (or Timeout to occur), as described in §4.1:

IQML('quotes', 'Symbol','@VX#', 'NumOfEvents',100); % streaming, non-blocking

data = IQML('quotes', 'Symbol','@VX#', 'NumOfEvents',100); % blocking

NumOfEvents can be any number higher than 1 for streaming to work (a value of 1 is the standard snapshot market-query request described in §4.1). To collect streaming quotes endlessly, set NumOfEvents to the value inf. Note that in Matlab, inf is a number (not a string), so do not enclose it in quotes ('inf').

The quotes are collected into an internal data buffer in IQML. A different buffer is maintained for each symbol. The buffer size can be controlled using the MaxItems parameter, which has a default value of 1. This means that by default only the latest streaming quote of each type (bid/ask) is stored, along with high/low/close data.

If you set a higher value for MaxItems,86 then up to the specified number of latest quotes will be stored. For example, to store the latest 5 quotes:

IQML('quotes', 'Symbol','@VX#', 'NumOfEvents',100, 'MaxItems',5)

warningNote: MaxItems increases memory usage, multiplied by the number of streamed symbols.87

Subsequent requests to retrieve the latest accumulated quotes buffer data, without stopping the background streaming, should use NumOfEvents = -1 (minus one). These requests return a Matlab data struct similar to the following:

>> data = IQML('quotes', 'Symbol','@VX#', 'NumOfEvents',-1)
data =
Symbol: '@VX#'
Command: 'w@VX#'
isActive: 0
EventsToProcess: 10
EventsProcessed: 10
LatestEventDatenum: 737128.637260451
LatestEventTimestamp: '20180309 15:17:39'
DataType: 'quotes and trades'
ProcessType: 'stream'
BufferSize: 3
Buffer: [3×1 struct]
LatestData: [1×1 struct]

In the returned data struct, we can see the following fields:

Symbol – the requested Symbol.

Command – the command sent to IQFeed, including the requested Symbol.

isActive logical flag indicating whether quotes are currently streamed for this security. When NumOfEvents ticks are received, this flag is set to false (0).

EventsToProcess – total number of streaming ticks requested for the security (using the NumOfEvents parameter).

EventsProcessed – number of streaming ticks received for this security. When EventsProcessed >= EventsToProcess, streaming quotes are turned off and isActive is set to false (0). Note that it is possible that EventsProcessed > EventsToProcess, since it takes a while for the streaming cancellation request to reach IQFeed, and during this time a few additional ticks may have arrived.

LatestEventDatenum – Matlab numeric datenum representation of the LatestEventTimestamp.

LatestEventTimestamp – local timestamp (string format) when this quote was received by IQML.

DataType – type of data to stream (set by DataType parameter, see below).

ProcessType – always equal to 'stream' for streaming quotes.

BufferSize – size of the data buffer (=MaxItems parameter, see below).

Buffer – buffer of size BufferSize, accumulating the latest quote updates.

LatestData – latest quote event received from IQFeed.

Different quotes are sent independently from IQFeed server with a unique timestamp. Note: data.LatestEventDatenum and data.LatestEventTimestamp are specified in local time-zone. In contrast, data.LatestData.Most_Recent_Trade_Time and data.Buffer.Most_Recent_Trade_Time use the server time-zone, typically US Eastern.

To get the quotes data, simply read the fields of the returned data struct, for example:88

>> data.LatestData
ans =
Symbol: '@VX#'
Most_Recent_Trade: 17.08
Most_Recent_Trade_Size: []
Most_Recent_Trade_Time: '08:06:20.716000'
Most_Recent_Trade_Market_Center: 32
Total_Volume: 4507
Bid: 17.05
Bid_Size: 63
Ask: 17.1
Ask_Size: 244
Open: 17.2
High: 17.35
Low: 17
Close: 17.23
Message_Contents: 'Cbasohlcv'
Message_Description: 'Last qualified trade; A bid update
occurred; An ask update occurred; A
settlement occurred; An open declaration
occurred; A high declaration occurred; A
low declaration occurred; A close
declaration occurred; A volume update
occurred'
Most_Recent_Trade_Conditions: '4D'
Trade_Conditions_Description: 'Implied'
Most_Recent_Market_Name: 'CBOE Futures Exchange (CFE)'

Note that data.LatestData is typically the same as data.Buffer(end), regardless of the values of MaxItems or NumOfEvents.89

Each streaming security asset can have a different BufferSize, by specifying a different MaxItems value in the command (large for heavily-traded assets, small for others).

Once the data is retrieved, you can direct IQML to clear (empty) the internal Buffer, by setting ClearBuffer to true or 1. The latest buffer will be returned, and the internal Buffer (but no other field) will be immediately emptied, awaiting new streaming quotes:90

data = IQML('quotes', 'symbol','IBM', 'NumOfEvents',-1, 'ClearBuffer',true);

To stop collecting streaming quotes, simply resend a request with NumOfEvents=0:

IQML('quotes', 'symbol','IBM', 'NumOfEvents',0);

IQFeed reports 16 standard data fields by default. If you have the Professional (or trial) IQML license, you can customize the returned data fields by requesting up to 50+ additional fields, removing standard fields, and setting the order of the reported fields. This can be done using the Fields parameter, as explained in §4.1. For example:

IQML('quotes', 'symbol','IBM', 'fields','Last,Ask,Bid', 'numOfEvents',6);

When DataType is 'q' or 'quotes', whenever any of the requested data fields (either the standard 16 fields, or a customized set) gets updated (not necessarily to a different value), a new tick (update/quote) message is sent/streamed. Adding data fields means a corresponding increase in tick messages. It is not possible in IQFeed to request data fields without the corresponding update messages for these fields (or vice versa). The only exception to this rule is setting DataType to 't' or 'trades': in this case only trade updates (containing all the requested fields) will be streamed, but no field updates.

In summary, the fewer data fields that are requested, the faster the run-time processing, and the lower the corresponding tick message rate, thus enabling a larger number of usable quotes to be streamed and processed by your Matlab program each second.

You can specify multiple symbols for streaming at the same time, in a single IQML command, by specifying a colon-delimited or cell-array list of symbols. For example:

IQML('quotes', 'symbols',{'IBM','GOOG','AAPL'}, 'numOfEvents',6);

IQML('quotes', 'symbols','IBM:GOOG:AAPL', 'numOfEvents',6); % equivalent

And similarly, when retrieving the accumulated streaming data:

>> data = IQML('quotes', 'symbol','IBM:GOOG:AAPL', 'numOfEvents',-1);
data =
1×3 struct array with fields:
Symbol
Command
isActive
EventsToProcess
EventsProcessed
LatestEventDatenum
LatestEventTimestamp
DataType
ProcessType
BufferSize
Buffer
LatestData

>> data(1).LatestData
ans =
struct with fields:
Symbol: 'IBM'
Most_Recent_Trade: 142.48
Most_Recent_Trade_Size: 41149
Most_Recent_Trade_Time: '17:33:40.531781'
Most_Recent_Trade_Market_Center: 19
...

To get the latest data for all streamed symbols, omit the Symbol parameter (or set it to empty ['']) in the IQML command. Note: this will return both active and non-active streams:

>> data = IQML('quotes', 'numOfEvents',-1); % no symbol: return ALL streams
data =
1×5 struct array with fields:
Symbol
Command
isActive
...

Similarly, to cancel all active streams in a single command, omit Symbol (or set it to ''):91

>> IQML('quotes', 'numOfEvents',0); % no symbol: stop ALL streams

IQFeed typically allows streaming up to 500 symbols. This limit can be increased by paying DTN for increased data subscriptions. In any case, the actual maximal number of concurrently-streaming symbols is limited by performance considerations (see §3.6).

Note that during non-trading hours, there is no streaming data (of course). To test the streaming-data mechanism during non-trading hours, use the dummy symbol TST$Y, for which IQFeed sends a continuous 24/7 stream of pre-recorded data.92

Here is a summary of the IQML parameters that directly affect streaming quotes:

Parameter

Data type

Default

Description

Symbol or Symbols 93

colon or comma-delimited string, or cell-array of strings

(none)

Limits the request to the specified symbol(s). Examples:

'@VX#'

'IBM:AAPL:GOOG'

'IBM,AAPL,GOOG'

{'IBM', 'AAPL', 'GOOG'}

This parameter must be set to valid symbol name(s) when NumOfEvents>0

NumOfEvents

integer

MaxItems

One of:

inf – continuous endless streaming quotes for the specified security

N>1 – stream only N quotes

1 – get only a single quote (default)

0 – stop streaming quotes

-1 – return latest accumulated quotes data while continuing to stream new quotes data

MaxItems

integer

1

Number of streaming quotes stored in cyclic buffer. Once this number of quotes are received old quotes are discarded as new quotes arrive.

DataType

string

'q'

One of:

'q' or 'quotes' (default) – stream both trades & quote (bid/ask update) events

't' or 'trades' – stream trade events only

Fields

colon or comma-separated string, or cell-array of strings

'Symbol, Most Recent Trade,
Most Recent Trade Size, Most Recent Trade Time, …'
(see
§4.1)

Sets the list of data fields reported by IQFeed for each quote. IQFeed’s default set has 16 fields; 50+ additional fields can be specified.

If Fields is set to an empty value ({} or ''), the list of current, available fields is returned.

If Fields is not empty, subsequent quotes queries will return the specified fields, in the specified order (Professional IQML license only). The Symbol field is always returned first, even if not specified.

Examples:

{'Bid', 'Ask', 'Last'}

'Bid, Ask, Last'

'Bid:Ask:Last'

'All' (indicates all available fields)

ClearBuffer

logical (true/false)

false

If true or 1, the internal cyclic quotes buffer is cleared after the data is returned to the caller.

6.2 Regional updates

Regional quotes are Bid and Ask prices delivered from various regional markets (exchanges). The streaming regional market update mechanism has two parts, just like streaming ticks (§6.1):

Request IQFeed to start sending a stream of regional updates. This is done by using the 'regional' action and setting a NumOfEvents parameter to a positive >1 value. You must specify the Symbol(s) for which regional updates will stream.

Later, whenever you wish to process the latest regional update(s), simply use the 'regional' action and NumOfEvents of -1 (minus one). This will return the latest information (a data struct), without stopping the background streaming.

For example, to request 100 streaming regional updates for Facebook:

IQML('regional', 'Symbol','FB', 'NumOfEvents',100)

This causes IQFeed to start sending regional updates to IQML in the background, up to the specified NumOfEvents, without affecting normal Matlab processing. You can continue to work with Matlab, process and display information etc., while the regional updates accumulate in the background.

warningRegional updates will only stream in the background in non-blocking mode. If you assign the IQML command results to a variable, the request is treated as blocking and IQML will wait for all data to accumulate (or Timeout to occur), as described in §7.2:

IQML('regional', 'Symbol','FB', 'NumOfEvents',100); % streaming, non-blocking

data = IQML('regional', 'Symbol','FB', 'NumOfEvents',100); % blocking

NumOfEvents can be any number higher than 1 for streaming to work (a value of 1 is the standard snapshot regional-update request described in §7.2). To collect streaming regional updates endlessly, set NumOfEvents to the value inf. Note that in Matlab, inf is a number (not a string), so do not enclose it in quotes ('inf').

The regional updates are collected into an internal data buffer in IQML. A different buffer is maintained for each symbol. The buffer size can be controlled using the MaxItems parameter, which has a default value of 194. This means that by default only the latest streaming regional update that affect the specified symbols will be stored in the buffer and become accessible for later processing.

If you set a higher value for MaxItems, then up to the specified number of latest regional update items will be stored. For example, to store the latest 5 updates:

IQML('regional', 'Symbol','FB', 'NumOfEvents',100, 'MaxItems',5)

warningNote that using a large MaxItems increases memory usage. This could have an adverse effect if you set a very large buffer size (many thousands) and/or streaming of a large number of different securities.95

Subsequent requests to retrieve the latest accumulated regional updates buffer data, without stopping the background streaming, should use NumOfEvents = -1 (minus one). These requests return a Matlab data struct similar to the following:

>> data = IQML('regional', 'Symbol','FB', 'NumOfEvents',-1)
data =
Symbol: 'FB'
Command: 'S,REGON,FB'
isActive: 0
EventsToProcess: 100
EventsProcessed: 100
LatestEventDatenum: 737146.784037153
LatestEventTimestamp: '20180327 18:49:00'
DataType: 'regional'
ProcessType: 'stream'
BufferSize: 50
Buffer: [50×1 struct]
LatestData: [1×1 struct]

In the returned data struct, we can see the following fields:

Symbol – the requested Symbol.

Command – the command sent to IQFeed, including the requested Symbol.

isActive – a logical flag indicating whether regional updates are currently being streamed for this security. When NumOfEvents ticks have been received, this flag is set to false (0).

EventsToProcess – total number of streaming regional updates requested (using the NumOfEvents parameter).

EventsProcessed – number of streaming regional updates received. When EventsProcessed >= EventsToProcess, streaming updates are turned off and isActive is set to false (0).
Note that it is possible that EventsProcessed > EventsToProcess, since it takes a while for the streaming cancellation request to reach IQFeed and during this time a few additional update messages may have arrived.

LatestEventDatenum – Matlab numeric datenum representation of the LatestEventTimestamp.

LatestEventTimestamp – local timestamp (string format) when this update was received by IQML.

DataType – always equal to 'regional' for streaming regional updates.

ProcessType – always equal to 'stream' for streaming regional updates.

BufferSize – size of the data buffer (=MaxItems parameter, see below).

Buffer – buffer of size BufferSize, accumulating the latest regional updates.

LatestData – latest regional update event received from IQFeed.

To get the regional updates data, simply read the fields of the returned data struct:96

>> data.LatestData
ans =
RegionalBid: 155.34
RegionalBidSize: 100
RegionalBidTime: '12:29:45'
RegionalAsk: 155.55
RegionalAskSize: 200
RegionalAskTime: '12:29:45'
FractionDisplayCode: 14
DecimalPrecision: 4
FractionDisplayDescription: 'Four decimal places'
MarketCenter: 11
MarketCenterDescription: 'NYSE Archipelago (NYSE_ARCA)'

Each update has an associated timestamp, since different regional updates are sent separately and independently from IQFeed server.

Note: data.LatestEventDatenum and data.LatestEventTimestamp are specified in the local time-zone; in contrast, data.LatestData.RegionalBidTime and .RegionalAskTime are specified in the server’s time-zone (typically US Eastern time zone).

Note that data.LatestData is typically the same as data.Buffer(end), regardless of the values of MaxItems or NumOfEvents.97

Each streaming security asset can have a different BufferSize, by specifying a different MaxItems value in the streaming command. This can be used for specifying a larger MaxItems for heavily-traded assets vs. lightly-traded ones.

Once the data is retrieved, you can direct IQML to clear (empty) the internal Buffer, by setting ClearBuffer to true or 1. The latest buffer will be returned, and the internal Buffer (but no other field) will be immediately emptied, awaiting new regional updates:98

data = IQML('regional', 'symbol','FB', 'NumOfEvents',-1, 'ClearBuffer',true);

To stop collecting regional updates, simply resend a request with NumOfEvents=0:

IQML('regional', 'symbol','FB', 'NumOfEvents',0);

You can specify multiple symbols for streaming at the same time, in a single IQML command, by specifying a colon-delimited or cell-array list of symbols. For example:

IQML('regional', 'symbols',{'IBM','GOOG','AAPL'}, 'numOfEvents',6);

IQML('regional', 'symbols','IBM:GOOG:AAPL', 'numOfEvents',6); % equivalent

As with streaming quotes (§6.1), to get the latest data for all streamed symbols, omit the Symbol parameter or set it to empty ['']. This returns all streams (both active/not):

>> data = IQML('regional', 'numOfEvents',-1); % no symbol: get ALL streams
data =
5×1 struct array with fields:
Symbol
Command
isActive
EventsToProcess
...

Similarly, to cancel all active streams in a single command, omit Symbol (or set it to ''):99

>> IQML('regional', 'numOfEvents',0); % no symbol: ALL streams are stopped

Here is a summary of the IQML parameters that affect streaming regional updates:

Parameter

Data type

Default

Description

Symbol or Symbols 100

colon or comma-delimited string, or cell-array of strings

(none)

Limits the request to the specified symbol(s). Examples:

'@VX#'

'IBM:AAPL:GOOG'

'IBM,AAPL,GOOG'

{'IBM', 'AAPL', 'GOOG'}

This parameter must be set to valid symbol name(s) when NumOfEvents>0

NumOfEvents

integer

MaxItems

One of:

inf – continuous endless streaming regional updates for specified security

N>1 – stream only N regional updates

1 – get only a single update (default)

0 – stop streaming regional updates

-1 – return the latest accumulated regional updates data while continuing to stream new regional updates data

MaxItems

integer

1

Number of streaming regional updates stored in a cyclic buffer. Once this number of updates has been received, the oldest update is discarded whenever a new update arrives.

ClearBuffer

logical (true/false)

false

If true or 1, the internal cyclic quotes buffer is cleared after the data is returned to the caller.

warningNote: Regional updates data is only available in the Professional IQML license.

6.3 Interval bars

The streaming interval bars feature has two parts, just like streaming ticks (§6.1):

Request IQFeed to start sending a stream of interval bars for a specified security. This is done by using the 'intervalbars' action and setting a NumOfEvents parameter to a positive >1 value.

Later, whenever you wish to process the latest interval bar(s), simply use the 'intervalbars' action and NumOfEvents of -1 (minus one). This will return the latest information (a data struct), without stopping the background streaming.

For example, request 600 streaming interval bars of a continuous VIX future contract:

IQML('intervalbars', 'Symbol','@VX#', 'NumOfEvents',600)

This causes IQFeed to start sending interval bars to IQML in the background, up to the specified NumOfEvents, without affecting normal Matlab processing. This means you can continue to work with Matlab, process data, display information etc.

warningQuotes will only stream in the background in non-blocking mode. If you assign the IQML command results to a variable, the request is treated as blocking and IQML will wait for all the events to accumulate (or Timeout to occur), as described in §4.1:

IQML('intervalbars', 'Symbol','@VX#', 'NumOfEvents',600); % streaming, non-blocking

data = IQML('intervalbars', 'Symbol','@VX#', 'NumOfEvents',600); % blocking

NumOfEvents can be any number higher than 1 for streaming to work. To collect streaming quotes endlessly, set NumOfEvents to the value inf. Note that in Matlab, inf is a number (not a string), so do not enclose it in quotes ('inf').

The quotes are collected into an internal data buffer in IQML. A different buffer is maintained for each symbol. The buffer size can be controlled using the MaxItems parameter, which has a default value of 1. This means that by default only the latest streaming interval bar is stored.

If you set a higher value for MaxItems,101 then up to the specified number of latest quotes will be stored, subject to IQFeed server limitations:102

IQML('intervalbars', 'Symbol','@VX#', 'NumOfEvents',600, 'MaxItems',3)

warningNote that using a large MaxItems increases memory usage, which could have an adverse effect if you use a very large buffer size (many thousands) and/or streaming for a large number of different securities.103

Subsequent requests to retrieve the latest accumulated interval bars buffer data, without stopping the background streaming, should use NumOfEvents = -1 (minus one). These requests return a Matlab data struct similar to the following:

>> data = IQML('intervalbars', 'Symbol','@VX#', 'NumOfEvents',-1)
data =
Symbol: '@VX#'
Command: 'BW,@VX#,60,,1,3,,,B'
isActive: 0
EventsToProcess: 600
EventsProcessed: 600
LatestEventDatenum: 737128.637260451
LatestEventTimestamp: '20180309 15:17:39'
DataType: 'intervalbars'
ProcessType: 'stream'
BufferSize: 3
Buffer: [3×1 struct]
LatestData: [1×1 struct]
MaxDaysToProcess: 1

In the returned data struct, we can see the following fields:

Symbol – the requested Symbol.

Command – the command sent to IQFeed, including the requested Symbol.

isActive logical flag indicating whether interval bars are currently streamed for the security. Once NumOfEvents bars are received this flag is set to false (0).

EventsToProcess – total number of streaming interval bars requested for the security (using the NumOfEvents parameter).

EventsProcessed number of streaming interval bars received for this security. When EventsProcessed>=EventsToProcess, streaming is turned off and isActive is set to false (0). Note: it is possible that EventsProcessed > EventsToProcess, since it takes a while for the streaming cancellation request to reach IQFeed, and during this time a few additional bars may have arrived.

LatestEventDatenum – Matlab numeric datenum representation of the LatestEventTimestamp.

LatestEventTimestamp – local timestamp (string format) when this bar was received by IQML.

DataType – type of data to stream (set by DataType parameter, see below).

ProcessType – always equal to 'stream' for streaming interval bars.

BufferSize – size of the data buffer (=MaxItems parameter, see below).

Buffer – buffer of size BufferSize, accumulating the latest quote updates.

LatestData – single latest interval bar received from IQFeed.

MaxDaysToProcess – maximal number of days with intervals data to process.

To retrieve the interval bars data, read the fields of the returned data struct:

>> data.LatestData
ans =
Symbol: '@VX#'
BarType: 'Complete interval bar from history'
Timestamp: '2018-03-09 15:17:39'
Open: 17.55
High: 17.6
Low: 17.55
Close: 17.6
CummlativeVolume: 4550
IntervalVolume: 11
NumberOfTrades: 0

Note that data.LatestData is typically the same as data.Buffer(end), regardless of the values of MaxItems or NumOfEvents.104

Different interval bars are sent independently from IQFeed server with a unique timestamp. Note that data.LatestEventDatenum and data.LatestEventTimestamp are specified in the local time-zone.

The data.LatestData.BarType field indicates whether this is a historic bar, or a bar from the live (real-time) stream, or an updated interval bar.

The data.LatestData.NumberOfTrades field indicates the number of trades that occurred within this bar (i.e., not cumulative), relevant only when IntervalType is 'ticks'/'trades'.

The IntervalType (default: 'secs') and IntervalSize (default: 60) parameters should typically be specified together. Note that IntervalSize must be a positive integer value (i.e. its value cannot be 4.5 or 0). If IntervalType is 'ticks'/'trades', IntervalSize must be 2 or higher. If IntervalType is 'volume', IntervalSize must be 100 or higher. If IntervalType is 'secs', IntervalSize must be any integer between 1-300 (5 minutes), or any multiple of 60 (1 minute) between 300-3600 (1 hour), or 7200 (2 hours).105

Each streaming security asset can have a different BufferSize, by specifying a different MaxItems value in the streaming command. This can be used for specifying a larger MaxItems for heavily-traded assets vs. lightly-traded ones.

Once the data is retrieved, you can direct IQML to clear (empty) the internal Buffer, by setting ClearBuffer to true or 1. The latest buffer will be returned, and the internal Buffer (but no other field) will be immediately emptied, awaiting new interval bars:106

data = IQML('intervalbars', 'symbol','IBM', 'NumOfEvents',-1, ...
'ClearBuffer',true);

To stop collecting interval bars, simply resend a request with NumOfEvents=0:

IQML('intervalbars', 'symbol','IBM', 'NumOfEvents',0);

You can specify multiple symbols for streaming at the same time, in a single IQML command, by specifying a colon-delimited or cell-array list of symbols. For example:

IQML('intervalbars', 'symbols',{'IBM','GOOG','AAPL'}, 'numOfEvents',6);

IQML('intervalbars', 'symbols','IBM:GOOG:AAPL', 'numOfEvents',6); % equivalent

As with streaming quotes (§6.1), to get the latest data for all streamed symbols, omit the Symbol parameter or set it to empty ['']. This returns all streams (both active/not):

>> data = IQML('intervalbars', 'numOfEvents',-1); % no symbol: get ALL streams
data =
5×1 struct array with fields:
Symbol
Command
isActive
...

Similarly, to cancel all active streams in a single command, omit Symbol (or set it to ''):

>> IQML('intervalbars', 'numOfEvents',0); % no symbol: stop ALL streams

warningInterval bars can also fetch historical bars data, starting from the date/time that is set by the BeginDateTime parameter (see the parameters table below). This is similar to (and subject to the same limitations as) fetching historical interval data (see §5.4), but with no specified end point. IQML will return both the historical bars, as well as new real-time streaming interval bars, as they become available. BeginDateTime’s default value is 00:00:00 today (server time), so you will almost always get historical bars before live streaming bars. If you run the query at mid-day, you may get hundreds of historical bars before you get the first live streaming bar. So, if you set NumOfEvents to a low value, you might receive only historical bars, without any live streaming bars.

The following parameters affect interval bars data queries:

Parameter

Data type

Default

Description

Symbol or Symbols 107

colon or comma-delimited string, or cell-array of strings

(none)

Limits the request to the specified symbol(s). Examples:

'@VX#'

'IBM:AAPL:GOOG'

'IBM,AAPL,GOOG'

{'IBM', 'AAPL', 'GOOG'}

This parameter must be set to valid symbol name(s) when NumOfEvents>0

NumOfEvents

integer

MaxItems

One of:

inf – continuous endless streaming interval bars for specified symbol(s)

N>1 – stream only N interval bars

1 – get only a single interval bar

0 – stop streaming interval bars

-1 – return latest interval bars data while continuing to stream new bars

MaxItems

integer

100

Returns up to the specified number of bars (if available).

MaxDays

integer

1

Max number of trading days to retrieve

IntervalType

string

'secs'

Sets the type of interval size. One of the following values:

's' or 'secs' – time [seconds] (default)

'v' or 'volume' – traded volume

't' or 'ticks' – number of ticks

IntervalSize

integer

60

Size of bars in IntervalType units. Must be ≥1 for secs, ≥2 for ticks, ≥100 for volume.

BeginFilterTime

string

'00:00:00'

Only return bars that begin after this time of day (US Eastern time-zone).
Format: ‘hhmm’, ‘hh:mm’, ‘hhmmss’ or ‘hh:mm:ss’.

EndFilterTime

string

'23:59:59'

Only return bars that end before this time of day (US Eastern time-zone).
Format: ‘hhmm’, ‘hh:mm’, ‘hhmmss’ or ‘hh:mm:ss’.

BeginDateTime

integer or string or datetime object

''
(empty string) meaning today at 00:00:00

Only return bars that begin after this date/time (US Eastern time-zone).
Format: Matlab datenum, ‘yyyymmdd hhmmss’ or ‘yyyy-mm-dd hh:mm:ss’.

Note: there is no corresponding EndDateTime parameter for streaming intervalbars (only for historic bars: §5.4).

Timeout

number

5.0

Max number of seconds to wait (0-9000) for data in blocking mode (0 means infinite)

ClearBuffer

logical (true/false)

false

If true or 1, the internal cyclic quotes buffer is cleared after data is returned to the caller

6.4 Market depth (Level 2)

The streaming market depth mechanism also has two distinct parts, just like streaming level 1 quotes (§6.1):

Request IQFeed to start sending a stream of market depth quotes for a specified security. This is done by using the 'marketdepth' action.

Later, whenever you wish to process the latest market depth data, simply use the 'marketdepth' action and NumOfEvents of -1 (minus one). This will return the latest information (a data struct), without stopping the background streaming.

For example, let’s request market depth quotes for a continuous E-mini contract:

IQML('marketdepth', 'Symbol','@ES#')

This causes IQFeed to start sending market depth updates to IQML in the background, up to the specified NumOfEvents, if defined, without affecting normal Matlab processing. This means you can continue to work with Matlab, process data, display information etc.

Note that each incoming quote message updates the data for a single market depth row. The market depth row cannot be specified nor predicted by the user, and the order of messages is unrelated to the market depth row, for example, an update for row #3 can follow an update of row #5.

warningMarket depth data will only stream in the background in non-blocking mode. If you assign the IQML command results to a variable, the request is treated as blocking and IQML will wait for all the events to accumulate (or Timeout to occur), as described in §4.1:

IQML('marketdepth', 'Symbol','@ES#', 'NumOfEvents',600); % streaming, non-blocking

data = IQML('marketdepth', 'Symbol','@ES#', 'NumOfEvents',600); % blocking

NumOfEvents is an optional input parameter and can be any number higher than 1 for streaming to work. To collect market depth data endlessly, set NumOfEvents to the value inf. Note that in Matlab, inf is a number (not a string), so do not enclose it in quotes ('inf').

The quotes are collected into an internal data structure in IQML. A different structure is maintained for each symbol.

Subsequent requests to retrieve the latest accumulated interval bars buffer data, without stopping the background streaming, should use NumOfEvents = -1 (minus one). These requests return a Matlab data struct similar to the following:

>> data = IQML('marketdepth', 'Symbol','@ES#', 'NumOfEvents',-1)
data =
Symbol: '@ES#'
Command: 'w@ES#'
EventsToProcess: 600
EventsProcessed: 437
IncludeEmptyQuotes: 0
LatestData: [1×10 struct]
LatestEventDatenum: 737195.518211377
LatestEventTimestamp: '20180515 12:26:13'

In the returned data struct, we can see the following fields:

Symbol – the requested Symbol.

Command – the command sent to IQFeed, including the requested Symbol.

EventsToProcess – total number of streaming interval bars requested for the security (using the NumOfEvents parameter).

EventsProcessed – number of streaming market depth data quotes received for this security. When EventsProcessed >= EventsToProcess, streaming market depth data for this security is turned off.

IncludeEmptyQuotes – value of the specified IncludeEmptyQuotes parameter (default value: false). If true or 1, then empty quotes (having no valid Bid or Ask) will be reported and be counted as a valid “event”; otherwise they will not.

LatestData – latest data received by IQFeed for each market depth row.

LatestEventDatenum – Matlab numeric datenum representation of the LatestEventTimestamp.

LatestEventTimestamp – local timestamp (string format) when latest market depth quote was received by IQML.

ProcessType – 'stream' to collect data in the background or 'block' to wait for data to come in and return it.

To retrieve the market depth data at the nth market depth row, simply read the fields of the LatestData at the nth location, for example:

>> data.LatestData(4)
ans =
Symbol: '@ES#'
ID: 'MD04'
Bid: 2725.5
Ask: 2727.25
BidSize: 65
AskSize: 148
BidTime: '05:25:59.761191'
Date: '2018-05-15'
AskTime: '05:25:59.760278'
BidInfoValid: 1
AskInfoValid: 1
Condition: 52
Condition_Description: 'regular'
ID_Description: 'Order book row #4'

BidInfoValid and AskInfoValid values are logical (true/false) values, which appear as 1 or 0, respectively, in the struct display above. The ID field indicates the corresponding order-book row (for futures) or market-maker name (for equities).

Different market depth quotes are sent independently from the IQFeed server with a unique timestamp, in a non-ordered manner. Note that data.LatestEventDatenum and data.LatestEventTimestamp are specified in the local time-zone.

Note: unlike streaming quotes (§6.1), regional updates (§6.2), and interval bars (§6.3), the streaming market depth mechanism does not store an internal buffer of quote updates, so there is no Buffer field. Only the latest snapshot of the deep order book (in the LatestData field) is updated.

To stop collecting market depth quotes for a security, simply send the request again, this time with NumOfEvents=0.

IQML('marketdepth', 'Symbol','@ES#', 'NumOfEvents',0);

You can specify multiple symbols for streaming at the same time, in a single IQML command, by specifying a colon-delimited or cell-array list of symbols. For example:

IQML('marketdepth', 'symbols',{'IBM','GOOG','AAPL'});

IQML('marketdepth', 'symbols','IBM:GOOG:AAPL'); % equivalent

As with the blocking request (§4.4), you’ll receive an error message when requesting market depth info from an exchange for which you have no Level 2 data subscription:

>> data = IQML('marketdepth', 'Symbol','IBM', ...) %not subscribed to NYSE L2

Error using IQML
Symbol 'IBM' was not found!

As with streaming quotes (§6.1), to get the latest data for all streamed symbols, omit the Symbol parameter or set it to empty ['']. This returns all streams (both active/not):

>> data = IQML('marketdepth', 'numOfEvents',-1); % no symbol: get ALL streams
data =
5×1 struct array with fields:
Symbol
Command
isActive
EventsToProcess
...

Similarly, to cancel all active streams in a single command, omit Symbol (or set it to ''):

>> IQML('marketdepth', 'numOfEvents',0); % no symbol: ALL streams are stopped

Refer to §4.4 above for a detailed description of the parameters that affect market depth data queries.

warningNote: Market Depth (Level 2) data is only available in the Professional IQML license.


86 MaxItems is a numeric parameter like NumOfEvents, so don’t enclose the parameter value within string quotes (‘’)

87 Quotes use ~3KB of Matlab memory. So, if MaxItems=1500, then for 80 symbols IQML would need 80*1500*3KB = 360MB of Matlab memory when all 80 buffers become full (which could take a while).

88 The textual description fields depend on the MsgParsingLevel parameter having a value of 2 or higher (see §3.2 and §8)

89 When NumOfEvents events have been received, IQFeed is instructed to stop streaming updates, but some update messages may already be on their way from IQFeed before streaming actually stops. These extra update messages are not accumulated in the Buffer, but the latest of these messages will be reflected in LatestData field.

90 During and around the time of the buffer clear, some streaming data may be lost, so it is advised not to clear to often…

91 Note that cancelling all active streams cancels streaming regional updates (§6.2) in addition to streaming quotes.

92 IQFeed’s streaming functionality of TST$Y is currently broken. To get notified when DTN reports that the functionality is fixed, follow this forum thread: http://forums.dtn.com/index.cfm?page=topic&topicID=4286

93 In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization

94 Note that MaxItems is a numeric parameter like NumOfEvents, so don’t enclose the parameter value within string quotes (‘’)

95 Each regional update item uses 2KB of Matlab memory. During trading hours, there could be dozens of updates per second for highly liquid symbols (i.e., 500MB or more per hour, if all updates are saved). Limiting MaxItems to some finite value ensures that the memory usage and performance impact remain low.

96 The textual Description fields depend on the MsgParsingLevel parameter having a value of 2 or higher (see §3.2 and §8)

97 When NumOfEvents events have been received, IQFeed is instructed to stop streaming updates, but one or more update messages may already be on their way from IQFeed before streaming actually stops. These extra update messages are not accumulated in the Buffer, but the latest of these messages will be reflected in LatestData field.

98 During and around the time of the buffer clear, some streaming data may be lost, so it is advised not to clear to often…

99 Note that cancelling all active streams cancels streaming quotes (§6.1) in addition to streaming regional updates.

100 In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization

101 MaxItems is a numeric parameter like NumOfEvents, so don’t enclose the parameter value within string quotes (‘’)

102 The number of reported bars may possibly be limited by the IQFeed server, depending on your data subscriptions and exchange.

103 Interval bars use ~2KB of Matlab memory. So, if MaxItems=1500, then for 80 symbols IQML would need 80*1500*2KB = 240MB of Matlab memory when all 80 buffers become full (which could take a while).

104 When NumOfEvents events have been received, IQFeed is instructed to stop streaming updates, but one or more update messages may already be on their way from IQFeed before streaming actually stops. These extra update messages are not accumulated in the Buffer, but the latest of these messages will be reflected in LatestData field.

105 Note that IQFeed’s limitations on live 'secs' interval bars are stricter than the limitations on historical interval bars (§5.4): http://forums.dtn.com/index.cfm?page=topic&topicID=5529

106 During and around the time of the buffer clear, some streaming data may be lost, so it is advised not to clear to often…

107 In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization