IQML User Guide
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 150
| Download | |
| Open PDF In Browser | View PDF |
IQML User Guide
Version 2.11
November 28, 2018
Fully compatible with:
Windows, Linux, Mac OS
DTN IQFeed 5.0 - 6.0
MATLAB R2008a - R2018b
© Yair Altman, Octahedron Ltd.
http://IQML.net
Undocumented Matlab
unbelievable features; unbelievable quality; unbelievable cost effectiveness; unbelievable service
IQML User Guide
2
Table of Contents
DISCLAIMER .................................................................................................................... 4
1 Introduction ..................................................................................................................... 5
2 Installation and licensing ................................................................................................. 6
2.1 Installing IQML .............................................................................................................. 6
2.2 Licensing and activation................................................................................................. 7
2.3 Switching activated computers ....................................................................................... 9
2.4 Updating the installed version ........................................................................................ 9
3 Using IQML .................................................................................................................. 10
3.1 General usage............................................................................................................... 10
3.2 General properties ....................................................................................................... 13
3.3 Blocking & non-blocking modes................................................................................... 13
3.4 Common causes of confusion ....................................................................................... 14
3.5 Returned data format.................................................................................................... 16
3.6 Run-time performance .................................................................................................. 17
4 Querying the latest market data ..................................................................................... 20
4.1 Snapshot (top of book) quotes ...................................................................................... 20
4.2 Fundamental information ............................................................................................. 29
4.3 Interval bars ................................................................................................................. 31
4.4 Market depth (Level 2) ................................................................................................. 34
4.5 Greeks, fair value, and implied volatility ..................................................................... 35
5 Historical and intra-day data .......................................................................................... 40
5.1 Daily data ..................................................................................................................... 40
5.2 Weekly data .................................................................................................................. 44
5.3 Monthly data ................................................................................................................ 46
5.4 Interval data ................................................................................................................. 48
5.5 Tick data ....................................................................................................................... 53
6 Streaming data ............................................................................................................... 58
6.1 Streaming quotes .......................................................................................................... 58
6.2 Regional updates .......................................................................................................... 63
6.3 Interval bars ................................................................................................................. 67
6.4 Market depth (Level 2) ................................................................................................. 71
7 News .............................................................................................................................. 74
7.1 Configuration ............................................................................................................... 74
7.2 Story headlines ............................................................................................................. 75
7.3 Story text ....................................................................................................................... 79
7.4 Story count.................................................................................................................... 81
7.5 Streaming news headlines ............................................................................................ 83
8 Lookup of symbols and codes ....................................................................................... 87
8.1 Symbols lookup ............................................................................................................. 87
8.2 Options/futures chain ................................................................................................... 92
8.3 Markets lookup ............................................................................................................. 97
8.4 Security types lookup .................................................................................................... 99
8.5 SIC codes lookup ........................................................................................................ 101
8.6 NAICS codes lookup ................................................................................................... 103
8.7 Trade condition codes lookup .................................................................................... 105
IQML User Guide
3
9 Connection, administration and other special commands............................................ 107
9.1 Connecting & disconnecting from IQFeed ................................................................. 107
9.2 Server time.................................................................................................................. 109
9.3 Client stats .................................................................................................................. 110
9.4 Sending a custom command to IQFeed ...................................................................... 113
10 Attaching user callbacks to IQFeed messages ........................................................... 114
10.1 Processing IQFeed messages in IQML .................................................................... 114
10.2 Run-time performance implications ......................................................................... 118
10.3 Usage example – using callbacks to parse options/futures chains ........................... 119
10.4 Usage example – using callbacks for realtime quotes GUI updates ........................ 120
10.5 Usage example – using callbacks for realtime order-book GUI updates ................. 121
11 Alerts ......................................................................................................................... 124
11.1 General Usage.......................................................................................................... 124
11.2 Alert Configuration .................................................................................................. 126
11.3 Alerts Query ............................................................................................................. 130
11.4 Alert Editing or Deletion .......................................................................................... 130
12 Messages and logging ................................................................................................ 131
13 Frequently-asked questions (FAQ) ............................................................................ 134
14 Troubleshooting ......................................................................................................... 137
15 Professional services .................................................................................................. 139
15.1 Sample program screenshots .................................................................................... 140
15.2 About the author ....................................................................................................... 143
Appendix A – online resources....................................................................................... 144
Appendix B – change log ............................................................................................... 145
IQML User Guide
4
DISCLAIMER
THIS SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND/OR
NONINFRINGEMENT.
THIS SOFTWARE IS NOT OFFICIALLY APPROVED OR ENDORSED BY ANY
REGULATORY, GOVERNING OR COMMERCIAL BODY, INCLUDING SEC, FINRA,
MATHWORKS AND/OR DTN.
MUCH EFFORT WAS INVESTED TO ENSURE THE CORRECTNESS, ACCURACY
AND USEFULNESS OF THE INFORMATION PRESENTED IN THIS DOCUMENT
AND THE SOFTWARE. HOWEVER, THERE IS NEITHER A GUARANTEE THAT THE
INFORMATION IS COMPLETE OR ERROR-FREE, NOR THAT IT MEETS THE
USER’S NEEDS. THE AUTHOR AND COPYRIGHT HOLDERS TAKE ABSOLUTELY
NO RESPONSIBILITY FOR POSSIBLE CONSEQUENCES DUE TO THIS DOCUMENT
OR USE OF THE SOFTWARE.
THE FUNCTIONALITY OF THE SOFTWARE DEPENDS, IN PART, ON THE
FUNCTIONALITY OF OTHER SOFTWARE, HARDWARE, SYSTEMS AND SERVICES
BEYOND OUR CONTROL. SUCH EXTERNAL COMPONENTS MAY CHANGE OR
STOP TO FUNCTION AT ANY TIME, WITHOUT PRIOR NOTICE AND WITHOUT
OUR CONTROL. THEREFORE, THERE CAN BE NO ASSURANCE THAT THE
SOFTWARE WOULD WORK, AS EXPECTED OR AT ALL, AT ANY GIVEN TIME.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
ANY CLAIM, DAMAGES, LOSS, OR OTHER LIABILITY, WHETHER IN ACTION OF
CONTRACT OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH
THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE,
REGARDLESS OF FORM OF CLAIM OR WHETHER THE AUTHORS WERE
ADVISED OF SUCH LIABILITIES.
WHEN USING THIS DOCUMENT AND SOFTWARE, USERS MUST VERIFY THE
BEHAVIOR CAREFULLY ON THEIR SYSTEM BEFORE USING THE SAME
FUNCTIONALITY FOR LIVE TRADES. USERS SHOULD EITHER USE THIS
DOCUMENT AND SOFTWARE AT THEIR OWN RISK, OR NOT AT ALL.
ALL TRADING SYMBOLS AND TRADING ORDERS DISPLAYED IN THE
DOCUMENTATION ARE FOR ILLUSTRATIVE PURPOSES ONLY AND ARE NOT
INTENDED TO PORTRAY A TRADING RECOMMENDATION.
IQML User Guide
5
1 Introduction
DTN provides financial data-feed services via its IQFeed service (www.iqfeed.net).
IQFeed customers use its services using a specialized application (“client”) that can
be installed on the user’s computer.1 User programs can interface to IQFeed’s client
application in order to retrieve market data from the IQFeed servers.
Matlab is a programming platform that is widely-used in the financial sector. Matlab
enables users to quickly analyze data, display results in graphs or interactive user
interfaces, and to develop decision-support and automated trading programs.
IQFeed does not come with an official Matlab API connector. This is the role of
IQML (www.IQML.net). IQML uses IQFeed’s API to connect Matlab with IQFeed’s
client application, providing a seamless interface within Matlab to IQFeed data. Users
can access IQFeed’s data using simple Matlab commands, without needing to know
the intricacies of the underlying API.
IQML consists of three software components (in addition to this User Guide):
1. A Java package (IQML.jar) that connects Matlab to the IQFeed client.
2. A Matlab function (IQML.p) that provides IQFeed’s data in an easy-to-use
manner, without needing to know anything about the underlying connector.
3. A Matlab file (IQML.m) that serves as a help file. This file contains no code,
just the help comment; the code itself is contained in the two other software
components. The help text is displayed when you run Matlab’s help function.
IQFeed queries (for trades and tick quotes, historical data, market info etc.) can be
initiated with simple one-line Matlab code, using the Matlab function (IQML.p).
Users can easily attach Matlab code (callbacks) to incoming IQFeed messages. This
enables users to trigger special operations (for example, adding an entry in an Excel
file, sending an email or text message, sending a trade order to an OMS application)
whenever a certain condition is detected, for example if a specified price is reached.
This document explains how to install and use IQML. Depending on the date that you
have installed IQML, your version may be missing some features discussed in this
document. You can always download the latest version of IQML from its webpage:
http://IQML.net, or directly from http://IQML.net/files/IQML.zip.
1
IQConnect.exe on Windows, IQFeed application on MacOS. or ran as a Windows app on Mac/Linux using Parallels/Wine.
Note: some MacOS users have reported problems with the “native” app (which is basically just a bottled Wine installation)
compared to a standard Wine install. This is a pure IQFeed/Mac issue, and not an IQML one; using Wine seems to solve it. In
any case, only the IQFeed client needs to run under Wine - Matlab itself can run natively.
IQML User Guide
6
2 Installation and licensing
2.1 Installing IQML
IQML requires the following in order to work:
1. An active account at DTN IQFeed
2. An installation of the IQFeed client (IQConnect)
3. An installation of Matlab R2008a or a newer release
On older Matlab releases, some IQML functionality may still be available.
Contact info@IQML.net for details.
Installing IQML is simple:
1. Read IQML’s license agreement.2 This is required even for the trial version of
IQML. If you do not accept the agreement you cannot use IQML.
2. Download http://IQML.net/files/IQML.zip to a local folder (e.g.: C:\IQML\).
3. Unzip the downloaded IQML.zip file in this local folder.
4. Add the local folder to your Matlab path using the path tool (in the Matlab
Desktop’s toolstrip, click HOME / ENVIRONMENT / Set path… and save).
The folder needs to be in your Matlab path whenever you run IQML.
5. If you are running the Production (non-trial) version of IQML, you will need
to activate your license at this point. When you purchase your license you will
be given specific instructions for this. See §2.2 below for licensing details.
6. Ensure that the IQFeed client is working and can be used to log-in to IQFeed.3
7. You can now run IQML within Matlab. To verify that IQML is properly
installed, retrieve the latest IQFeed server time, as follows (see §9.2 below):4
>> t = IQML('time');
8. You can query the installed version using IQML’s 'version' action, as follows:
>> disp(IQML('version'))
Version: 1.0
Release: '23-Feb-2018'
License: 'Professional'
Expiry: '16-Jun-2018'
9. Once the IQML product is installed, you will be notified in the Matlab console
(Command Window) whenever there is a new version available. You can
always update your installation to the latest version, as follows:
>> IQML('update')
Downloading the latest IQML version from http://IQML.net/files/IQML.zip
into C:\IQML\...
Download complete - installing...
Installation of the latest IQML version is now complete.
2
http://IQML.net/files/IQML_License_Agreement.pdf
3
IQConnect.exe on Windows, IQFeed application on MacOS. or ran as a Windows app on Mac/Linux using Parallels/Wine.
Note: some MacOS users have reported problems with the “native” app (which is basically just a bottled Wine installation)
compared to a standard Wine install. This is a pure IQFeed/Mac issue, and not an IQML one; using Wine seems to solve it. In
any case, only the IQFeed client needs to run under Wine - Matlab itself can run natively.
4
In some cases, you may need (or want) to specify the IQFeed Username,Password for the initial connection – see §9.1 below
IQML User Guide
7
2.2 Licensing and activation
IQML’s license uses an activation that is specific to the installed computer. This uses
a unique fingerprint hash-code that is reported by the Operating System, which
includes the Windows ID (on Windows systems), computer name, and the list of
hardware MAC addresses used by the computer.
Once the computer’s license is activated, the activation key is stored on the IQML.net
webserver. This activation key automatically validates online whenever IQML
connects to IQFeed (i.e., at the beginning of an IQFeed session), and once every few
hours while it is connected. Validating the license online only takes a second or two.
Since it is only done at the initial connection to the IQFeed client and once every few
hours, it does not affect IQML’s run-time performance. If you have a special concern
regarding the online activation, please contact us for clarifications.
A corollary of the computer fingerprint is that whenever you modify components that
affect the fingerprint, IQML will stop working. This could happen if you reinstall the
operating system (OS), modify the computer name, change network adapters (e.g.,
switch between wifi/cellular/wired connection, or use a new USB networking device),
modify MAC addresses, or use software that creates dynamic MACs. In such cases,
you might see an error message such as the following when you try to use IQML:
Error using IQML
IQML is not activated on this computer.
Some additional information may be presented to help you diagnose the problem.
To fix such cases, simply revert back to the original hardware/networking
configuration, and then IQML will resume working. If you wish to make the
configuration change permanent, you can contact us for an activation switch to the
new configuration (see the following section (§2.3) for details).
Computer fingerprints are typically stable, and are not supposed to change
dynamically. However, some software programs (especially on MacOS, but also
sometimes on Windows) create dynamic MAC addresses and/or dynamically modify
the computer name (hostname). This may then be reflected in the OS-reported
fingerprint, possibly causing IQML to stop working. The solution is to find a way to
keep the fingerprint components static, with the same values as the activated
fingerprint.5 You can determine the nature of the OS-reported fingerprint as follows:
>> IQML('license', 'debug',1)
Using the output from this command, you can determine which fingerprint
component was changed / added / deleted, and then take the appropriate action to fix
it so that the reported fingerprint will match the activated fingerprint. If you decide
that the fingerprint changes are permanent, contact us to change the activated
fingerprint (see §2.3 below).
5
For example, the computer’s name can be set using the OS hostname command, or the following method on Mac OS:
https://knowledge.autodesk.com/support/smoke/learn-explore/caas/sfdcarticles/sfdcarticles/Setting-the-Mac-hostname-orcomputer-name-from-the-terminal.html
IQML User Guide
8
A short time before you license term is over, you will start to see a notification
message in your Matlab console (Command Window) alerting you about this:
*** Your IQML license will expire in 3 days (10-Mar-2018).
*** To extend your license please email info@IQML.net
This informational message will only appear during the initial connection to IQFeed,
so it will not affect your regular trading session.
When the license term is over, IQML will stop working and display a corresponding
error message:
*** Your IQML license has expired on 10-Mar-2018.
*** To extend your license please email info@IQML.net
You can always renew or extend your license using the payment links on
http://IQML.net. If you wish to be independent of such annual renewals, you can
purchase a discounted multi-year license.
You can query the installed version using IQML’s 'version' action, as follows:
>> data = IQML('version')
data =
Version: 1.0
Release: '23-Feb-2018'
License: 'Professional'
Expiry: '16-Jun-2018'
Multiple IQML license options are available for purchase on http://IQML.net – longer
license terms are naturally more cost-effective than shorter ones. At the end of any
license term you can decide to renew the same term, or purchase any other term:
1, 3 or 6-months license: these short-term licenses can be repeatedly renewed,
for short-term evaluation or program development beyond the free trial.
1-year license: this is the standard, most popular license term.
Multi-year license: 2-year, 3-year or 5-year extended license terms will work
for much longer than the standard license year, as long as you keep your
hardware and software stable and IQFeed continues to provide its API service.
Volume (multi-computer) license: the same license as for a single computer,
but when you purchase multiple licenses at once, you get a volume discount.
Site license: enables to run IQML on an unlimited number of computers
within the same Windows Domain. This license does not require activation by
end-users, only a single centralized activation. It enables deploying IQML to a
cloud service, where computer hardware fingerprints often change.
Deployment (compiled or OEM) license: enables to use IQML within a
compiled program that runs on an unlimited number of computers, in any site
or domain. This license does not require any end-user activation, only a single
centralized activation of the parent executable to which the license is tied.
Source-code license: unlimited in duration, can be installed on an unlimited
number of computers within the organization, and requires no activation. This
license requires signing a dedicated NDA agreement.
IQML User Guide
9
2.3 Switching activated computers
You can switch the IQML license activation between computers or computer
hardware configurations (i.e., fingerprint hash-code) up to 3 times a year at no cost. A
handling fee will be incurred for additional re-activations, following the initial three.
In order to change the activation fingerprint, simply email us the new configuration’s
fingerprint and we will make the switch on IQML’s activation server.
Activation switches can take up to two business days to process, but typically
complete within a few hours during regular European business hours. You will
receive a confirmation email when the activation switch is complete.
2.4 Updating the installed version
Once the IQML product is installed, you will be notified in the Matlab console
(Command Window) whenever there is a new version available. An example of such
a notification is:
>> IQML(...)
% some IQML command
A newer version of IQML (1.09) is available. Updates include:
1.09 (2018-04-16)
- Added Interval Bars functionality
To display the latest online User Guide, click here.
To install the new version, click here, or run IQML('update'), or download
IQML.zip from http://IQML.net/files/IQML.zip and then unzip it in C:\IQML.
You can decide to ignore this notification and keep using your existing IQML version,
or to follow the notification’s advice and upgrade your version – the choice is yours.
You can update your installation to the latest version, at any time during your license
term, as follows:
>> IQML('update')
Downloading the latest IQML version from http://IQML.net/files/IQML.zip
into C:\IQML\...
Download complete - installing...
Installation of the latest IQML version is now complete.
Following the update, you can check the new release’s version as follows:
>> data = IQML('version')
data =
Version: 1.9
Release: '16-Apr-2018'
License: 'Professional'
Expiry: '16-Jun-2018'
After installing the latest version, if you discover that this version does not work well,
you can always revert back to the previous version by downloading and installing
http://iqml.net/files/IQML_previous.zip: simply unzip this file in your IQML folder,
then restart Matlab and run data=IQML('version') to verify the installation. If you
decide to revert your installed version for whatever reason, please email us to let us
know why, so that we could correct the issue that you found in upcoming versions.
IQML User Guide
10
3 Using IQML
3.1 General usage
IQML uses the IQFeed client6 to connect to the IQFeed server. If an active IQFeed
client is not detected, IQML will automatically attempt to start the IQFeed client and
to connect to it. Note that this may not work for some IQFeed client installations. You
can always start the IQFeed client manually, before running IQML. In any case, if an
IQFeed connection is unsuccessful, IQML will error.
IQML’s Matlab wrapper function is called IQML, contained within the IQML.p file.
Its accompanying IQML.m file provides basic usage documentation using standard
Matlab syntax, e.g.:
>> help('IQML')
>> help IQML
% equivalent alternative
>> doc IQML
The IQML function accepts a variable number of input parameters, and returns data in
a single output argument, with an optional errorMsg output. The general syntax is:
>> [data, errorMsg] = IQML(action, parameters);
where:
data
is the output value. If this output value is requested, then Matlab
processing will block data until the result is available; if the output data is not
requested then the Matlab processing will proceed immediately (nonblocking) – the IQFeed data will stream asynchronously (see below).
errorMsg is the latest error message that was reported (if any); see §3.5 below.
action is a string that denotes the requested query type (mandatory input)
parameters can be specified, depending on the requested action. There are
several ways to specify parameters, which are described below.
For example:
>> data = IQML('time'); %'time' action (blocking), 0 parameters
>> IQML('quotes', 'Symbol','IBM'); %streaming 'quotes' action, 1 parameter
>> IQML('command', 'String',command, 'PortName','Admin'); %2 parameters
Note that when an output data is requested, IQML treats the request as blocking
(synchronous), meaning that Matlab processing will wait for IQFeed’s data (or a
timeout) before proceeding with the next Matlab command. For example:
>> t = IQML('time');
% blocking until data is available
When an output data is not requested, IQML treats the request as streaming (nonblocking, a-synchronous) and Matlab processing will proceed immediately. This nonblocking mode is typically useful for sending IQFeed requests (for example, to start
streaming trades/ticks), without waiting for a response from IQFeed. The streamed
data is accumulated by IQML in the background, and can later be retrieved using the
mechanism that is discussed in §6 below. Examples of such non-blocking commands:
>> IQML('quotes', 'Symbol','IBM'); %start non-blocking IBM quotes stream
>> IQML('command', 'String',command); %asynchronous/non-blocking command
6
IQConnect.exe on Windows, IQFeed application on MacOS. or ran as a Windows app on Mac/Linux using Parallels/Wine
IQML User Guide
11
Here are the action values recognized by IQML, in the Professional and Standard
(non-pro) licenses; trial licenses have the full functionality of a Professional license:
Non- Pro &
Pro trial
'version'
Display product version information
§2.1
Yes Yes
'license'
Display the license fingerprint & activation key
§2.2
Yes Yes
'update'
Update the IQML installation to the latest version
§2.4
Yes Yes
'doc'
Display this User Guide in a separate window
Yes Yes
'quotes'
Fetch quotes/trades information on a ticker
§4.1, §6.1 Yes Yes
'fundamental' Fetch fundamental information on a ticker
§4.2
Yes Yes
'intervalbars' Fetch custom streaming interval bars on a ticker
§4.3, §6.3 Yes Yes
'marketdepth' Fetch level 2 market depth information on a ticker §4.4, §6.4 Yes
'greeks'
Greeks, fair value and implied vol. of options/futures §4.5
Yes
'history'
Fetch historical data bars from IQFeed
§5
Yes Yes
'regional'
Fetch regional update information on a ticker
§6.2
Yes
'news'
Fetch news headlines or stories from IQFeed
§7
Yes
'lookup'
Fetch list of symbols/codes matching set of criteria
§8
Yes Yes
'chain'
Fetch futures/options chain matching set of criteria
§8.2
Yes
'disconnect' Disconnect IQML from IQFeed
§9.1
Yes Yes
'reconnect'
Disconnect and then re-connect IQML to IQFeed
§9.1
Yes Yes
'time'
Retrieve the latest IQFeed server & message times
§9.2
Yes Yes
'stats'
Retrieve connection and network traffic statistics
§9.3
Yes Yes
'command'
Send a custom command to IQFeed
§9.4
Yes Yes
'alert'
Alert the users upon IQFeed streaming events
§11
Yes
Action
Description
Section
IQML accepts input parameters in several alternative formats, which are equivalent –
you can use whichever format that you prefer:
As name-value pairs – for example:
>> IQML('command', 'String',command, 'PortName','Admin'); %2 parameters
As a struct (or struct array) of parameters – for example:
>>
>>
>>
>>
params = []; %
params.String
params.PortName
IQML('command',
initialize
= command;
= 'Admin';
params);
As a table of parameters, with the parameter names as the table field names
As field-separated rows in an Excel input file – for example:
>> IQML('command', 'C:\MyData\inputFile.xlsx');
Where:
o Each column of the file contains a separate parameter
o Row #1 contains the parameter names, and rows 2+ contain their
corresponding values, one row per command
o All commands must have the same action
For example:
IQML User Guide
12
Each parameter must have an associated value. The value’s data type depends on the
specific parameter: it could be numeric, a string, a function handle etc. The definition
of all the parameters and their expected data types is listed in the appropriate section
in this User Guide that explains the usage for the associated action.
Note that if you choose to use the struct format and then to reuse this struct for
different IQML commands (by altering a few of the parameters), then the entire set of
struct parameters is used, possibly including some leftover parameters from previous
IQML commands, that may lead to unexpected results. For example:
% 1st IQML command
>> params = []; %
>> params.String
>> params.PortName
>> IQML('command',
– stop streaming timestamp messages every 1 second
initialize
= 'S,TIMESTAMPSOFF';
= 'Level1';
params);
% 2nd IQML command – stop streaming client stats messages every 1 sec
>> params.String = 'S,CLIENTSTATS OFF'; %reuse existing params struct
>> IQML('command', params);
% 3rd IQML command – start streaming quotes messages for IBM
>> params.Symbol = 'IBM'; %reuse existing params struct
>> IQML('quotes', params);
In this example, the 2nd IQML command above will have no effect, because the
PortName parameter in the params struct from the 1st IQML command will be reused
in the 2nd command, sending it to the Level1 port, instead of to the Admin port.
Similarly, the 3rd IQML command will result in an error, because the 'quotes' action
does not expect the String and PortName parameters that were carried over (reused)
from the 2nd command.
To avoid such unexpected results, I therefore advise to re-initialize the params struct
(params=[]) before preparing each IQML command.
IQML is quite tolerant of user input: parameter names (but generally not their values)
are case-insensitive, parameter order does not matter, non-numeric parameter values
can be specified as either char arrays ('abc') or strings ("abc"), and some of these can
be shortened. For example, the following commands are all equivalent:
>>
>>
>>
>>
>>
IQML('quotes',
IQML('quotes',
IQML('Quotes',
IQML('Quotes',
IQML('QUOTES',
'Symbol','IBM');
'symbol','IBM');
"Symbol","IBM");
'Symbol','IBM');
'symbol',"IBM");
The full list of acceptable input parameters, and their expected values, is listed in the
following sections, grouped by usage classification.
When using IQML, there is no need to worry about connecting or disconnecting from
the IQFeed client – IQML handles these activities automatically, without requiring
user intervention. Users only need to ensure that the IQFeed client is active and
logged-in when the IQML command is invoked in Matlab.
IQML reads data using the IQFeed account to which the IQFeed client is connected.
In other words, the IQFeed account type is transparent to IQML: the only way to
control which IQFeed data is available to IQML is to login to the IQFeed client using
the appropriate username/password. Refer to §9.1 below for additional details.
IQML User Guide
13
3.2 General properties
The following general properties can be specified in IQML, with most actions:
Parameter
Symbol or
Symbols 7
Data
type
Default
string
(none)
Description
The asset symbol, as known by IQFeed.8
Max number of seconds (0-9000) to wait for
data in a blocking request (0 means infinite).
logical false or 0 If true or 1, additional information is displayed.
Debug
One of:
2 – parse all the data in incoming IQFeed
messages (default; most verbose, slowest)
1 – do not parse lookup codes (e.g. trade
condition, price formats, market id).
The corresponding Description fields will
2
MsgParsingLevel number
either be missing, or contain empty strings.
The codes can be parsed separately (see §8).
0 – do not parse lookup code; also do not
convert string data into numeric values (i.e.
all data fields will remain strings: ‘3.14’).
This is the fastest but least verbose option.
If true or 1, IQFeed error messages raise a Matlab
RaiseErrorMsgs logical true or 1 9
error in blocking (non-streaming) mode (see §12)
function
Custom user callback function to process
[]
ProcessFunc
incoming IQFeed data messages (see §10).
handle
Timeout
number
5.0
NumOfEvents
integer
inf
The maximal number of messages to process.
Additional properties are request-specific and are listed below in the relevant
sections. For example, the 'history' action has additional properties that control the
parameters of the historic data request (start/end date, data type, etc.).
3.3 Blocking & non-blocking modes
Whenever you specify an output parameter in a call to IQML, the program will block
until a response is available (i.e., a synchronous request). If no output parameter is
specified, IQML will immediately return (non-blocking, a-synchronous) and
additional Matlab commands can immediately be issued. This non-blocking mode is
typically useful for sending IQFeed requests to start streaming data (for example,
streaming trades/ticks or news headlines), without waiting for any response from
IQFeed. The streamed data is accumulated by IQML in the background, and can later
be retrieved using the mechanism that is discussed in §6 below. For example:
>> t = IQML('time'); % blocking until data is available
>> IQML('quotes', 'Symbol','IBM'); %start non-blocking IBM quotes stream
>> IQML('command', 'String',command); %asynchronous/non-blocking command
7
In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization.
8
https://iqfeed.net/symbolguide
9
Using the 2nd (optional) output parameter of IQML implies a default value of false (0) for RaiseErrorMsgs (see §3.5 below)
IQML User Guide
14
3.4 Common causes of confusion
1. A common cause of confusion is specifying symbols incorrectly: IQFeed is
very particular about the way that symbols should be specified. If the
specified symbol is invalid, or if your account does not have the
corresponding market subscription, IQFeed will report an error:
>> IQML('quotes', 'Symbol','xyz123')
Symbol 'XYZ123' was not found!
If the request was blocking, an error (exception) will be thrown back to the
caller, which can be trapped and handled by the user, using a Matlab trycatch construct:
try
data = IQML('fundamental', 'Symbol','xyz123');
catch err
% do something intelligent here...
end
IQFeed’s website includes a detailed symbol-lookup search engine.10 If you are
still unsure about a symbol name, please contact IQFeed’s customer support.
2. Another cause of confusion is due to specifying numeric values as strings or
vice versa. For example, IQML(...,'Timeout','10') rather than
IQML(...,'Timeout',10). Each parameter expects a value of a specific data
type, which is listed in the parameter tables in this user guide. In some cases,
IQML is smart enough to automatically convert to the correct data type, but
you should not rely on this: it is better to always use the correct data type.
Otherwise, Matlab might get confused when trying to interpret the string '10'
as a number, and odd results might happen.
3. While most of IQML’s functionality is available in all license types, some
actions/functionality are only available in the Professional IQML license:
Parallelized queries (§3.6)
Customizable data fields in quotes data (§4.1, §6.1)
Level 2 market depth quotes (§4.4, §6.4, §10.5)
Option Greeks, Fair Value and Implied Volatility (§4.5)
Regional updates (§6.2)
News (§7)
Options/futures chain lookup (§8.2)
Alerts (§11)
If you have a Standard license and try to access one of the Professional-only
actions, you will receive a run-time error message:
>> data = IQML('news');
Error using IQML:
The 'news' action is not available in your Standard license of IQML,
only in the Professional license. Please contact info@iqml.net to
upgrade your license.
10
https://iqfeed.net/symbolguide
IQML User Guide
15
4. IQFeed reports dates in different formats, depending on the specific query:
either in the standard American mm/dd/yyyy format (for example:
'01/29/2018'), or in yyyymmdd format (for example: '2018-01-29' or
'20180129 12:29:48'). Dates are usually reported as strings. In some cases, a
corresponding Matlab datenum value is also reported, for example (§5.5, §6.1):
Symbol:
Timestamp:
Datenum:
...
Symbol:
LatestEventDatenum:
LatestEventTimestamp:
...
'IBM'
'2018-03-07 13:23:02.036440'
737126.557662458
'@VX#'
737128.637260451
'20180309 15:17:39'
5. By default, Matlab displays data in the console (“Command Window”) using
“short” format, which displays numbers rounded to 4 digits after the decimal.
The data actually has higher precision, so when you use it in a calculation the
full precision is used, but this is simply not displayed in the console.
IQML does not truncate/round/modify the IQFeed data in any manner!
To display the full numeric precision in the Matlab console, change your
Command Window’s Numeric Format from “short” to “long” (or “long g”) in
Matlab’s Preferences window, or use the “format long” Matlab command:
>> data = IQML('quotes', 'symbol','ONLIB.X'); %overnight LIBOR rate
>> data.Close
% short format (only 4 digits after decimal)
ans =
1.4463
>> format long g
% long format (full precision displayed)
>> data.Close
ans =
1.44625
IQML User Guide
16
3.5 Returned data format
Many queries in IQML return their data in the form of a struct-array (a Matlab array
of structs), for example (see §8.6):
>> data = IQML('lookup', 'DataType','NAICS')
data =
1175×1 struct array with fields:
id
description
>> data(1)
ans =
id: 111110
description: 'Soybean Farming'
>> data(2)
ans =
id: 111120
description: 'Oilseed (except Soybean) Farming'
For various purposes (readability, maintainability, performance, usability), users may
wish to modify this data structure. You can easily convert the data using Matlab’s
builtin functions struct2cell() (which converts the struct-array into a cell-array), or
struct2table() (which converts the struct-array into a Matlab table object):
>> disp(struct2cell(data)')
[111110]
'Soybean Farming'
[111120]
'Oilseed (except Soybean) Farming'
[111130]
'Dry Pea and Bean Farming'
[111140]
'Wheat Farming'
[111150]
'Corn Farming'
[111160]
'Rice Farming'
...
>> disp(struct2table(data))
id
description
______
___________________________________________________
111110
'Soybean Farming'
111120
'Oilseed (except Soybean) Farming'
111130
'Dry Pea and Bean Farming'
111140
'Wheat Farming'
111150
'Corn Farming'
111160
'Rice Farming'
...
Note that empty data cannot be converted using struct2table() or struct2cell():
>> data = IQML('lookup', 'DataType','NAICS', 'Description','xyz')
data =
[]
>> struct2cell(data)
Undefined function 'struct2cell' for input arguments of type 'double'.
>> struct2table(data)
Error using struct2table (line 26)
S must be a scalar structure, or a structure array with one column or one row.
A second, optional, output parameter of IQML returns the latest error message (if any):11
>> [data, errorMsg] = IQML('quotes', 'Symbol','IBM', 'Timeout',0.1)
data =
[]
errorMsg =
'IQML timeout: either IQFeed has no data for this query, or the Timeout
parameter should be set to a value larger than 0.1'
11
Using the 2nd (optional) output parameter of IQML implies a default value of false (0) for the RaiseErrorMsgs parameter.
IQML User Guide
17
3.6 Run-time performance
IQML’s standard processing has an overhead of 1-2 milliseconds per IQFeed
message, depending on several factors:
Message type/complexity – simple messages such as the periodic timestamp
updates are simpler to process than complex messages (e.g. fundamental data).
The Debug parameter (see §3.2) – A value of 1/true is ~1 msec slower per
message, compared to the default value of 0/false (depending on message type).
The MsgParsingLevel parameter (§3.2) – A value of 0 is ~1 msec faster per
message, compared to the default value of 2 (depending on message type).
The UseParallel parameter (see below) enables query parallelization (faster).
The Fields parameter in quotes queries (§4.1, §6.1) – fewer fields are faster.
User-defined callbacks (§10) add their own processing time per message.
Each active alert (§11) uses 1-2 msecs per message (depending on alert type, and
only for the alert’s corresponding message type). If the alert action is
triggered, then its processing time is added. For example, displaying a popup
message might take 1 sec, and sending an email might take a few seconds.
Computer capabilities – faster CPU and memory (RAM) enable faster
processing, if your computer has enough physical memory to avoid swapping.
Adding memory is typically much more cost-effective than upgrading the CPU.
This means that without any defined alert or user-specified callback, nor any other
code running in the background (for example, a Matlab data analysis program), we
can expect IQML to process up to 500-1000 IQFeed messages per second by default.
This is a relatively fast throughput, but if you stream real-time quotes for hundreds of
liquid securities concurrently then you might reach this limit. When this happens,
Matlab may be so bogged-down from the flood of incoming messages that it will
become unresponsive, and you may need to restart IQConnect and/or Matlab.
Similarly, if you request a blocking (non-streaming) request with multiple data items
(for example, thousands of historical data or news items), the query may take a while
to process, requiring us to set a higher-than-default Timeout parameter value. For
example, if you issue a blocking request for 20K data bars, IQFeed will send 20K
data messages (one message per bar). If each of these messages takes 1-2 msecs to
process, the total processing time for the IQML query will be 20-40 secs.
When IQFeed is connected, it continuously sends messages to IQML: periodic
“heartbeat” and status messages, and messages for any active streaming quotes or news
events that you requested. These messages are automatically processed by IQML in the
background, reducing the CPU time that is left available to process other IQML queries
(e.g., a blocking historical data query) or Matlab analysis functions. It is therefore
advisable to stop streaming IQFeed data when not needed, even if only temporarily.
IQML User Guide
18
In the Professional IQML license, you can use Matlab’s Parallel Computing Toolbox to
parallelize IQFeed queries. This can be done both externally (placing IQML commands
in parfor/spmd blocks, so that they will run independently), and internally in some IQML
query types (using the UseParallel parameter). If you have the Standard IQML license,
or if you do not have Matlab’s Parallel Computing Toolbox, you can still run
concurrent IQML commands in separate Matlab sessions, just not in the same session.
IQML automatically tries to parallelize queries when the UseParallel parameter value
(default: false) is set to 1 or true. The list of parallelizable queries includes:
Requests resulting in multiple blocking queries in a single IQML command
(for example, historical data for multiple symbols or a date range – see §5)
Requests for full news-story of all returned news headlines in a blocking query,
using the GetStory parameter (see §7.2)
Requests for fundamental/quotes data on all symbols in an options-chain or
futures-chain, using the WhatToShow parameter (see §8.2)
When setting UseParallel to 1 or true, IQML will use parallel Matlab tasks (so-called
‘headless workers’ or ‘labs’) from the currently-active parallel pool created by the Parallel
Computing Toolbox. If no pool is active, the default local pool is automatically started.
IQML parallelization has several performance implications:
Starting the parallel pool can take some time (a few seconds, up to a minute or
two, depending on configuration). It is therefore best to start the parallel pool
before time-critical operations, to avoid this startup time upon the first parallel
query. Starting the pool can be done using Matlab’s parpool function.
The default pool uses the same number of workers as the number of physical
cores on your computer. This makes sense for CPU-intensive programs, but
IQML queries are limited by I/O, not CPU. Therefore, unless you also use the
parallel pool for CPU-intensive computations in your program, it makes sense
to start a pool that has more workers than the number of CPU cores. You can
configure your local cluster for this.12 Note that the parallel pool size should
be set to ≤14, since IQFeed limits the number of concurrent connections.13
In addition to the workers startup time, each worker independently connects to
IQFeed upon the first IQML command it encounters, taking an extra few secs.
It is only possible to parallelize workers on the local computer, not on other
(distributed) computers in a grid/cluster/cloud. This is due to IQFeed/exchange
limitations, which prohibit distribution of data to other computers.
Due to parallelization overheads, inter-task memory transfers, and CPU taskswitches (especially in a case of more workers than cores), speedup will always
be smaller than the number of workers. The actual speedup will depend on query
type and computer/OS configuration. Parallelization may even cause slowdown
in some cases (e.g. quote queries, due to waiting for market events, not CPU).
12
https://www.mathworks.com/help/distcomp/discover-clusters-and-use-cluster-profiles.html#f5-16540
13
IQFeed’s actual limit is 15, but one connection is used by the main (non-parallel) Matlab process, in addition to the workers.
IQML User Guide
19
Here is a run-time example showing the effect of using a 4-worker pool to parallelize
a news-story query, resulting in a 3.5x speedup (not 4x, due to parallelization overheads):
>> tic, data = IQML('news', 'DataType','headlines', 'MaxItems',100, ...
'GetStory',1); toc
Elapsed time is 56.311768 seconds.
>> parpool('local',4) % start 4 workers in parallel pool (optional)
>> tic, data = IQML('news', 'DataType','headlines', 'MaxItems',100, ...
'GetStory',1, 'UseParallel',1); toc
Elapsed time is 15.799185 seconds.
Also in the Professional IQML license, you can customize the fields reported by
IQFeed for market data. The Fields parameter can be set to a cell-array of strings
({'Bid','Ask','Last'}), or a comma-separated string ('Bid,Ask,Last'). All subsequent
quotes queries, either for the latest snapshot (§4.1) or for streaming quotes (§6.1), will
report just the requested fields. For example:
>> data = IQML('quotes', 'Symbol','AAPL', 'Fields',{'Bid','Ask','Last'})
>> data = IQML('quotes', 'Symbol','AAPL', 'Fields','Bid,Ask,Last') %equivalent
data =
Symbol: 'AAPL'
Bid: 222.71
Ask: 222.91
Last: 222.11
Note: the more fields that you request, the longer the required processing time, by both
IQFeed and IQML. By default, IQFeed reports 16 data fields, but ~50 additional
fields can be requested. Requesting fewer fields (as in the example above, which only
requests 3 fields) implies faster run-time processing. To improve run-time
performance and reduce latency, request only those data fields that are actually
required by your program.
IQML User Guide
20
4 Querying the latest market data
4.1 Snapshot (top of book) quotes
We start with a simple example to retrieve the latest market information for Alphabet
Inc. Class C, which trades using the GOOG symbol, using IQML’s 'quotes' action:
>> data = IQML('quotes', 'Symbol','GOOG')
data =
Symbol: 'GOOG'
Most_Recent_Trade: 1092.14
Most_Recent_Trade_Size: 1
Most_Recent_Trade_Time: '09:46:31.960276'
Most_Recent_Trade_Market_Center: 25
Total_Volume: 113677
Bid: 1092.13
Bid_Size: 100
Ask: 1092.99
Ask_Size: 100
Open: 1099.22
High: 1099.22
Low: 1092.38
Close: 1090.93
Message_Contents: 'Cbaohlc'
Message_Description: 'Last qualified trade; A bid update
occurred, An ask update occurred; An open
declaration occurred; A high declaration
occurred; A low declaration occurred; A
close declaration occurred'
Most_Recent_Trade_Conditions: '3D87'
Trade_Conditions_Description: 'Intramaket Sweep; Odd lot trade'
Most_Recent_Market_Name: 'Direct Edge A (EDGA)'
As can be seen, the returned data object is a Matlab struct with self-explanatory fields.14
To access any specific field, use the standard Matlab dot-notation:
>> bidPrice = data.Bid;
%=1092.13 in this specific case
If the symbol is not currently trading, some fields return empty values:
>> data = IQML('quotes', 'Symbol','GOOG')
data =
Symbol: 'GOOG'
Most_Recent_Trade: 1078.99
Most_Recent_Trade_Size: 1
Most_Recent_Trade_Time: '19:58:47.052099'
Most_Recent_Trade_Market_Center: 26
Total_Volume: 0
Bid: 1077.6
Bid_Size: 100
Ask: 1079.89
Ask_Size: 200
Open: []
High: []
Low: []
Close: 1078.92
Message_Contents: 'Cbav'
Message_Description: 'Last qualified trade; A bid update
occurred; An ask update occurred;
A volume update occurred'
Most_Recent_Trade_Conditions: '0517'
Trade_Conditions_Description: 'Average Price Trade; Form-T Trade'
Most_Recent_Market_Name: 'Direct Edge X (EDGX)'
14
The textual Description fields depend on the MsgParsingLevel parameter having a value of 2 or higher (see §3.2 and §8)
IQML User Guide
21
In this example, the query was sent outside regular trading hours (on Sunday) so Open,
High and Low are empty. As expected, the data indicates this was a “Form-T” trade.
Other fields may sometimes be empty. For example, overnight LIBOR rate (Symbol=
'ONLIB.X') reports empty Bid, Ask, Most_Recent_Trade_Size (and Total_Volume=0).
In rare cases, you might see invalid field values (e.g. 0), which may indicate a data
error. IQML does not modify the data reported by IQFeed, so if you see this problem
consistently for a certain security or exchange, please contact IQFeed’s support.
If you specify an incorrect security name or classification properties, or if you do not
have the necessary market subscription, then no data is returned, and an error
message is displayed (see discussion in §3.4).
>> IQML('quotes', 'Symbol','xyz123')
Symbol 'XYZ123' was not found!
You may request more than a single snapshot quote: To get the next N real-time
quotes, specify the NumOfEvents parameter. The result is an array of structs in the
same format as above (or an empty array if no data is available):15
>> data = IQML('quotes', 'Symbol','IBM', 'NumOfEvents',4)
data =
4×1 struct array with fields:
Symbol
Most_Recent_Trade
Most_Recent_Trade_Size
...
>> data(1)
ans =
Symbol:
Most_Recent_Trade:
Most_Recent_Trade_Size:
Most_Recent_Trade_Time:
Most_Recent_Trade_Market_Center:
Total_Volume:
...
'IBM'
159.16
75
'09:36:15.534201'
24
135267
Note that it is possible that not all the requested quotes will be received before
IQML’s timeout (default value: 5 secs) returns the results:
>> data = IQML('quotes', 'Symbol','IBM', 'NumOfEvents',4)
Warning: IQML timeout: only partial data is returned: the Timeout parameter
should be set to a value larger than 5
data =
2×1 struct array with fields:
Symbol
Most_Recent_Trade
Most_Recent_Trade_Size
...
To control the maximal duration that IQML will wait for the data, set the Timeout
parameter. For example, to wait up to 60 secs to collect the next 4 upcoming quotes:
>> data = IQML('quotes', 'Symbol','IBM', 'NumOfEvents',4, 'timeout',60);
15
Some older versions of IQML returned a different form struct (the same as that reported by streaming quotes - §6.1). This was
corrected to match the documentation starting in IQML version 2.00.
IQML User Guide
22
You can request quotes for multiple symbols at the same time, in a single IQML
command, by specifying a colon-delimited or cell-array list of symbols. For example:
>> data = IQML('quotes', 'symbols',{'IBM','GOOG','AAPL'});
>> data = IQML('quotes', 'symbols','IBM:GOOG:AAPL');
% equivalent
The result will be an array of Matlab structs that correspond to the requested symbols:
data =
1×3 struct array with fields:
Symbol
Most_Recent_Trade
Most_Recent_Trade_Size
Most_Recent_Trade_Time
Most_Recent_Trade_Market_Center
Total_Volume
Bid
...
>> data(2)
ans =
struct with fields:
Symbol:
Most_Recent_Trade:
Most_Recent_Trade_Size:
Most_Recent_Trade_Time:
Most_Recent_Trade_Market_Center:
Total_Volume:
Bid:
Bid_Size:
Ask:
Ask_Size:
Open:
High:
Low:
Close:
Message_Contents:
Message_Description:
'GOOG'
1078.99
1
'19:58:47.052099'
26
0
1077.6
100
1079.89
200
[]
[]
[]
1078.92
'Cbav'
'Last qualified trade; A bid update
occurred; An ask update occurred;
A volume update occurred'
Most_Recent_Trade_Conditions: '0517'
Trade_Conditions_Description: 'Average Price Trade; Form-T Trade'
Most_Recent_Market_Name: 'Direct Edge X (EDGX)'
If you have the Professional license of IQML and also Matlab’s Parallel Computing
Toolbox, then setting the UseParallel parameter to true (or 1) will process the quotes
query for all the specified symbols in parallel (see discussion in §3.6). Note that in the
case of quote queries, there is often little or no speedup in parallelization, because the
delay is caused by waiting for market quote events, not due to CPU processing:
>> data = IQML('quotes', 'symbols',{'IBM','GOOG','AAPL'}, 'UseParallel',true);
Note that if you request quotes for a very large number of symbols in a single IQML
command, and especially if you set UseParallel to true, you might run into your IQFeed
account’s symbols-limit (MaxSymbols; see §9.3). In such a case, IQFeed-generated
error messages such as the following will be displayed on the Matlab console:
Warning: Requesting 3258 symbol quotes, which is more than your IQFeed account's
concurrent symbols limit (500) - quotes for some symbols may not be available.
(Type "warning off IQML:MaxSymbols" to suppress this warning.)
Level1 symbol limit reached - symbol 'IBM' not serviced!
IQML User Guide
23
By default, IQFeed reports 16 data fields for each quote: Symbol, Most Recent Trade,
Most Recent Trade Size, Most Recent Trade Time, Most Recent Trade Market
Center, Total Volume, Bid, Bid Size, Ask, Ask Size, Open, High, Low, Close,
Message Contents, and Most Recent Trade Conditions.16
If the Fields parameter is set to an empty value ({} or ''), the current set of fields and the
full list of available fields, are reported (in this case, a Symbol parameter is unnecessary):
>> data = IQML('quotes', 'fields',{})
data =
CurrentFields: {1×16 cell}
AvailableFields: {1×68 cell}
>> data.AvailableFields
ans =
1×68 cell array
Columns 1 through 5
{'Symbol'} {'Exchange ID'} {'Last'} {'Change'} {'Percent Change'}
Columns 6 through 11
{'Total Volume'} {'High'} {'Low'} {'Bid'} {'Ask'} {'Bid Size'}
Columns 12 through 17
{'Ask Size'} {'Tick'} {'Range'} {'Open Interest'} {'Open'} {'Close'}
Columns 18 through 22
{'Spread'} {'Settle'} {'Delay'} {'Restricted Code'} {'Net Asset Value'}
...
If you have the Professional (or trial) IQML license, you can request IQFeed to report
more than 50 additional data fields, as well as to set the reported fields order, using
the optional Fields parameter, as follows:
We can set Fields to 'All' (or 'all') to request all available data fields in reported quotes:17
>> data = IQML('quotes', 'Symbol','AAPL', 'Fields','all')
data =
Symbol: 'AAPL'
x7_Day_Yield: []
Ask: 222.91
Ask_Change: []
Ask_Market_Center: 28
Ask_Size: 100
Ask_Time: '19:59:42.031900'
Available_Regions: []
Average_Maturity: []
Bid: 222.71
...
The field names in the reported Matlab struct are the same as the IQField field names,
except that spaces are replaced by ‘_’ and an ‘x’ is prefixed to fields that start with a
number, in order to create valid Matlab field identifiers (e.g., '7 Day Yield' is
converted into 'x7_Day_Yield').
A complete table of available fields is provided for convenience at the bottom of this
section. If you are uncertain about the meaning of a certain field, or wish to know
16
The additional textual fields Message_Description, Trade_Conditions_Description and Most_Recent_Market_Name are
IQML-generated textual interpretations of the codes in the IQFeed-generated Message_Contents, Trade_Conditions and
Most_Recent_Trade_Market_Center fields, respectively, as governed by the MsgParsingLevel parameter (§3.2).
17
Additional description fields will be generated by IQML for those fields that report value codes (for example, the Fraction
Display Code and Financial Status Indicator fields), as governed by the MsgParsingLevel parameter (§3.2).
IQML User Guide
24
which field reports certain data, please ask your DTN IQFeed representative (after all,
IQML just reports the data as provided by IQFeed).
Some of the reported field values may be empty. For example, AAPL’s
Average_Maturity value is empty since this field is only valid for bonds. Similarly,
EURUSD.FXCM’s Market_Capitalization value is empty because Forex securities
have no market cap. Likewise, Net_Asset_Value is only valid for funds. Delay=[]
indicates a real-time quote, whereas Delay=15 indicates that the quote was delayed 15
minutes by the exchange (presumably because you do not possess a real-time data
subscription for this exchange/security-type).
The Fields parameter can be set to any subset of AvailableFields,18 as either a cellarray of strings, or as a comma-separated string. In this case, any subsequent quotes
query will report the requested fields, in the specified order. For example:
>> data = IQML('quotes', 'Symbol','AAPL', 'Fields',{'Bid','Ask','Last'})
>> data = IQML('quotes', 'Symbol','AAPL', 'Fields','Bid,Ask,Last') %equivalent
data =
Symbol: 'AAPL'
Bid: 222.71
Ask: 222.91
Last: 222.11
The order of the specified Fields indicates the order in which the data fields will be
reported. For example, to change the order of the reported data fields above:
>> data = IQML('quotes', 'Symbol','AAPL', 'Fields','Last,Ask,Bid')
data =
Symbol: 'AAPL'
Last: 222.11
Ask: 222.91
Bid: 222.71
Note that the Symbol field is always reported in the first position, regardless of whether
or not it was specified in the Fields list, or of its specified position order in the Fields
list (also note the optional spaces between the comma-separated field names):
>> data = IQML('quotes', 'Symbol','AAPL', 'Fields','Bid, Ask, Last, Symbol')
data =
Symbol: 'AAPL'
Bid: 222.71
Ask: 222.91
Last: 222.11
As noted, Fields can be set to any subset of the AvailableFields. If a bad field is
specified (one which is not available in IQFeed), an error message will be displayed:
>> data = IQML('quotes', 'Symbol','AAPL', 'Fields','Bid, Ask, xyz')
Error using IQML
Bad field 'xyz' was requested in IQML quotes command (check the
capitalization/spelling).
Available fields are: 7 Day Yield, Ask, Ask Change, Ask Market Center, ...
Note: the more fields that you request, the longer the required processing time, by both
IQFeed and IQML. To improve run-time performance and reduce latency, request
only those data fields that are actually needed by your program.
18
AvailableFields is reported by an IQML('quotes','fields',{}) command – see the previous page in this User Guide.
IQML User Guide
25
The following parameters affect quotes data queries:
Parameter Data type
Default
colonSymbol or
Symbols 19
delimited
string, or
cell-array
of strings
NumEvents integer
Timeout
UseParallel
number
logical
(true/false)
(none)
Description
Limits the query to the specified symbol(s).
Examples:
'@VX#'
'IBM:AAPL:GOOG'
{'IBM', 'AAPL', 'GOOG'}
This parameter must be set to valid symbol
name(s). Multiple symbols can be parallelized
using the UseParallel parameter (see below).
1
Returns up to the specified number of quotes
5.0
Max number of seconds to wait for incoming
data (0-9000, where 0 means infinite)
false
If set to true or 1, and if Parallel Computing
Toolbox is installed, then querying multiple
symbols will be done in parallel (see §3.6;
Professional IQML license only).
Sets the list of data fields reported by IQFeed
for each quote. IQFeed’s default set has 16
'Symbol, Most fields; 50+ additional fields can be specified
Recent Trade, (a detailed list of fields is provided below).
Most Recent Trade If Fields is set to an empty value ({} or ''),
Size, Most Recent
the list of current, available fields is returned.
Trade Time, Most
Fields
commaseparated Recent Trade If Fields is not empty, subsequent quotes
Market Center,
string, or Total Volume, Bid, queries will return the specified fields, in
cell-array Bid Size, Ask, Ask the specified order (Professional IQML
of strings Size, Open, High, license only). The Symbol field is always
returned first, even if not specified.
Low, Close,
Message Contents, Examples:
Most Recent Trade
{'Bid', 'Ask', 'Last'}
Conditions'
'Bid, Ask, Last'
'All' (indicates all available fields)
The full list of available fields in IQFeed is listed below. Note that some of these
fields may not be available, and IQFeed may also add/modify this list at any time.
The list of fields that are actually available cen be retrieved in IQML using the
IQML('quotes','fields',{}) command, as explained above. For details about any of
these fields, please contact your DTN/IQFeed representative (IQML just reports the
data, it has no control over the reported values or definition of the data fields).
19
In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization
IQML User Guide
Field Name
Field Type
Description
26
Data origin 20
1 7 Day Yield
float
Value of a Money Market fund over past 7 days.
Exchange/other
2 Ask
float
Min price a market maker/broker accepts for a security. Exchange/other
3 Ask Change
float
Change in Ask since last offer.
IQConnect
4 Ask Market Center integer
Market Center that sent the ask information (see §8.3). Exchange/other
5 Ask Size
integer
The share size available for the ask price
6 Ask Time
hh:mm:ss.ffffff The time of the last ask.
Exchange/other
Exchange/other
7 Available Regions string
Dash-delimited list of available regional exchanges.
IQConnect
8 Average Maturity
float
Average number of days until maturity of a Money
Market Fund’s assets.
Exchange/other
9 Bid
float
Max price a market maker/broker will pay for a security. Exchange/other
10 Bid Change
float
Change in Bid since last offer.
IQConnect
11 Bid Market Center integer
Market Center that sent the bid information (see §8.3). Exchange/other
12 Bid Size
integer
The share size available for the bid price.
13 Bid Time
hh:mm:ss.ffffff The time of the last bid.
Exchange/other
14 Change
float
Today's change (Last - Close)
IQConnect
15 Change From Open float
Change in last price since last open.
IQConnect
16 Close
float
The closing price of the day. For commodities this will Exchange/other
be the last trade price of the session.
17 Close Range 1
float
For commodities only. Range value for closing trades
that aren’t reported individually.
Exchange/other
18 Close Range 2
float
For commodities only. Range value for closing trades
that aren’t reported individually.
Exchange/other
19 Days to Expiration string
Number of days to contract expiration.
IQConnect
20 Decimal Precision string
Last Precision used.
DTN
21 Delay
integer
The number of minutes a quote is delayed when not
authorized for real-time data.
Exchange/other
22 Exchange ID
hexidecimal
The Exchange Group ID.
DTN
23 Extended Trade
float
Price of the most recent extended trade (last qualified
trades + Form T trades).
Exchange/other
24 Extended Trade
Date
MM/DD/CCYY Date of the extended trade.
Exchange/other
25 Extended Trade
Market Center
integer
Market Center of the most recent extended trade (last
qualified trades + Form T trades); see §8.3.
Exchange/other
26 Extended Trade
Size
integer
Size of the most recent extended trade (last qualified
trades + Form T trades).
Exchange/other
27 Extended Trade
Time
hh:mm:ss.ffffff Time (including microseconds) of the most recent
extended trade (last qualified trades + Form T trades).
Exchange/other
28 Extended Trading
Change
float
Extended Trade minus Yesterday's close.
IQConnect
29 Extended Trading
Difference
float
Extended Trade minus Last.
IQConnect
30 Financial Status
Indicator
char
Denotes if an issuer has failed to submit its regulatory Exchange/other
filings on a timely basis, has failed to meet the
exchange's continuing listing standards and/or filed for
bankruptcy. A corresponding description field will be
generated by IQML for this field when
MsgParsingLevel ≥ 2 (see §3.2)
20
Exchange/other
In this table, “exchange/other” means either the exchange, or some other 3rd-party that provides data to DTN/IQFeed.
IQML User Guide
Field Name
Field Type
Description
27
Data origin 20
31 Fraction Display
Code
string
Display formatting code. A corresponding description
field will be generated by IQML for this field when
MsgParsingLevel ≥ 2 (see §3.2)
DTN
32 High
float
Today's highest trade price.
Exchange/other
33 Last
float
Last trade price from the regular trading session.
Exchange/other
34 Last Date
MM/DD/CCYY Date of the last qualified trade.
Exchange/other
35 Last Market Center integer
Market Center of most recent last qualified trade.
Exchange/other
36 Last Size
integer
Size of the most recent last qualified trade.
Exchange/other
37 Last Time
hh:mm:ss.ffffff Time (including microseconds) of the most recent last
qualified trade.
Exchange/other
38 Last Trade Date
MM/DD/YYYY Date of last trade.
Exchange/other
39 Low
float
Today's lowest trade price.
Exchange/other
40 Market
Capitalization
float
Real-time calculated market cap (Last price * Common IQConnect
Shares Outstanding).
41 Market Open
integer
1 = market open, 0 = market closed.
Note: valid for Futures and Future Options only.
DTN
42 Message Contents non-delimited
string of single
character
message
identification
codes
Possible single character values include:
IQConnect
C - Last Qualified Trade.
E - Extended Trade = Form T trade.
O - Other Trade = Any trade not
accounted for by C or E.
b - A bid update occurred.
a - An ask update occurred.
o - An Open occurred.
h - A High occurred.
l - A Low occurred.
c - A Close occurred.
s - A Settlement occurred.
v - A volume update occurred.
Notes: you can get multiple codes in a single message
but you will only get one trade identifier per message.
It is also possible to receive no codes in a message if
the fields that updated were not trade or quote related.
A corresponding description field is generated by IQML
for this field when MsgParsingLevel ≥ 2 (see §3.2)
43 Most Recent Trade float
Price of most recent trade (inc. non-last-qualified trades). Exchange/other
44 Most Recent Trade string of 2digit
Conditions
hex numbers.
Conditions that identify the type of most recent trade. A Exchange/other
corresponding description field is generated by IQML for
this field when MsgParsingLevel ≥ 2 (see §3.2, §8.7)
45 Most Recent Trade MM/DD/CCYY Date of most recent trade.
Date
Exchange/other
46 Most Recent Trade integer
Market Center
Market Center of most recent trade. A corresponding
description field will be generated by IQML for this
field when MsgParsingLevel ≥ 2 (see §3.2, §8.3)
Exchange/other
47 Most Recent Trade integer
Size
Size of most recent trade.
Exchange/other
48 Most Recent Trade hh:mm:ss.ffffff Time (including microseconds) of most recent trade.
Time
49 Net Asset Value
float
50 Number of Trades integer
Today
Exchange/other
The market value of a mutual fund share. Equal to net Exchange/other
assets / total number of shares outstanding. Duplicates
the Bid field. Valid for Mutual Funds only.
The number of trades for the current day.
IQConnect/DTN
IQML User Guide
Field Name
Field Type
Description
28
Data origin 20
51 Open
float
The opening price of the day. For commodities this will Exchange/other
be the first trade of the session.
52 Open Interest
integer
IEOptions, Futures, FutureOptions, SSFutures only.
53 Open Range 1
float
For commodities only. Range value for opening trades Exchange/other
that aren’t reported individually.
54 Open Range 2
float
For commodities only. Range value for opening trades Exchange/other
that aren’t reported individually.
55 Percent Change
float
= Change / Close
IQConnect
56 Percent Off
Average Volume
float
Current Total Volume / Average Volume
IQConnect
57 Previous Day
Volume
integer
Previous Day's Volume.
Exchange/other
58 Price-Earnings
Ratio
float
Real-time calculated PE (Last / Earnings Per Share).
IQConnect
59 Range
float
Trading range for the current day (high - low)
IQConnect
60 Restricted Code
string
"N"=Short Sale is not restricted, "R"=Restricted.
Exchange/other
61 Settle
float
Settle price (Futures or FutureOptions only).
Exchange/other
62 Settlement Date
MM/DD/YYYY The date that the Settle field is valid for.
Exchange/other
63 Spread
float
The difference between Bid and Ask prices.
IQConnect
64 Symbol
string
The symbol name of the security
IQConnect
65 Tick
integer
173=Up, 175=Down, 183=No Change. Based on the
previous trade. Only valid for Last qualified trades.
IQConnect
66 TickID
integer
Identifier for tick (not necessarily sequential).
DTN
67 Total Volume
integer
Today's cumulative volume in number of shares.
IQConnect, DTN
or exchange
68 Type
string
“Q”=Update message, “P”=Summary Message.
IQConnect
69 Volatility
float
Real-time calculated volatility: (High - Low) / Last.
IQConnect
70 VWAP
float
Volume Weighted Average Price.
IQConnect/DTN
Exchange/other
IQML User Guide
29
4.2 Fundamental information
Fundamental data on a symbol can be fetched using a 'fundamental' action, as follows:
>> data = IQML('fundamental', 'symbols','IBM')
data =
Symbol: 'IBM'
Exchange_ID: 7
PE: 25.7
Average_Volume: 4588000
x52_Week_High: 180.95
x52_Week_Low: 139.13
Calendar_Year_High: 171.13
Calendar_Year_Low: 144.395
Dividend_Yield: 3.79
Dividend_Amount: 1.5
Dividend_Rate: 6
Pay_Date: '03/10/2018'
Ex_dividend_Date: '02/08/2018'
Short_Interest: 17484332
Current_Year_EPS: 6.17
Next_Year_EPS: []
Five_year_Growth_Percentage: -0.16
Fiscal_Year_End: 12
Company_Name: 'INTERNATIONAL BUSINESS MACHINE'
Root_Option_Symbol: 'IBM'
Percent_Held_By_Institutions: 59.9
Beta: 1.05
Leaps: []
Current_Assets: 49735
Current_Liabilities: 37363
Balance_Sheet_Date: '12/31/2017'
Long_term_Debt: 39837
Common_Shares_Outstanding: 921168
Split_Factor_1: '0.50 05/27/1999'
Split_Factor_2: '0.50 05/28/1997'
Market_Center: []
Format_Code: 14
Precision: 4
SIC: 7373
Historical_Volatility: 25.79
Security_Type: 1
Listed_Market: 7
x52_Week_High_Date: '03/08/2017'
x52_Week_Low_Date: '08/21/2017'
Calendar_Year_High_Date: '01/18/2018'
Calendar_Year_Low_Date: '02/09/2018'
Year_End_Close: 153.42
Maturity_Date: []
Coupon_Rate: []
Expiration_Date: []
Strike_Price: []
NAICS: 541512
Exchange_Root: []
Option_Premium_Multiplier: []
Option_Multiple_Deliverable: []
Price_Format_Description: 'Four decimal places'
Exchange_Description: 'New York Stock Exchange (NYSE)'
Security_Type_Description: 'Equity'
SIC_Description: 'COMPUTER INTEGRATED SYSTEMS DESIGN'
NAICS_Description: 'Computer Systems Design Services'
Note that the naming, interpretation and order of returned data fields is controlled by
IQFeed, not IQML – DTN might change these fields in the future.
IQML User Guide
30
Also note that the inclusion of the *_Description fields (Price_Format_Description,
Exchange_Description, etc.) depends on the MsgParsingLevel parameter having
value of 2 or higher (see §3.2 for details). When MsgParsingLevel is 1 or 0, these
fields will not be part of the returned data struct.
It is possible to fetch fundamental data of multiple symbols in a single IQML
command, by specifying a colon-delimited or cell-array list of symbols:
>> data = IQML('fundamental', 'symbols','AAPL:GOOG')
data =
1×2 struct array with fields:
Symbol
Exchange_ID
PE
Average_Volume
...
>> data(1)
ans =
Symbol:
Exchange_ID:
PE:
Average_Volume:
x52_Week_High:
x52_Week_Low:
Calendar_Year_High:
Calendar_Year_Low:
...
'AAPL'
5
20.4
26900000
228.87
149.16
228.87
150.24
Symbol:
Exchange_ID:
PE:
Average_Volume:
x52_Week_High:
x52_Week_Low:
Calendar_Year_High:
Calendar_Year_Low:
...
'GOOG'
5
51.9
1239000
1273.89
909.7
1273.89
980.64
>> data(2)
ans =
%or: {'AAPL','GOOG'}
IQML User Guide
31
4.3 Interval bars
Interval bars data for one or more symbols can be fetched using the 'intervalbars' action.
For example, to fetch the latest 60-second interval bar for the current E-Mini contract:
>> data = IQML('intervalbars', 'Symbol','@ES#')
data =
Symbol: '@ES#'
BarType: 'Complete interval bar from history'
Timestamp: '2018-09-05 12:57:00'
Open: 2887.75
High: 2888.25
Low: 2887.5
Close: 2888.25
CummlativeVolume: 1117565
IntervalVolume: 913
NumberOfTrades: 0
In the returned data struct, we can see the following fields:
Symbol – the requested Symbol.
BarType – typically ‘Complete interval bar from history’, but in some cases
might be ‘Complete interval bar from stream’ or ‘Updated interval bar’.
Timestamp
Open
Low
CummlativeVolume
NumberOfTrades
– server timestamp (string format) for this interval bar. The
timestamp is of the end of the bar, not the beginning.
– price at the start of this interval bar.
High – highest price during this interval bar.
– lowest price during this interval bar.
Close – price at the end of this interval bar.
– total trade volume since start of the current trading day.
IntervalVolume – trade volume during this interval bar.
– number of trades during this interval bar. Relevant only
when IntervalType is set to '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).21
We can ask for multiple bars by setting NumOfEvents or MaxItems to a positive integer,
resulting in an array of structs in the format above (empty array if no data is available):
>> data = IQML('intervalbars', 'Symbol','@VX#', 'NumOfEvents',4)
data =
4×1 struct array with fields:
Symbol
BarType
...
21
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
IQML User Guide
32
>> data(1)
ans =
Symbol:
BarType:
Timestamp:
Open:
High:
Low:
Close:
CummlativeVolume:
IntervalVolume:
NumberOfTrades:
'@VX#'
'Complete interval bar from history'
'2018-09-05 12:36:00'
14.45
14.5
14.45
14.45
57077
17
0
IQFeed only returns interval bars that had market ‘action’. Other bars are not sent
from IQFeed – they will appear in IQML’s returned data as gaps in the Timestamp.
Also note that it is possible that not all the requested bars will be received before
IQML’s timeout (default value: 5 secs) returns the results:
>> data = IQML('intervalbars', 'Symbol','IBM', 'NumOfEvents',4)
Warning: IQML timeout: only partial data is returned: the Timeout parameter
should be set to a value larger than 5
data =
2×1 struct array with fields:
Symbol
BarType
...
To control the maximal duration that IQML will wait for the data, set the Timeout
parameter. For example, to wait up to 60 secs to collect 4 bars:
>> data = IQML('intervalbars', 'Symbol','IBM', 'NumOfEvents',4, 'timeout',60);
Interval bars query fetches 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
(live) 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.
Unlike quotes (§4.1), when you specify NumOfEvents > 1, IQML does not wait for
new bars to arrive; instead, it returns previous (historic) bars, as long as this does not
conflict with the specified BeginDateTime. For example, if you set NumOfEvents=5,
you will receive the latest 5 bars: 4 complete historic bars, as well as the current
(incomplete) bar. If you require live (future) interval bars, then set BeginDateTime,
or use the streaming mechanism that is described in §6.3. For example, if you set
BeginDateTime to 5 bars ago and NumOfEvents=15, then IQFeed will return the 5
historic bars and wait for 10 additional future bars (subject to the specified Timeout).
Additional data filtering parameters: MaxDays, BeginFilterTime and EndFilterTime.
You can query multiple symbols at the same time, in a single IQML command, by
specifying a colon-delimited or cell-array list of symbols. For example:
>> data = IQML('intervalbars', 'symbols',{'IBM','GOOG','AAPL'});
>> data = IQML('intervalbars', 'symbols','IBM:GOOG:AAPL'); % equivalent
IQML User Guide
33
The following parameters affect interval bars data queries:
Parameter Data type
Default
Description
Limits the request to the specified
symbol(s). Examples:
colon '@VX#'
delimited
Symbol or
'IBM:AAPL:GOOG'
string or
(none)
Symbols 22
cell-array
{'IBM', 'AAPL', 'GOOG'}
of strings
This parameter must be set to valid
symbol name(s) when NumOfEvents>0
One of:
inf – continuous endless streaming
interval bars for specified symbol(s)
N>1 – stream only N interval bars
integer
Inf
NumOfEvents
1 – get only a single interval bar
0 – stop streaming interval bars
-1 – return latest interval bars data
while continuing to stream new bars
Returns up to the specified number of
integer
100
MaxItems
bars (if available).
MaxDays
integer
1
IntervalType
string
'secs'
IntervalSize
integer
60
BeginFilterTime
EndFilterTime
string
string
Max number of trading days to retrieve
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
Size of bars in IntervalType units. Must be
≥1 for secs, ≥2 for ticks, ≥100 for volume.
'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’.
'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’.
Only return bars that begin after this
''
integer or
string or (empty string) date/time (US Eastern time-zone).
BeginDateTime datetime
meaning today Format: Matlab datenum, ‘yyyymmdd
object
at 00:00:00 hhmmss’ or ‘yyyy-mm-dd hh:mm:ss’.
Max number of seconds to wait (0-9000)
number
5.0
Timeout
for data in blocking mode (0 means infinite)
22
In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization
IQML User Guide
34
4.4 Market depth (Level 2)
Market depth data on a symbol can be fetched using a 'marketdepth' action.
Each incoming market depth message gives information on a single market depth
row. The messages from IQFeed are not sorted by their market depth row; they arrive
at a random, unpredicted order. This is true for the initial market-depth table report,
as well as for row updates, depending on when the corresponding traders update their
bid/ask. The NumOfEvents input parameter, which specifies how many incoming
messages from IQFeed to process, should be set to at least the total number of market
depth rows, in order to get data for all market depth rows.
>> data = IQML('marketdepth', 'symbol','@ES#', 'NumOfEvents',50)
data =
10×1 struct array with fields:
Symbol
Bid
Ask
BidSize
AskSize
...
The latest data (i.e., state of the market-depth table) is returned as a Matlab struct array,
whose elements correspond to the market-depth rows. For example, to see the data for
row #3 (i.e., 2 rows below the top-of-book row), you can access array element #3:
>> data(3)
ans =
Symbol:
Bid:
Ask:
BidSize:
AskSize:
BidTime:
Date:
AskTime:
BidInfoValid:
AskInfoValid:
Condition:
Condition_Description:
'@ES#'
2723.75
2725
102
154
'07:26:08.060172'
'2018-05-15'
'07:26:12.948046'
1
1
52
'regular'
BidInfoValid
and AskInfoValid values are logical (true/false) values, which appear
as 1 or 0, respectively, in the struct display above.
If your IQFeed account is not authorized for Level 2 data, you will see the following
warning message in the Matlab console upon the initial connection to IQFeed
(IQML’s first request) – note that this is only an informational message, not an error:
Account not authorized for Level II
If your IQFeed account is authorized for Level 2 data but not for a certain exchange, you
will receive an error message when requesting market depth info from that exchange:
>> data = IQML('marketdepth', 'Symbol','IBM')
Error using IQML
Symbol 'IBM' was not found!
% not subscribed to NYSE L2
Note: Market Depth (Level 2) data is only available in the Professional IQML license.
IQML User Guide
35
4.5 Greeks, fair value, and implied volatility
Extra data can be fetched (calculated) for asset options using the 'greeks' action:
Greeks (Delta, Vega, Theta, Rho, Gamma etc.)
Fair value for the derivative and the difference vs. actual trading price
Implied volatility based on the fair vs. trading prices
>> data = IQML('greeks', 'symbol','IBM1814L116')
data =
Symbol: 'IBM1814L116'
Asset_Name: 'IBM DEC 2018 C 116.00'
Strike_Price: 116
Expiration_Date: '12/14/2018'
Days_To_Expiration: 30
Inferred_Asset_Side: 'Call'
Underlying_Symbol: 'IBM'
Underlying_Spot: 121.3
Underlying_Historic_Volatility: 37.1
Assumed_Risk_Free_Rate: 0
Assumed_Dividend_Yield: 0
Asset_Fair_Value: 8.1193
Asset_Latest_Price: 7.05
Asset_Price_Diff: 1.0693
Implied_Volatility: 0.28242
Delta: 0.68197
Vega: 0.12404
Theta: -0.076697
Rho: 6.1318
CRho: 6.7992
Omega: 10.189
Lambda: 10.189
Gamma: 0.027646
Vanna: -0.3527
Charm: 0.0021809
Vomma: 5.8043
Veta: 2.4262
Speed: -0.0012419
Zomma: -0.061581
Color: -0.00038078
Ultima: -45.238
Annual_Factor_Used: 365
This_Asset_Latest_Quote: [1×1 struct]
Underlying_Latest_Quote: [1×1 struct]
This_Asset_Fundamentals: [1×1 struct]
Underlying_Fundamentals: [1×1 struct]
The results are reported in a Matlab struct: the first few fields provide basic information
on the derivative asset and its underlying security, followed by fair-value information,
implied volatility and a list of Greek values. Finally, four sub-structs are included to
provide direct access to the asset’s and the underlying’s latest quotes (§4.1) and
fundamenta data (§4.2, for example, data.Underlying_Fundamentals.Average_Volume).
You can request quotes for multiple symbols at the same time, in a single IQML
command, by specifying a colon-delimited or cell-array list of symbols. For example:
>> data = IQML('greeks', 'symbols',{'IBM1814L116','IBM1814X116'});
>> data = IQML('greeks', 'symbols','IBM1814L116:IBM1814X116');
% equivalent
IQML User Guide
36
The result will be an array of Matlab structs that correspond to the requested symbols:
data =
2×1 struct array with fields:
Symbol
Asset_Name
Strike_Price
...
If you have Matlab’s Parallel Computing Toolbox, setting the UseParallel parameter
to true (or 1) will process the Greeks query for all the specified symbols in parallel
(see discussion in §3.6):
>> data = IQML('greeks', 'symbols',{'IBM1814L116','IBM1814X116'}, ...
'UseParallel',true);
Notes:
1. Greeks and related derivative data (the the 'greeks' action in general) is only
available in the Professional IQML (or trial) license.
2. The values are NOT provided by IQFeed but rather computed by IQML on
your local computer. This means that the values do NOT have DTN IQFeed’s
official approval. It also means there is a performance impact: The calculation
and required data fetches for each query may take up to 0.3-1 secs, depending
on your CPU, IQFeed round-trip latency, and the specific option parameters.
3. The calculations assume vanilla European-style options using Black-ScholesMerton’s model.23 Using IQML’s calculations with other derivatives (American/
Asian/barrier/exotic options etc.) may result in incorrect/misleading values.
4. There are various possible ways to estimate Implied Volatility from the option’s
trading price and fair value. IQML uses a standard Newton-Raphson iterative
approximation method; other methods may result in slightly different values.
5. In some cases, some fields may contain obviously-bad values. For example,
the Implied_Volatility field may contain –Inf or +Inf when the Newton
algorithm fails to converge to a valid value. Likewise, some Greeks may
contain a value of NaN in certain cases (for example, a contract that is so far
out-of-the-money that it has no trading price).
6. Some of the Greeks are also known by other names. For example, Vega is
reported as Kappa by some authors; some sources refer to Vomma as Volga or
vega convexity; Omega is sometimes called Lambda or elasticity; Charm is
also known as delta decay, and Color as gamma decay.
7. Various sources/systems calculate Greeks in different manners. For example,
the reported Vega, Rho, Veta and Ultima values are sometimes divided by 100
(IQML does not); Theta, Charm, Veta and Color are sometimes annualized
and sometimes divided by some representative number of days per year
(365/364/360/253/252) to provide 1-day estimates (this factor is customizable
in IQML, 365 by default).24 The foreign rate/dividends yield is ignored by
some sources and included by others in the calculations. Some sources report
the Color as the positive rate of change of Gamma relative to maturity time,
23
Support for American options is planned in a future release of IQML; there are no current plans to support Asian/exotic options.
24
For example, Matlab’s Financial Toolbox, NAG and Maple report annualized values; to get corresponding values in IQML, set
the AnnualFactor parameter to 1.
IQML User Guide
37
and others report them as the negative rate of change.25 In addition, some
sources apparently have buggy math implementations.26 The result is that
different sources provide different Greek values for the very same inputs.
IQML’s values are basically identical to those of Matlab’s Financial Toolbox,
NAG and Maple.27 Unfortunately, IQFeed’s standalone Option Chains utility
reports different values. IQML adheres to the core math formulae28 and we
believe that IQML provides accurate results. However, the discrepancy
between the values reported by different systems means that you must carefully
ensure that IQML’s reported values fit your needs and expectations.
The following Greek values are reported by IQML:
Field Symbol
Derivative
Definition
order
Description
Sensitivity of fair value to changes in the
underlying asset’s spot price
Delta
Δ
1
∂V/∂S
Vega
ν
1
∂V/∂σ
Theta
Θ
1
-∂V/∂τ
Sensitivity of fair value to changes in the
underlying asset’s volatility
Sensitivity of fair value to maturity time
Rho
ρ
1
∂V/∂r
Sensitivity of fair value to risk-free rate
1
∂V/∂b
CRho
Sensitivity of fair value to the cary-rate
% change in fair value to a 1% change in the
Δ × S/V underlying asset’s price (these are synonym
fields, both are reported for convenience)
Sensitivity of Delta to changes in the
∂Δ/∂S underlying asset’s spot price
Sensitivity of Delta to changes in the
∂Δ/∂σ underlying asset’s volatility
-∂Δ/∂τ Sensitivity of Delta to maturity time
Sensitivity of Vega to changes in the
∂ν/∂σ underlying asset’s volatility
Omega,
Lambda
Ω
λ
1
Gamma
Γ
2
Vanna
-
2
Charm
-
2
Vomma
-
2
Veta
-
2
∂ν/∂τ
Sensitivity of Vega to the maturity time
Speed
-
3
∂Γ/∂S
Zomma
-
3
∂Γ/∂σ
Color
-
3
∂Γ/∂τ
Ultima
-
3
∂3V/∂σ3
Sensitivity of Gamma to changes in the
underlying asset’s spot price
Sensitivity of Gamma to changes in the
underlying asset’s volatility
Sensitivity of Gamma to maturity time
Sensitivity of Vomma to changes in the
underlying asset’s volatility
25
For example, the reported Color value is negative in NAG compared to IQML and Maple.
26
This does not imply that there are no calculation bugs in IQML’s implementation. The Greeks calculation is not trivial.
27
Excluding a few quirks, such as a negative Color value reported by NAG, or Maple’s Lambda calculation, or the default
AnnualFactor of 1 used by both. Also compare the very similar values reported by the online calculator http://option-price.com
28
John Hull, Options, Futures, and Other Derivatives (ISBN 9780134472089); https://en.wikipedia.org/wiki/Greeks_(finance)
IQML User Guide
38
By default, IQML uses the derivative’s fundamental data and default 0% rates in its
calculations. You can override these defaults using the following optional parameters:
UnderlyingSymbol – this is the Asset_Name’s first string token by default. For
example, for IBM1814L116, Asset_Name='IBM DEC 2018 C 116.00' so
Underlying_Symbol is set to 'IBM'. This value can be overrriden using the
UnderlyingSymbol parameter. For example, you might wish to specify that
the underlying symbol for Greeks computation of GOOG1816K1000 is not
the default 'GOOG' (Alphabet Inc Class C), but rather 'GOOGL' (Class A).
HistoricVolatility – this is usually reported by IQFeed in the underlying
asset’s fundamental data (data.Underlying_Fundamentals.Historical_Volatility)
and is used in IQML by default. Instead of this reported value, you can specify
another value (for example, the S&P 500 volatility), as a fixed percent value.
RiskFreeRate – this is the domestic risk-free rate. IQML uses 0% by default; you
can specify any other fixed percentage rate (based on e.g. LIBOR29 or T-bill30).
DividendsYield – this is the underlying’s dividend yield, assumed by IQML
to be 0% by default; you can specify any other fixed percentage value. In the
context of Forex currencies, this value may represent the foreign risk-free rate.
Side – by default, the option side ('Call' or 'Put') is determined by IQML from
the derivative contract’s name. You can override this for contracts that have
non-standard names that IQML cannot properly analyze.
DaysToExpiration – by default, IQML determines the number of days until
contract expiration (maturity) based on the contract’s reported Expiration_Date.
This maturity time can be overridden to any positive value. Note that the value
is specified in days, not years.
AnnualFactor – by default, IQML normalizes the reported Theta, Charm,
Veta and Color values by dividing the computed annualized value by 365 in
order to provide 1-day estimates. You can override this scaling factor to any
positive number. Setting a value of 1 provides annualized results (i.e., not 1day estimates), as reported by Matlab’s Financial Toolbox, NAG and Maple.
For example:
>> data = IQML('greeks', 'symbol','IBM1814L116', 'UnderlyingSymbol','IBM', ...
'Duration',13.7, 'RiskFreeRate',2.5, 'DividendsYield',3.2)
29
You can query the current LIBOR rate with IQML, for example using symbol ONLIB.X (overnight rate), 1MLIB.X (1 month),
3MLIB.X (3 months), or 1YLIB.X (1 year). Additional durations are also available
(http://iqfeed.net/symbolguide/index.cfm?pick=indexRATES&guide=mktindices), but a 1-month rate is often used even for
shorter or longer option durations, for consistency. Also see http://forums.iqfeed.net/index.cfm?page=topic&topicID=4387.
30
You can query the current T-bill rate with IQML, for example using symbol TB30.X (30-day rate), IRX.XO (91 days),
TB180.X (180 days), or 1YCMY.X (1 year). Also see http://forums.iqfeed.net/index.cfm?page=topic&topicID=4387.
IQML User Guide
39
The following parameters affect Greeks data queries:
Parameter Data type
Default
colonSymbol or
Symbols 31
delimited
string, or
cell-array
of strings
UseParallel
logical
(true/false)
Underlying
Symbol
string
HistoricVol
number
atility
RiskFreeR
ate
(none)
This parameter must be set to valid symbol
name(s). Multiple symbols can be parallelized
using the UseParallel parameter (see below).
false
-1 (which means
it’s taken from the
underlying asset’s
reported value)
0.0
DividendsY
number
ield
0.0
string
If set to true or 1, and if Parallel Computing
Toolbox is installed, then querying multiple
symbols will be done in parallel (see §3.6).
'' (which means it’s
taken from the Symbol of the derivative’s underlying asset
contract’s name)
number
Side
Description
Limits the query to the specified symbol(s).
Examples:
'GOOG1816K1000'
'IBM1814L116:GOOG1816K1000'
{'IBM1814L116', 'GOOG1816K1000'}
Value that represents the underlying’s price
volatility (in percent). 1.0 means 1%;
-1 means a dynamic value based on the
underlying asset’s reported historic volatility.
Domestic risk-free rate
Specified in percent; 1.0 means 1%.
Underlying’s dividends yield (for stocks) or
foreign risk-free rate (for currencies).
Specified in percent; 1.0 means 1%.
''
(which means it’s Either 'Call' or 'Put'
taken from the
contract’s name)
-1 (which means
DaysToExp
it’s taken from the Number of days until the contract expires
number
(matures)
contract’s
iration
expiration date)
AnnualFac
tor
number
365
The computed Theta, Charm, Veta and
Color values are divided by this factor
before being reported.
Note: The Greeks functionality is only available in the Professional IQML license.
31
In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization
IQML User Guide
40
5 Historical and intra-day data
Historical data can be retrieved via the 'history' action, subject to your account
subscription rights, and IQFeed’s pacing limitations. Several data-types are available,
which can be set using the DataType parameter (default: 'day').32
5.1 Daily data
To retrieve historic daily data bars, set DataType to 'd' or 'day' (or just leave this
parameter out, since 'day' is the default data type), and set the asset’s Symbol:
>> data = IQML('history', 'symbol','IBM');
>> data = IQML('history', 'symbol','IBM', 'dataType','day') %equivalent
data =
100×1 struct array with fields:
Symbol
Datestamp
Datenum
High
Low
Open
Close
PeriodVolume
OpenInterest
We received an array of Matlab structs containing daily bars, one per each of the last
N trading days (excluding the currently-trading bar). By default, we receive up to
N=100 data bars, ordered from oldest to newest. In the example above, we ran the
query on March 6, 2018 so we received daily data from 2017-10-10 until 2018-03-05:
>> data(1)
ans =
Symbol:
Datestamp:
Datenum:
High:
Low:
Open:
Close:
PeriodVolume:
OpenInterest:
>> data(end)
ans =
Symbol:
Datestamp:
Datenum:
High:
Low:
Open:
Close:
PeriodVolume:
OpenInterest:
'IBM'
'2017-10-10'
736978
148.95
147.65
147.71
148.5
4032601
0
'IBM'
'2018-03-05'
737124
157.49
153.75
154.12
156.95
3670630
0
You can aggregate the numeric values into Matlab arrays as follows:
dates = {data.Datestamp};
closes = [data.Close];
% cell-array of strings
% array of numeric values
You can then use these arrays for vectorized processing, plotting etc. For example:
dates2 = datetime(dates);
[maxVal, maxIdx] = max(closes);
[minVal, minIdx] = min(closes);
32
http://iqfeed.net/dev/api/docs/HistoricalviaTCPIP.cfm
% array of datetime objects
% maximal value and location index
% minimal value and location index
IQML User Guide
plot(dates2, closes); hold on;
plot(dates2(maxIdx), maxVal, '^g');
plot(dates2(minIdx), minVal, 'vr');
41
% maximal data point – green ▲
% minimal data point – red ▼
You can change the order at which the data bars are reported, using the DataDirection
parameter (1 means oldest-to-newest (default); -1 means newest-to-oldest):
>> data = IQML('history', 'symbol','IBM', 'dataDirection',-1);
>> data(1)
ans =
Symbol: 'IBM'
Datestamp: '2018-03-05'
Datenum: 737124
High: 157.49
Low: 153.75
Open: 154.12
Close: 156.95
PeriodVolume: 3670630
OpenInterest: 0
It is possible that there may be fewer than N=100 daily bars for an asset. For example,
the symbol @EMF19 (1-month Euro-Dollar Jan 2019 future on CME) started trading
on 2018-01-12, so we only get 35 daily bars when we run the query on 2018-03-06:
>> data = IQML('history', 'symbol','@EMF19');
data =
35×1 struct array with fields:
Symbol
...
You can ask IQFeed to limit the maximal number of data bars (N) using the
MaxItems parameter:
>> data = IQML('history', 'symbol','IBM', 'maxItems',20)
data =
20×1 struct array with fields:
Symbol
...
In this example, data(1).Datestamp='2018-02-05', i.e. 20 trading days ago.
Note that the MaxItems parameter only has an effect if the additional data bars
actually exist. In other words, it controls the maximum number of returned data bars –
the actual number of bars may be less than this value.33
33
For example, IQFeed’s trial account is limited to 1-year of daily data points; IQFeed automatically trims trial-account queries
down to this limit: http://forums.dtn.com/index.cfm?page=topic&topicID=5535
IQML User Guide
42
When the number of data bars that IQFeed sends is very large, it could take a while
for the information to be sent. In such a case, IQML might time-out on the request and
return only partial data. Such a case is detected and reported by IQML:
>> data = IQML('history', 'symbol','IBM', 'maxItems',-1)
Warning: IQML timeout: only partial data is returned: the Timeout parameter
should be set to a value larger than 5
data =
1274×1 struct array with fields:
Symbol
...
As suggested by the message, you can set the Timeout parameter to a high value in
order to allow IQML more time to gather the data before returning the results:
>> data = IQML('history', 'symbol','IBM', 'maxItems',-1, 'timeout',60) %oldest:1/2/96
data =
5577×1 struct array with fields:
Symbol
...
You can also specify a BeginDate/EndDate interval for the returned data. Dates can be
specified in several formats: numeric Matlab datenum (737089), Matlab datetime
object, numeric yyyymmdd (20180129), string ('2018/01/29', '2018-01-29', '20180129').
Note that MaxItems takes precedence over BeginDate, regardless of DataDirection.
For example, if MaxItems=5, you will only get the 5 latest bars, for any BeginDate.
You can request historical data for multiple symbols at the same time, in a single IQML
command, by specifying a colon-delimited or cell-array list of symbols. For example:
>> data = IQML('history', 'symbol',{'IBM','GOOG','AAPL'}, 'maxItems',20)
>> data = IQML('history', 'symbol','IBM:GOOG:AAPL', 'maxItems',20) %equivalent
The result will be an array of Matlab structs that correspond to the requested symbols
(3 symbols with 20 data-points each, in this example):
data =
20×3 struct array with fields:
Symbol
...
>> data(1,2) % 2nd index (column) is the symbol; GOOG data is in data(:,2)
ans =
struct with fields:
Symbol: 'GOOG'
Datestamp: '2018-07-10'
Datenum: 737251
High: 1159.59
Low: 1149.59
Open: 1156.98
Close: 1152.84
PeriodVolume: 798412
OpenInterest: 0
In certain cases, when you request historic data for multiple symbols, you might
receive a different number of data bars for different symbols, depending on data
availability. In such cases, the result will not be an N-by-M struct array, but a cell
array (one cell for each symbol) that contains struct arrays. For example:
data =
1×3 cell array
{77×1 struct}
{100×1 struct}
{55×1 struct}
IQML User Guide
43
IQML queries for multiple symbols or dates (if BeginDate and EndDate are specified)
can be parallelized using the UseParallel parameter, if you have a Professional IQML
license and Matlab’s Parallel Computing Toolbox (§3.6):
>> data = IQML('history', 'UseParallel',true, 'symbol',symbols) %multi-symbols
>> data = IQML('history', 'UseParallel',true, 'symbol','IBM',...
'BeginDate',19900102, 'EndDate',20181028)
%date range
The following parameters affect daily history data queries:
Parameter Data type Default
Description
Limits the query to the specified symbol(s).
Examples:
colon '@VX#'
delimited
Symbol or
'IBM:AAPL:GOOG'
string or
(none)
{'IBM', 'AAPL', 'GOOG'}
Symbols 34
cell-array
This parameter must be set to valid symbol
of strings
name(s). Multiple symbols can be parallelized
using the UseParallel parameter (see below).
1
Sets the order of data bars in the returned
meaning struct array. One of the following values:
DataDirection integer
oldest first, 1 means oldest-to-newest (default)
newest last -1 means newest-to-oldest
Returns up to the specified number of data
integer
100
MaxItems
bars (if available). -1 means all available.
BeginDate
'1900/01/01'
integer or
(i.e., from
string or
as early as
datetime
data is
object
available)
EndDate
integer or
'2099/12/31'
string or
(i.e., until
datetime
now)
object
Timeout
UseParallel
34
number
5.0
logical
(true/false)
false
Earliest bar date. Examples:
737089 (Matlab datenum format)
20180129 (yyyymmdd format)
'20180129'
'2018/01/29'
'2018-01-29'
Note: MaxItems has precedence over
BeginDate: If there are more data points
than MaxItems between BeginDate–
EndDate, only the last MaxItems data
points (from EndDate backward) will be
returned, regardless of BeginDate.
Latest bar date.
See BeginDate above for details.
Max # of seconds to wait for incoming data
(0-9000, where 0 means infinite)
If set to true or 1, and if Parallel Computing
Toolbox is installed, then querying multiple
symbols or dates will be done in parallel
(see §3.6; Professional IQML license only).
In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization
IQML User Guide
44
5.2 Weekly data
To retrieve historic weekly data bars, set DataType to 'w' or 'week', and set the
asset’s Symbol:
>> data = IQML('history', 'symbol','FB', 'dataType','week')
data =
100×1 struct array with fields:
Symbol
Datestamp
Datenum
High
Low
Open
Close
PeriodVolume
OpenInterest
As with the daily bars, we received an array of Matlab structs containing weekly bars,
one per each of the last N weeks (excluding the currently-trading day). By default we
receive up to N=100 data bars (~2 years), ordered from oldest to newest. In the
example above, we ran the query on March 6, 2018 so we received weekly data from
2016-04-15 (the data bar for April 11-15, 2016) until 2018-03-05 (the data bar for
March 5, 2018 only). Each bar’s Datestamp indicates the end-date of the bar.
As with the daily bars, you can change the data bars order, using the DataDirection
parameter (1 means oldest-to-newest (default); -1 means newest-to-oldest).
>> data = IQML('history', 'symbol','FB', 'dataType','week', 'dataDirection',-1);
As with the daily bars, you can ask IQFeed to limit the maximal number of data bars
(N) using the MaxItems parameter:
>> data = IQML('history', 'symbol','FB', 'dataType','week', 'maxItems',20);
In this example, data(1).Datestamp='2017-10-27', i.e. 20 weeks ago.
As with the daily bars, you can set the Timeout parameter to a high value in order to
allow IQML more time to gather data before returning the results. This is typically not
necessary for weekly data requests, because of the relatively low amount of data.
Note: unlike daily data requests, you cannot specify a BeginDate/EndDate interval
in a request for historic weekly data bars.
As with daily data requests, you can request historical data for multiple symbols at the
same time, in a single IQML command, by specifying a colon-delimited or cell-array
list of symbols. For example:
>> data = IQML('history', 'symbol',{'IBM','GOOG','AAPL'}, ...
'dataType','week', 'maxItems',20)
>> data = IQML('history', 'symbol','IBM:GOOG:AAPL', ...
'dataType','week', 'maxItems',20) %equivalent
IQML User Guide
45
The result will be an array of Matlab structs that correspond to the requested symbols
(3 symbols with 20 data-points each, in this example):
data =
20×3 struct array with fields:
Symbol
Datestamp
...
In certain cases, when you request historic data for multiple symbols, you might
receive a different number of data bars for different symbols, depending on data
availability. In such cases, the result will not be an N-by-M struct array, but a cell
array (one cell for each symbol) that contains struct arrays. For example:
data =
1×3 cell array
{77×1 struct}
{100×1 struct}
{55×1 struct}
IQML queries for multiple symbols can be parallelized using the UseParallel parameter, if
you have a Professional IQML license and Matlab’s Parallel Computing Toolbox (§3.6):
>> data = IQML('history', 'symbol',symbols, 'UseParallel',true, ...
'dataType','week', 'maxItems',20)
The following parameters affect weekly history data queries:
Parameter
Symbol or
Symbols 35
Data type
Default
colondelimited
string or
cell-array
of strings
(none)
DataDirection
integer
MaxItems
integer
Timeout
number
UseParallel
35
logical
(true/false)
Description
Limits the query to the specified symbol(s).
Examples:
'@VX#'
'IBM:AAPL:GOOG'
{'IBM', 'AAPL', 'GOOG'}
This parameter must be set to valid symbol
name(s). Multiple symbols can be parallelized
using the UseParallel parameter (see below).
1
Sets the order of data bars in the returned
meaning struct array. One of the following values:
oldest bar is 1 means oldest-to-newest (default)
first, newest -1 means newest-to-oldest
is last
Returns up to the specified number of data
100
bars (if available). -1 means all available.
5.0
Max number of seconds to wait for incoming
data (0-9000, where 0 means infinite)
false
If set to true or 1, and if Parallel Computing
Toolbox is installed, then querying multiple
symbols will be done in parallel (see §3.6;
Professional IQML license only).
In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization
IQML User Guide
46
5.3 Monthly data
To retrieve historic monthly data bars, set DataType to 'm' or 'month', and set the
asset’s Symbol:
>> data = IQML('history', 'symbol','FB', 'dataType','month')
data =
100×1 struct array with fields:
Symbol
Datestamp
Datenum
High
Low
Open
Close
PeriodVolume
OpenInterest
As with the daily bars, we received an array of Matlab structs containing monthly
bars, one per each of the last N months (excluding the currently-trading day). By
default we receive up to N=100 data bars (~8 years), ordered from oldest to newest.
We ran the example query above on March 6, 2018 so we received monthly data from
2009-12-31 (the data bar for 12/2009) until 2018-03-05 (the data bar for March 2018).
As with the daily bars, you can change the data bars order, using the DataDirection
parameter (1 means oldest-to-newest (default); -1 means newest-to-oldest).
>> data = IQML('history', 'symbol','FB', 'dataType','month', ...
'dataDirection',-1);
As with the daily bars, you can ask IQFeed to limit the maximal number of data bars
(N) using the MaxItems parameter:
>> data = IQML('history', 'symbol','FB', 'dataType','month', 'maxItems',20);
In this example, data(1).Datestamp='2016-08-31', i.e. 20 months ago.
As with the daily bars, you can set the Timeout parameter to a high value in order to
allow IQML more time to gather data before returning the results. This is typically not
necessary for monthly data requests, because of the relatively low amount of data.
Note: unlike daily data requests, you cannot specify a BeginDate/EndDate interval
in a request for historic monthly data bars.
As with daily data requests, you can request historical data for multiple symbols at the
same time, in a single IQML command, by specifying a colon-delimited or cell-array
list of symbols. For example:
>> data = IQML('history', 'symbol',{'IBM','GOOG','AAPL'}, ...
'dataType','month', 'maxItems',20)
>> data = IQML('history', 'symbol','IBM:GOOG:AAPL', ...
'dataType','month', 'maxItems',20) %equivalent
IQML User Guide
47
The result will be an array of Matlab structs that correspond to the requested symbols
(3 symbols with 20 data-points each, in this example):
data =
20×3 struct array with fields:
Symbol
Datestamp
...
In certain cases, when you request historic data for multiple symbols, you might
receive a different number of data bars for different symbols, depending on data
availability. In such cases, the result will not be an N-by-M struct array, but a cell
array (one cell for each symbol) that contains struct arrays. For example:
data =
1×3 cell array
{77×1 struct}
{100×1 struct}
{55×1 struct}
IQML queries for multiple symbols can be parallelized using the UseParallel parameter, if
you have a Professional IQML license and Matlab’s Parallel Computing Toolbox (§3.6):
>> data = IQML('history', 'symbol',symbols, 'UseParallel',true, ...
'dataType','month', 'maxItems',20)
The following parameters affect monthly history data queries:
Parameter
Symbol or
Symbols 36
Data type
Default
colondelimited
string or
cell-array
of strings
(none)
DataDirection
integer
MaxItems
integer
Timeout
number
UseParallel
36
logical
(true/false)
Description
Limits the query to the specified symbol(s).
Examples:
'@VX#'
'IBM:AAPL:GOOG'
{'IBM', 'AAPL', 'GOOG'}
This parameter must be set to valid symbol
name(s). Multiple symbols can be parallelized
using the UseParallel parameter (see below).
1
Sets the order of data bars in the returned
meaning struct array. One of the following values:
oldest bar is
1 means oldest-to-newest (default)
first, newest
-1 means newest-to-oldest
is last
Returns up to the specified number of data
100
bars (if available). -1 means all available.
5.0
Max number of seconds to wait for incoming
data (0-9000, where 0 means infinite)
false
If set to true or 1, and if Parallel Computing
Toolbox is installed, then querying multiple
symbols will be done in parallel (see §3.6;
Professional IQML license only).
In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization
IQML User Guide
48
5.4 Interval data
To retrieve historic data bars having a custom width, possibly as short as a single
second, set DataType to 'i' or 'interval', and set the asset’s Symbol:
>> data = IQML('history', 'symbol','FB', 'dataType','interval')
data =
100×1 struct array with fields:
Symbol
Timestamp
Datenum
High
Low
Open
Close
TotalVolume
PeriodVolume
NumberOfTrades
>> data(end)
ans =
Symbol:
Timestamp:
Datenum:
High:
Low:
Open:
Close:
TotalVolume:
PeriodVolume:
NumberOfTrades:
'IBM'
'2018-03-07 09:43:00'
737126.404861111
156.97
156.77
156.83
156.77
215082
16080
0
The returned data struct here is similar to the struct returned by the daily, weekly and
monthly historical data queries. Unlike those queries, interval-query result does not
include an OpenInterest field, but does include two new fields: TotalVolume (which
indicates the total daily volume up to that bar), and NumberOfTrades. Also note that we
get a Timestamp field (US Eastern time-zone), not Datestamp as with the other queries.
Bars that had no trading action are not reported. In the example query above, we see
the following Timestamp values, where we clearly see a gap during non-trading hours:
>> {data.Timestamp}'
ans =
100×1 cell array
{'2018-03-06 14:59:00'}
{'2018-03-06 15:00:00'}
{'2018-03-06 15:01:00'}
... % contiguous data bars
{'2018-03-06 15:59:00'}
{'2018-03-06 16:00:00'}
{'2018-03-06 16:03:00'}
{'2018-03-06 16:11:00'}
...
{'2018-03-07 08:33:00'}
{'2018-03-07 08:45:00'}
{'2018-03-07 09:22:00'}
{'2018-03-07 09:31:00'}
{'2018-03-07 09:32:00'}
... % contiguous data bars
{'2018-03-07 09:43:00'}
{'2018-03-07 09:44:00'}
IQML User Guide
49
As with the other queries, the current (unclosed) interval bar is never reported, nor
bars that have no data (e.g., 16:04-16:10, 8:34-8:44, 8:46-9:21 in the example above).
The default interval size is 60 secs (1 minute, aligned on the full-minute mark). You
can specify a different interval size using the IntervalSize parameter. For example, to
set a 15-sec interval:
>> data=IQML('history','symbol','FB','dataType','interval','intervalSize',15);
IQFeed is smart enough to automatically align the data bars to full minutes/hours
when the requested IntervalSize enables this (as is the case for 15 or 60-sec
intervals). For example, with a 15-sec IntervalSize we may get bars for 10:04:15,
10:04:30, 10:04:45, 10:05:00.
When such alignment is not possible, you will get non-aligned bars. For example,
with a 13-sec IntervalSize: 09:59:18, 09:59:31, 09:59:57, 10:00:10.
By default, IntervalSize specifies the interval’s size in seconds and all the bars have
this same duration. You can change this by setting the IntervalType parameter
(default: 'secs') to 'volume' or 'ticks'/'trades'. Naturally, if you change IntervalType,
the data bars will now have non-equal durations.
>> data = IQML('history', 'symbol','FB', 'dataType','interval', ...
'intervalType','ticks');
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 between 1 and 86400 (1 day).37
By default, IQML only reports interval data from today. You can ask to see additional
(older) calendar days by specifying a positive Days parameter value. If you set Days
to -1, then all available information will be reported, subject to the other filter criteria.
In addition, you can specify a daily time-window: only bars between BeginFilterTime
and EndFilterTime in each day (US Eastern time-zone) will be reported. This could
be useful, for example, to limit the results only to the regular trading hours.
Similarly, you can specify a date/time window for all the data bars: only bars that
start after the specified BeginDateTime and end before the specified EndDateTime
(both of them US Eastern time-zone) will be reported.
As with the daily bars, you can change the data bars order, using the DataDirection
parameter (1 means oldest-to-newest (default); -1 means newest-to-oldest).
>> data=IQML('history','symbol','FB','dataType','interval','dataDirection',-1);
37
Note that IQFeed’s limitations on live 'secs' interval bars (§4.3, §6.3) are stricter than the limitations on historical interval bars:
http://forums.dtn.com/index.cfm?page=topic&topicID=5529
IQML User Guide
50
As with the daily bars, you can ask IQFeed to limit the maximal number of data bars
(N) using the MaxItems parameter:
>> data = IQML('history', 'symbol','FB', 'dataType','interval', 'maxItems',20);
Note that MaxItems takes precedence over BeginDateTime, regardless of
DataDirection. For example, if MaxItems=5, you will only get the 5 latest bars
(before EndDateTime), regardless of the specified BeginDateTime.
As with the daily bars, you can set the Timeout parameter to a high value in order to
allow IQML more time to gather data before returning the results.
As with daily data requests, you can request historical data for multiple symbols at the
same time, in a single IQML command, by specifying a colon-delimited or cell-array
list of symbols. For example:
>> data = IQML('history', 'symbol',{'IBM','GOOG','AAPL'}, ...
'dataType','interval', 'maxItems',20)
>> data = IQML('history', 'symbol','IBM:GOOG:AAPL', ...
'dataType','interval', 'maxItems',20) %equivalent
The result will be an array of Matlab structs that correspond to the requested symbols
(3 symbols with 20 data-points each, in this example):
data =
20×3 struct array with fields:
Symbol
Datestamp
...
In certain cases, when you request historic data for multiple symbols, you might
receive a different number of data bars for different symbols, depending on data
availability. In such cases, the result will not be an N-by-M struct array, but a cell
array (one cell for each symbol) that contains struct arrays. For example:
data =
1×3 cell array
{77×1 struct}
{100×1 struct}
{55×1 struct}
IQML queries for multiple symbols or a date/time range (if BeginDateTime and
EndDateTime are specified) can be parallelized using the UseParallel parameter, if you
have a Professional IQML license and Matlab’s Parallel Computing Toolbox (see §3.6):
>> data = IQML('history', 'dataType','interval', 'UseParallel',true, ...
'symbol',symbols)
% multiple symbols parallelized
>> data = IQML('history', 'dataType','interval', 'UseParallel',true, ...
'symbol','IBM' ,... % single-symbol date-range parallelized
'BeginDateTime',20181026100000, ...
'EndDateTime', 20181026110000)
In some cases, users may be tempted to use the historical data mechanism to retrieve
real-time data. This is relatively easy to set-up. For example, using an endless Matlab
loop that sleeps for 60 seconds, requests the latest historical data for the past minute
and then goes to sleep again, or using a periodic timer object that wakes up every
minute. In such cases, consider using streaming rather than historical queries (see §6).
Some software vendors make a distinction between intra-day and historical
information. However, as far as IQFeed and IQML are concerned, this is merely a
semantic difference and there is no practical difference.
IQML User Guide
51
Note: by default IQFeed limits interval data to the past 180 calendar days if you make
the request outside trading hours, but just past 8 days for requests during US trading
hours (9:30-16:30 US Eastern time). This means that if during trading hours you
request historic data from a month ago, you will get none (empty results), even if the
request was just for a single hour of data.
The only exception to the 8/180-day limitation are interval bars of full minutes
(IntervalType='secs' and IntervalSize a multiple of 60), since these bars are precomputed and have a lesser impact on IQFeed’s servers. The other interval types are
computed on-the-fly from tick data, and so are limited in duration in order not to
overload IQFeed’s servers, especially during trading hours when server load is high.
An additional limitation imposed by IQFeed is that minute interval data is only
available since 2005-2007.38 Longer intervals (daily/weekly/monthly) have 10+ years
of data.
Also note that IQFeed’s interval data typically exclude “O” trades (see §5.5).
The following parameters affect interval history data queries:
Parameter
Symbol or
Symbols 39
DataDirection
MaxItems
Days
Data type
Default
colondelimited
string or
cell-array
of strings
(none)
Description
Limits the query to the specified symbol(s).
Examples:
'@VX#'
'IBM:AAPL:GOOG'
{'IBM', 'AAPL', 'GOOG'}
This parameter must be set to valid symbol
name(s). Multiple symbols can be parallelized
using the UseParallel parameter (see below).
1
Sets the order of data bars in the returned
meaning struct array. One of the following values:
integer oldest bar is
1 means oldest-to-newest (default)
first, newest
-1 means newest-to-oldest
is last
Returns up to the specified number of data
integer
100
bars (if available). -1 means all available.
integer
Number of preceding calendar days to
1
process. -1 means unlimited (all available
meaning
data, subject to the other criteria), 1 means
today only
today, 2 means today & yesterday, etc.
38
Specifically for minute (60 sec) intervals, IQFeed’s developer FAQ indicates that “Minute interval data dating back to mid
2005 for select contracts and mid 2007 for all others [is available]”.
39
In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization
IQML User Guide
Parameter
Data type
Default
IntervalType
string
'secs'
IntervalSize
integer
60
BeginFilterTime
EndFilterTime
string
Only return bars that end before this time of
day (US Eastern time-zone). Only relevant
'23:59:59'
when Days>0 or BeginDateTime is not ''.
Format: hhmm, hh:mm, hhmmss or hh:mm:ss
integer or
string or
datetime
object
UseParallel
Size of bars in IntervalType units. Must be
≥1 for secs, ≥2 for ticks, ≥100 for volume bars
string
object
Timeout
Description
Sets the type of interval size. One of the
following values:
's' or 'secs' – time [seconds] (default)
'v' or 'volume' – traded volume
't', 'trades' or 'ticks' – number of ticks
Only return bars that begin after this time of
day (US Eastern time-zone). Only relevant
'00:00:00'
when Days>0 or BeginDateTime is not ''.
Format: hhmm, hh:mm, hhmmss or hh:mm:ss
integer or
string or
BeginDateTime datetime
EndDateTime
52
number
logical
(true/false)
Only return bars that begin after this
date/time (US Eastern time-zone).
''
Only relevant when Days<0.
(empty Format: Matlab datenum, ‘yyyymmdd
string) hhmmss’ or ‘yyyy-mm-dd hh:mm:ss’.
meaning
from as Note: MaxItems has precedence over
early as BeginDateTime: If there are more data
data is points than MaxItems between Begin/
available EndDateTime, only the last MaxItems
data points (from EndDateTime backward)
are returned, regardless of BeginDateTime.
''
(empty
string)
meaning
now
Only return bars that end before this
date/time (US Eastern time-zone)
Only relevant when Days<0.
Format: Matlab datenum, ‘yyyymmdd
hhmmss’ or ‘yyyy-mm-dd hh:mm:ss’.
5.0
Max number of seconds to wait for incoming
data (0-9000, where 0 means infinite)
false
If set to true or 1, and if Parallel Computing
Toolbox is installed, then querying multiple
symbols or a date/time range will be done
in parallel (see §3.6; Professional IQML
license only).
IQML User Guide
53
5.5 Tick data
Unlike data bars, which aggregate ticks and provide summary information, it is also
possible to retrieve historic individual trades (“ticks”). To retrieve this data, set
DataType to 't' or 'ticks', and set the asset’s Symbol:
>> data = IQML('history', 'symbol','IBM', 'dataType','ticks')
data =
100×1 struct array with fields:
Symbol
Timestamp
Datenum
Last
LastSize
TotalVolume
Bid
Ask
TickID
BasisForLast
BasisDescription
TradeMarketCenter
TradeMarketName
TradeConditions
TradeDescription
>> data(end)
ans =
Symbol:
Timestamp:
Datenum:
Last:
LastSize:
TotalVolume:
Bid:
Ask:
TickID:
BasisForLast:
BasisDescription:
TradeMarketCenter:
TradeMarketName:
TradeConditions:
TradeDescription:
'IBM'
'2018-03-07 13:23:02.036440'
737126.557662458
156.72
8
1698707
156.72
156.76
808996961
'O'
'Last qualified trade'
18
'Better Alternative Trading System (BATS)'
'3D87'
'Intramaket Sweep; Odd lot trade'
The data struct here is quite different than the historical bar queries above. Notice the
Timestamp field, specified in micro-second precision (US Eastern time-zone). See a
discussion of the time resolution in the next page.
Note that the textual Description fields depend on the MsgParsingLevel parameter
having a value of 2 or higher (see §3.2 and §8)
Also note that only trade ticks are provided, along with the Bid and Ask prices at the
time of the trade. IQFeed does not report historic non-trading ticks (i.e., Bid/Ask
changes that occurred between the trades).
The Last and LastSize fields typically refer to the last trade. The type (“basis”) of
data in these fields is determined according to the BasisForLast field, which is
explained in the BasisDescription field for convenience.40 Possible basis values are:41
40
Note that the textual Description fields depend on the MsgParsingLevel parameter having a value of 2 or higher (see §3.2)
IQML User Guide
54
C – Last qualified trade.
E – Extended trade = form T trade.
O – Other trade = any trade not accounted for by C or E.
S – Settle = daily settle (only applicable to commodities).
In general, algo-trading should rely only on “C” trades, and potentially also “E”
trades. “O” trades often have wide price swings (i.e. large variation from mainstream
trading prices); this adds noise to charts and may confuse data analytics.42 IQFeed’s
interval data (§5.4) typically exclude “O” trades.
Note that TickID values are not always increasing, and almost never contiguous. They
are generally provided by the exchange as unique trade identifiers and so should not
be used as an indicator of missing data, and their order is not quarantined. Instead, it
is better to rely on the Timestamp or Datenum fields.
In some cases, implied ticks are reported. For example, note the following tick that
was retrieved for the VIX index continuous future (@VX#):
>> data = IQML('history', 'symbol','@VX#', 'dataType','ticks');
>> data(1)
ans =
Symbol: '@VX#'
Timestamp: '2018-03-09 06:47:57.899000'
Datenum: 737128.283309016
Last: 17.12
LastSize: 1
TotalVolume: 3605
Bid: 17.1
Ask: 17.15
TickID: 4377589
BasisForLast: 'O'
BasisDescription: 'Other trade = any trade not accounted for by C or E'
TradeMarketCenter: 32
TradeMarketName: 'CBOE Futures Exchange (CFE)'
TradeConditions: '4D'
TradeDescription: 'Implied'
Note that in the case of @VX# on CBOE, the ticks are only reported in millisecond
resolution, not microseconds as for IBM. In this case, Timestamp still shows 6 digits
after the seconds decimal, but they always end in 000 (…:57.899000). The actual
time resolution of reported ticks depends on the specific exchange and security type.43
You can limit the data that is returned, as with the historical-bars queries above:
By default, IQML only reports ticks data from today. You can ask to see additional
(older) calendar days by specifying a positive Days parameter value. If you set Days
to -1, then all available information will be reported, subject to the other filter criteria.
In addition, you can specify a daily time-window: only ticks between BeginFilterTime
and EndFilterTime in each day (US Eastern time-zone) will be reported. This could
be useful, for example, to limit the results only to the regular trading hours.
41
Additional basis codes may be added by IQFeed in the future.
42
http://forums.iqfeed.net/index.cfm?page=topic&topicID=3898
43
Micro-second resolution is only available with IQFeed client 5.2 or newer, and only in certain setups (e.g. CMEGroup and
equity markets). Contact IQFeed support if you are unsure about the resolution provided by a certain setup configuration.
IQML User Guide
55
Similarly, you can specify an overall date/time window: only ticks that start after the
specified BeginDateTime and end before the specified EndDateTime (both of them
US Eastern time-zone) will be reported.
You can also limit the maximal number of ticks using the MaxItems parameter.
Note: by default IQFeed limits ticks data to the past 180 calendar days if you make
the request outside trading hours, but just past 8 days for requests during US trading
hours (9:30-16:30 US Eastern time).44 This means that if during trading hours you
request historic data from a month ago, you will get none (empty results), even if the
request was just for a single hour of data.
You can change the order of the reported ticks, using the DataDirection parameter (1
means oldest-to-newest (default); -1 means newest-to-oldest). MaxItems has precedence
over BeginDateTime, regardless of DataDirection. For example, if MaxItems=5,
we’ll only get the 5 latest ticks (before EndDateTime), regardless of BeginDateTime.
As with daily data requests, you can request historical data for multiple symbols at the
same time, in a single IQML command, by specifying a colon-delimited or cell-array
list of symbols. For example:
>> data = IQML('history', 'symbol',{'IBM','GOOG','AAPL'}, ...
'dataType','ticks', 'maxItems',20)
>> data = IQML('history', 'symbol','IBM:GOOG:AAPL', ...
'dataType','ticks', 'maxItems',20) %equivalent
The result will be an array of Matlab structs that correspond to the requested symbols
(3 symbols with 20 data-points each, in this example):
data =
20×3 struct array with fields:
Symbol
Datestamp
...
In certain cases, when you request historic data for multiple symbols, you might
receive a different number of data bars for different symbols, depending on data
availability. In such cases, the result will not be an N-by-M struct array, but a cell
array (one cell for each symbol) that contains struct arrays. For example:
data =
1×3 cell array
{77×1 struct}
{100×1 struct}
{55×1 struct}
IQML queries for multiple symbols or a date/time range (if BeginDateTime and
EndDateTime are specified) can be parallelized using the UseParallel parameter, if you
have a Professional IQML license and Matlab’s Parallel Computing Toolbox (see §3.6):
>> data = IQML('history', 'dataType','ticks', 'UseParallel',true, ...
'symbol',symbols)
% multiple symbols parallelized
>> data = IQML('history', 'dataType','ticks', 'UseParallel',true, ...
'symbol','IBM' ,... % single-symbol date-range parallelized
'BeginDateTime',20181026100000, ...
'EndDateTime', 20181026110000)
44
Historic ticks older than 180 days can be purchased from DTN – http://forums.iqfeed.net/index.cfm?page=topic&topicID=4376
IQML User Guide
56
Finally, as with other IQML commands, you can set the Timeout parameter to a high
value in order to allow IQML more time to gather data before returning the results.
The following parameters affect ticks history data queries:
Parameter
Symbol or
Symbols 45
Data type
Default
colondelimited
string or
cell-array
of strings
(none)
DataDirection
integer
MaxItems
integer
Days
BeginFilterTime
EndFilterTime
45
Description
Limits the query to the specified symbol(s).
Examples:
'@VX#'
'IBM:AAPL:GOOG'
{'IBM', 'AAPL', 'GOOG'}
This parameter must be set to valid symbol
name(s). Multiple symbols can be parallelized
using the UseParallel parameter (see below).
1
Sets the order of ticks in the returned struct
meaning array. One of the following values:
oldest tick
1 means oldest-to-newest (default)
is first,
newest last -1 means newest-to-oldest
Returns up to the specified number of ticks
100
(if available). -1 means all available.
integer
Number of preceding calendar days to
1
process. -1 means unlimited (all available
meaning
data, subject to the other criteria), 1 means
today only
today, 2 means today & yesterday, etc.
string
Only return ticks that begin after this time of
day (US Eastern). Only relevant when Days>0
'00:00:00'
or BeginDateTime is not ''. Format:
‘hhmm’, ‘hh:mm’, ‘hhmmss’ or ‘hh:mm:ss’.
string
Only return ticks that end before this time of
day (US Eastern). Only relevant when Days>0
'23:59:59'
or BeginDateTime is not ''. Format:
‘hhmm’, ‘hh:mm’, ‘hhmmss’ or ‘hh:mm:ss’.
In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization
IQML User Guide
Parameter
Data type
integer or
string or
BeginDateTime datetime
object
EndDateTime
integer or
string or
datetime
object
Timeout
UseParallel
number
logical
(true/false)
Default
''
(empty
string)
meaning
from as
early as
data is
available
''
(empty
string)
meaning
now
57
Description
Only return ticks that begin after this
date/time (US Eastern time-zone).
Only relevant when Days<0.
Format: Matlab datenum, ‘yyyymmdd
hhmmss’ or ‘yyyy-mm-dd hh:mm:ss’.
Note: MaxItems has precedence over
BeginDateTime: If there are more data
points than MaxItems between
BeginDateTime–EndDateTime, only the
last MaxItems data points (from
EndDateTime backward) will be returned,
regardless of BeginDateTime.
Only return ticks that end before this
date/time (US Eastern time-zone)
Only relevant when Days<0.
Format: Matlab datenum, ‘yyyymmdd
hhmmss’ or ‘yyyy-mm-dd hh:mm:ss’.
5.0
Max number of seconds to wait for incoming
data (0-9000, where 0 means infinite)
false
If set to true or 1, and if Parallel Computing
Toolbox is installed, then querying multiple
symbols or a date/time range will be done
in parallel (see §3.6; Professional IQML
license only).
IQML User Guide
58
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:
1. 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.
2. 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, let’s request 100 streaming quotes for a continuous VIX future contract:
IQML('quotes', 'Symbol','@VX#', 'NumOfEvents',100)
This causes IQFeed to start sending quotes to IQML in the background, up to the
specified NumOfEvents, without affecting normal Matlab processing. This means
that you can continue to work with Matlab, process data, display information etc.
Quotes 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,46 then up to the specified number of latest
quotes will be stored:
IQML('quotes', 'Symbol','@VX#', 'NumOfEvents',100, 'MaxItems',3)
Note 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.47
46
MaxItems is a numeric parameter like NumOfEvents, so don’t enclose the parameter value within string quotes (‘’)
47
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).
IQML User Guide
59
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
Command
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
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
– the requested Symbol.
– the command sent to IQFeed, including the requested Symbol.
– total number of streaming ticks requested for the security
(using the NumOfEvents parameter).
to reach IQFeed, and during this time a few additional ticks may have arrived.
LatestEventDatenum – Matlab
LatestEventTimestamp.
LatestEventTimestamp
numeric datenum representation of the
– local timestamp (string format) when this quote was
received by IQML.
DataType
ProcessType
BufferSize
Buffer
LatestData
– type of data to stream (set by DataType parameter, see below).
– always equal to 'stream' for streaming quotes.
– size of the data buffer (=MaxItems parameter, see below).
– buffer of size BufferSize, accumulating the latest quote updates.
– 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.
IQML User Guide
60
To get the quotes data, simply read the fields of the returned data struct, for example:48
>> data.LatestData
ans =
Symbol:
Most_Recent_Trade:
Most_Recent_Trade_Size:
Most_Recent_Trade_Time:
Most_Recent_Trade_Market_Center:
Total_Volume:
Bid:
Bid_Size:
Ask:
Ask_Size:
Open:
High:
Low:
Close:
Message_Contents:
Message_Description:
'@VX#'
17.08
[]
'08:06:20.716000'
32
4507
17.05
63
17.1
244
17.2
17.35
17
17.23
'Cbasohlcv'
'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.49
To stop collecting streaming quotes for a security, simply send the request again, this
time with 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','AAPL', '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.
48
The textual description fields depend on the MsgParsingLevel parameter having a value of 2 or higher (see §3.2 and §8)
49
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.
IQML User Guide
61
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:
Most_Recent_Trade:
Most_Recent_Trade_Size:
Most_Recent_Trade_Time:
Most_Recent_Trade_Market_Center:
...
'IBM'
142.48
41149
'17:33:40.531781'
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);
data =
1×5 struct array with fields:
Symbol
Command
isActive
...
% no symbol: return ALL streams
Similarly, to cancel all active streams in a single command, omit Symbol (or set it to ''):50
>> IQML('quotes', 'numOfEvents',0);
% no symbol: stop ALL streams
IQFeed typically allows streaming up to 500 symbols. This limit can be increased by
paying IQFeed extra. In any case, the actual maximal number of concurrentlystreaming symbols is limited by performance considerations (see §3.6).
50
Note that cancelling all active streams cancels streaming regional updates (§6.2) in addition to streaming quotes.
IQML User Guide
62
Here is a summary of the IQML parameters that directly affect streaming quotes:
Parameter
Description
Limits the request to the specified symbol(s).
Examples:
colon '@VX#'
delimited
Symbol or
string, or (none) 'IBM:AAPL:GOOG'
Symbols 51
{'IBM', 'AAPL', 'GOOG'}
cell-array
of strings
This parameter must be set to valid symbol
name(s) when NumOfEvents>0
One of:
inf – continuous endless streaming quotes for
the specified security
N>1 – stream only N quotes
1
NumOfEvents integer
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
DataType
Data type Default
integer
string
1
Number of streaming quotes stored in a cyclic
buffer. Once this number of quotes are received,
old quotes are discarded when new quotes arrive.
'q'
One of:
'q' or 'quotes' (default) – stream both trades &
quote events (top-of-book bid/ask updates)
't' or 'trades' – stream trade events only
Sets the list of data fields reported by IQFeed for
each quote. IQFeed’s default set has 16 fields;
'Symbol,
Most 50+ additional fields can be specified.
Fields
51
Recent
Trade,
Most
comma- Recent
separated Trade
string, or Size,
cell-array Most
of strings Recent
Trade
Time,
…'
(see
§4.1)
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'
'All' (indicates all available fields)
In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization
IQML User Guide
63
6.2 Regional updates
The streaming regional market updates mechanism also has two parts, just like
streaming ticks (§6.1):
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.
2. 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, let’s 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. This
means that you can continue to work with Matlab, process and display information etc.
Regional 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 152. 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 50 updates:
IQML('regional', 'Symbol','FB', 'NumOfEvents',100, 'MaxItems',50)
Note that using a large MaxItems increases memory usage, which could have an
adverse effect if you set a very large buffer size (many thousands) and/or streaming
for a large number of different securities.53
52
Note that MaxItems is a numeric parameter like NumOfEvents, so don’t enclose the parameter value within string quotes (‘’)
53
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 memory usage and performance impact remain low.
IQML User Guide
64
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
Command
isActive
EventsToProcess
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
– the requested Symbol.
– the command sent to IQFeed, including the requested Symbol.
– 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).
– total number of streaming regional updates requested
(using the NumOfEvents parameter).
to reach IQFeed and during this time a few additional update messages may
have arrived.
LatestEventDatenum – Matlab
LatestEventTimestamp.
LatestEventTimestamp
numeric datenum representation of the
– local timestamp (string format) when this update was
received by IQML.
DataType
ProcessType
BufferSize
Buffer
LatestData
– always equal to 'regional' for streaming regional updates.
– always equal to 'stream' for streaming regional updates.
– size of the data buffer (=MaxItems parameter, see below).
– buffer of size BufferSize, accumulating the latest regional updates.
– latest regional update event received from IQFeed.
IQML User Guide
65
To get the regional updates data, simply read the fields of the returned data struct:54
>> data.LatestData
ans =
RegionalBid:
RegionalBidSize:
RegionalBidTime:
RegionalAsk:
RegionalAskSize:
RegionalAskTime:
FractionDisplayCode:
DecimalPrecision:
FractionDisplayDescription:
MarketCenter:
MarketCenterDescription:
155.34
100
'12:29:45'
155.55
200
'12:29:45'
14
4
'Four decimal places'
11
'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.55
To stop collecting streaming regional updates for a security, simply send the request
again, this time with 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 ''):56
>> IQML('regional', 'numOfEvents',0); % no symbol: ALL streams are stopped
54
The textual Description fields depend on the MsgParsingLevel parameter having a value of 2 or higher (see §3.2 and §8)
55
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.
56
Note that cancelling all active streams cancels streaming quotes (§6.1) in addition to streaming regional updates.
IQML User Guide
66
Here is a summary of the IQML parameters that affect streaming regional updates:
Parameter
Data type
Default
colondelimited
string or
cell-array
of strings
(none)
NumOfEvents
integer
Inf
MaxItems
integer
1
Symbol or
Symbols 57
Description
Limits the request to the specified symbol(s).
Examples:
'@VX#'
'IBM:AAPL:GOOG'
{'IBM', 'AAPL', 'GOOG'}
This parameter must be set to valid symbol
name/names when NumOfEvents>0.
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
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.
Note: Regional updates data is only available in the Professional IQML license.
57
In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization
IQML User Guide
67
6.3 Interval bars
The streaming interval bars feature has two parts, just like streaming ticks (§6.1):
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.
2. 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.
Quotes 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,58 then up to the specified number of latest
quotes will be stored, subject to IQFeed server limitations:59
IQML('intervalbars', 'Symbol','@VX#', 'NumOfEvents',600, 'MaxItems',3)
Note 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.60
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:
58
MaxItems is a numeric parameter like NumOfEvents, so don’t enclose the parameter value within string quotes (‘’)
59
The number of reported bars may possibly be limited by the IQFeed server, depending on your data subscriptions and exchange.
60
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).
IQML User Guide
68
>> 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, simply read the fields of the returned data struct:
>> data.LatestData
ans =
Symbol:
BarType:
Timestamp:
Open:
High:
Low:
Close:
CummlativeVolume:
IntervalVolume:
NumberOfTrades:
'@VX#'
'Complete interval bar from history'
'2018-03-09 15:17:39'
17.55
17.6
17.55
17.6
4550
11
0
IQML User Guide
69
Note that data.LatestData is typically the same as data.Buffer(end), regardless of
the values of MaxItems or NumOfEvents.61
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).62
To stop collecting streaming interval bars for a security, simply send the request
again, this time with 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
Interval 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.
61
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.
62
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
IQML User Guide
70
The following parameters affect interval bars data queries:
Parameter Data type
Default
Description
Limits the request to the specified
symbol(s). Examples:
colon '@VX#'
delimited
Symbol or
'IBM:AAPL:GOOG'
string or
(none)
Symbols 63
cell-array
{'IBM', 'AAPL', 'GOOG'}
of strings
This parameter must be set to valid
symbol name(s) when NumOfEvents>0
One of:
inf – continuous endless streaming
interval bars for specified symbol(s)
N>1 – stream only N interval bars
integer
Inf
NumOfEvents
1 – get only a single interval bar
0 – stop streaming interval bars
-1 – return latest interval bars data
while continuing to stream new bars
Returns up to the specified number of
integer
100
MaxItems
bars (if available).
MaxDays
integer
1
IntervalType
string
'secs'
IntervalSize
integer
60
BeginFilterTime
EndFilterTime
string
string
Max number of trading days to retrieve
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
Size of bars in IntervalType units. Must be
≥1 for secs, ≥2 for ticks, ≥100 for volume.
'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’.
'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’.
Only return bars that begin after this
''
integer or
string or (empty string) date/time (US Eastern time-zone).
BeginDateTime datetime
meaning today Format: Matlab datenum, ‘yyyymmdd
object
at 00:00:00 hhmmss’ or ‘yyyy-mm-dd hh:mm:ss’.
Max number of seconds to wait (0-9000)
number
5.0
Timeout
for data in blocking mode (0 means infinite)
63
In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization
IQML User Guide
71
6.4 Market depth (Level 2)
The streaming market depth mechanism also has two distinct parts, just like
streaming level 1 quotes (§6.1):
1. Request IQFeed to start sending a stream of market depth quotes for a
specified security. This is done by using the 'marketdepth' action.
2. 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.
Market 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
LatestData: [1×10 struct]
LatestEventDatenum: 737195.518211377
LatestEventTimestamp: '20180515 12:26:13'
IQML User Guide
72
In the returned data struct, we can see the following fields:
Symbol
Command
EventsToProcess
EventsProcessed
LatestData
LatestEventDatenum – Matlab
LatestEventTimestamp.
LatestEventTimestamp
ProcessType
– the requested Symbol.
– the command sent to IQFeed, including the requested Symbol.
– total number of streaming interval bars requested for the
security (using the NumOfEvents parameter).
– number of streaming market depth data quotes received for
this security. When EventsProcessed >= EventsToProcess, streaming market
depth data for this security is turned off.
– latest data received by IQFeed for each market depth row.
numeric datenum representation of the
– local timestamp (string format) when latest market
depth quote was received by IQML.
– '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 =
Bid:
Ask:
BidSize:
AskSize:
BidTime:
Date:
AskTime:
BidInfoValid:
AskInfoValid:
Condition:
Condition_Description:
2725.5
2727.25
65
148
'05:25:59.761191'
'2018-05-15'
'05:25:59.760278'
1
1
52
'regular'
BidInfoValid
and AskInfoValid values are logical (true/false) values, which appear
as 1 or 0, respectively, in the struct display above.
Different market depth quotes are sent independently from IQFeed server with a
unique timestamp. Note that data.LatestEventDatenum and data.LatestEventTimestamp
are specified in the local time-zone.
To stop collecting market depth quotes for a security, simply send the request again,
this time with 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
IQML User Guide
73
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
The following parameters affect market depth data queries:
Parameter
Symbol or
Symbols 64
NumOfEvents
Data type Default
colondelimited
string or
cell-array
of strings
integer
(none)
Inf
Description
Limits the request to the specified symbol(s).
Examples:
'@ES#'
'IBM:AAPL:GOOG'
{'IBM', 'AAPL', 'GOOG'}
This parameter must be set to valid symbol
name(s) when NumOfEvents>0
One of:
inf – continuous endless streaming
market depth data for specified
symbol(s)
N>1 – stream only N incoming market
depth quotes
1 – get only a single quote
0 – stop streaming market depth data
-1 – return the latest data while
continuing to stream new data
Note: Market Depth (Level 2) data is only available in the Professional IQML license.
64
In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization
IQML User Guide
74
7 News
News headlines and stories can be retrieved via the 'news' action. Several data-types
are available, which can be set using the DataType parameter.
Note: News data is only available in the Professional IQML license.
7.1 Configuration
To retrieve the news configuration for your account, set DataType to 'config':
>> data = IQML('news', 'DataType','config')
data =
Category: 'All News'
Majors: [1×7 struct]
>> {data.Majors.Source}
ans =
1×7 cell array
{'DTN'}
{'CPR'}
{'CBW'}
{'RTT'}
{'CPZ'}
{'CIW'}
{'BEN'}
>> {data.Majors.Description}
ans =
1×7 cell array
{'DTN News'}
{'PR Newswire'}
{'Business Wire'}
{'Real-Time Trader'}
{'GlobeNewswire Inc'}
{'Marketwire'}
{'Benzinga Pro'}
This shows that we are connected to 7 major news sources. We can drill-down for
details about these news sources:
>> data.Majors(1)
ans =
Source: 'DTN'
Description: 'DTN News'
AuthenticationCode: '1D'
IconID: 10
Minors: [1×4 struct]
>> data.Majors(1).Minors(1)
ans =
Source: 'DT5'
Description: 'Treasuries, Most Actives, Gainers, Losers'
AuthenticationCode: '1D'
>> c.Majors(1).Minors(2)
ans =
Source: 'RTL'
Description: 'Derivatives - Selected Futures and Options'
AuthenticationCode: '2Ab'
IconID: 10
Note that some news sources have no “Minor” news-sources:
>> data.Majors(2)
ans =
Source:
Description:
AuthenticationCode:
IconID:
Minors:
>> data.Majors(7)
ans =
Source:
Description:
AuthenticationCode:
IconID:
Minors:
'CPR'
'PR Newswire'
'1X'
5
[1×0 struct]
'BEN'
'Benzinga Pro'
'1a'
10
[1×0 struct]
News configuration queries do not have any user-settable parameters.
IQML User Guide
75
7.2 Story headlines
To retrieve the latest news headlines (in blocking mode), set DataType to 'headlines':
>> data = IQML('news', 'DataType','headlines')
data =
1000×1 struct array with fields:
Source
ID
Symbols
Timestamp
Text
Story
>> data(1)
ans =
Source: 'CPR'
ID: 21988707473
Symbols: {}
Timestamp: 20180305064553
Text: 'The Surface Disinfectants Market is Expected to Grow at a CAGR
of 8.3% to a USD '
Story: ''
>> data(2)
ans =
Source: 'BEN'
ID: 21988707468
Symbols: {'BZFDA' 'CVRS'}
Timestamp: 20180305064533
Text: 'Corindus Receives FDA Clearance for First Automated Robotic
Movemen...'
Story: ''
>> data(3)
ans =
Source: 'RTB'
ID: 21988701358
Symbols: {'BSX'}
Timestamp: 20180305064233
Text: 'Boston Scientific Corp Q4 adjusted earnings Miss Estimates'
Story: ''
As can be seen, some stories are specific to particular symbols (BZFDA and CVRS in
story #21988707468, BSX in #21988701358), while others are not (#21988707473).
Also note that the news stories’ Timestamp is reported in yyyymmddHHMMSS
format, where the time is specified in US Eastern time-zone.
When you retrieve news headlines, you might run into a timeout problem: by default,
IQFeed send the latest 1000 news headlines and only some of them might be received
by IQML before the built-in Timeout (default: 5 secs) forces IQML to return the data
to the user (remember, this is blocking mode, where a timeout applies):
>> data = IQML('news', 'DataType','headlines')
Warning: IQML timeout: only partial data is returned: the Timeout parameter
should be set to a value larger than 5
data =
738×1 struct array with fields:
Source
ID
Symbols
Timestamp
Text
IQML User Guide
76
As suggested by the message, you can set the Timeout parameter to a high value in
order to allow IQML more time to gather the data before returning the results:
>> data = IQML('news', 'DataType','headlines', 'Timeout',10)
data =
1000×1 struct array with fields:
Source
ID
...
You can filter the headlines to a specific set of symbols by specifying Symbols as a
colon-delimited or cell-array list of symbols. For example, to filter only headlines that
relate to symbols BSX, BSX/AAPL, and BSX/AAPL/GOOG, respectively:
>> data = IQML('news', 'DataType','headlines', 'Symbols','BSX')
data =
60×1 struct array with fields:
Source
ID
...
>> data = IQML('news', 'DataType','headlines', 'Symbols',{'BSX','AAPL'})
data =
677×1 struct array with fields:
Source
ID
...
>> data = IQML('news', 'DataType','headlines', 'Symbols','BSX:AAPL:GOOG')
data =
841×1 struct array with fields:
Source
ID
...
You can also limit the search to specific news sources, by specifying a colonseparated or cell-array list of sources in the Sources parameter. For example:
>> data = IQML('news', 'DataType','headlines', 'Symbols','BSX:GOOG:AAPL', ...
'Sources','DTN:CPR:BEN')
data =
745×1 struct array with fields:
Source
ID
...
In this example, we see that when we limit our search to DTN (DTN News), CPR (PR
Newswire), and BEN (Benzinga Pro), we only get 745 headlines, compared to 841
headlines from all the news sources. The news source names are the ones reported by
the Majors.Source field, in the news configuration query (see §7.1 above).
In addition to limiting the search to a certain news source, you can also limit it to
certain meta-tags that are assigned by some news sources, using the Symbols
parameter. For example, to limit the search to “Benzinga Ratings”:
>> data = IQML('news', 'DataType','headlines', 'Symbols','BZRatings');
IQML User Guide
77
You can limit the reported headlines to only a specific date, using the Date parameter:
>> data = IQML('news', 'DataType','headlines', 'Date',20180304, ...
'Symbols',{'BSX','AAPL'})
data =
14×1 struct array with fields:
Source
ID
...
Date can be specified in multiple formats: as a Matlab datetime object, a numeric
Matlab datenum (737089), a numeric yyyymmdd value (20180129), or a string
('2018/01/29', '2018-01-29' or '20180129').
You can also limit the maximal number of reported headlines using the MaxItems
parameter. This will report the latest MaxItems news headlines (fewer headlines may
actually be reported, depending on their availability):
>> data = IQML('news', 'DataType','headlines', 'MaxItems',50)
data =
50×1 struct array with fields:
Source
ID
...
By default, only the headline text is returned. To automatically fetch the full story text
that is associated with each headline, set GetStory to true:
>> data = IQML('news', 'DataType','headlines', 'GetStory',true);
>> data(1)
ans =
Source: 'CBW'
ID: 22017456356
Symbols: {}
Timestamp: '20180524 092926'
Text: 'Global Barium Nitrate Market - Emergence of EnvironmentFriendly Ox...'
Story: '09:28 Thursday, May 24, 2018. (RTTNews.com) - Babcock & Wilcox
Enterprises, Inc. (BW) confirmed that it had received a non-binding indication
of interest from Steel Partners to acquire B&W in a transaction in which B&W
shareholders would receive between $3.00 and $3.50 per share in cash. ...
For comments and feedback: contact editorial@rttnews.com ↵Copyright(c) 2018
RTTNews.com All Rights Reserved'
Querying the story text for multiple headlines could take a long time. A rough
estimate is that 2-3 full news stories can be retrieved sequentially each second. So for
example, with 100 headlines, a news query with GetStory=true might take ~50 secs.
If you have the Professional IQML license and Matlab’s Parallel Computing Toolbox,
you can parallelize this news query by setting UseParallel to true:
>> tic
>> data = IQML('news', 'DataType','headlines', 'MaxItems',100, 'GetStory',1);
>> toc
Elapsed time is 56.311768 seconds.
>> parpool('local',4) % start 4 workers in parallel pool (optional)
>> tic
>> data = IQML('news', 'DataType','headlines', 'MaxItems',100, 'GetStory',1,...
'UseParallel',1);
>> toc
Elapsed time is 15.799185 seconds.
IQML User Guide
78
The following parameters affect (filter) news headlines queries:
Parameter Data type
Default
Description
Limits the query to the specified symbols
and meta-tags only (or to all symbols, if
empty). Examples:
''
'IBM'
(empty string),
meaning all
'IBM:AAPL:GOOG'
{'IBM', 'AAPL', 'GOOG'}
'BZRatings:BZTradingIdeas'
Symbol or
Symbols 65
colondelimited
string or
cell-array
of strings
Sources
Limits the query to the specified news
colonsources only (or to all sources, if empty).
delimited
''
Examples:
string or (empty string),
'DTN'
cell-array meaning all
'DTN:CPR:BEN'
of strings
{'DTN', 'CPR', 'BEN'}
Date
integer or
string or
datetime
[]
meaning all
Date at which the news headline was
published (or all dates, if empty). Examples:
737089 (Matlab datenum format)
20180129 (yyyymmdd format)
'20180129'
'2018/01/29'
'2018-01-29'
1000
Maximal # of headlines to be reported by
IQFeed. Note that a lower number of
headlines may be reported, depending on
their availability, based on the other filters.
object
MaxItems
integer
GetStory
logical
(true/false)
false
If false (default), only store the incoming
headline messages.
If true or 1, automatically fetch and store
the full story text for each incoming headline.
This can be parallelized using the
UseParallel parameter (see below).
Timeout
number
5.0
Max # of seconds to wait for incoming data
(0-9000, where 0 means infinite)
false
If set to true or 1, and if Parallel Computing
Toolbox is installed, then querying stories
for headlines using GetStory=true will be
done in parallel (see §3.6; Professional
IQML license only).
UseParallel
65
logical
(true/false)
In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization
IQML User Guide
79
7.3 Story text
To read a particular story in full (blocking mode), specify DataType = 'story' and ID
(numeric ID, as provided in the story-headlines query, §7.2 above). Different news
sources provide their news stories in different formats, for example:
>> data = IQML('news', 'DataType','story', 'ID',21988707468)
data =
ID: 21988707468
Symbols: {'BZFDA' 'CVRS'}
Text: 'Corindus Receives FDA Clearance for First Automated Robotic
Movement in technIQ Series for CorPath GRX Platform.'
>> data = IQML('news', 'DataType','story', 'ID',21988701358)
data =
ID: 21988701358
Symbols: {'BSX'}
Text: '06:42 Monday, March 05, 2018. (RTTNews.com) - Boston Scientific
Corp (BSX) released earnings for fourth quarter that declined
from the same period last year... % full text redacted here
Read the original article on RTTNews
(http://alpha.rttnews.com/9583/boston-scientific-corp-q4adjusted-earnings-miss-estimates.aspx) For comments and
feedback: contact editorial@rttnews.com. Copyright(c) 2018
RTTNews.com All Rights Reserved.'
In many cases, the news story is not specifically related to any particular symbol:
>> data = IQML('news', 'DataType','story', 'ID',21991159700)
data =
ID: 21991159700
Symbols: {}
Text: 'Global Nanocatalysts Strategic Business Report 2018: Market
Trends, Growth Drivers & Issues 2016-2024 ResearchAndMarkets.com. Mar. 12, 2018. Business Editors. DUBLIN-(BUSINESS WIRE)--Mar. 12, 2018--The Nanocatalysts – Global
Strategic Business Report... % full text redacted here
View source version on businesswire.com:
http://www.businesswire.com/news/home/20180312005490/en/ ...
For GMT Office Hours Call +353-1-416-8900. Related Topics:
Nanotechnology, Nanomaterials'
In some cases, the story may be assigned one or more meta-symbol tags. For
example, the following story is tagged for “Benzinga Ratings”:
>> data = IQML('news', 'DataType','story', 'ID',21991162633)
data =
ID: 21991162633
Symbols: {'BZRatings' 'MNTX'}
Text: 'Manitex International Sees Q4 Sales $64.40M vs $64.45M Est.
Manitex International (NASDAQ: MNTX) sees Q4 sales of $64.40M
vs $64.45M estimate.'
Note that separate paragraphs in the news story text are separated by a newline
(char(10)) in the reported data.Text field. This enables display of the story text in a
human-readable format, when you output the text to the Matlab console or GUI.
IQML User Guide
80
If the requested ID is invalid or does not exist, the returned data will be empty (no
error is reported):
>> IQML('news', 'DataType','story', 'ID',123456)
ans =
[]
% non-existing headline ID
Aside from ID, the news story-text query does not have any user-settable parameters.
You can specify multiple IDs in a single IQML query command, by specifying an
array of values. For example:
>> data = IQML('news', 'DataType','story', 'ID',[22018991229,22018991585])
data =
2×1 struct array with fields:
ID
Symbols
Text
>> data(1)
ans =
ID: 22018991229
Symbols: {}
Text: 'May 29, 2018 ↵Dublin, May 29, 2018 (GLOBE NEWSWIRE) -- The
European Financing in Cleantech Innovation report...
>> data(2)
ans =
ID: 22018991585
Symbols: {'BZEarnings' 'MOMO'}
Text: 'Momo Inc. Earlier Reported Q1 EPS $0.69 Beat $0.50 Estimate,
Sales $435.129M Beat $396.17M Estimate ↵Momo Inc. ...
IQML User Guide
81
7.4 Story count
It is sometimes useful to know the number of distinct news stories, from all news sources
(even those to which you are not subscribed), that relate to different symbols, indicating
level of news interest in those symbols. Set DataType to 'number' and the Symbols,
Sources and/or dates, to receive a Matlab struct with a numeric count for each symbol:
>> data = IQML('news', 'DataType','number', 'Symbols','BSX')
data =
BSX: 14
>> data = IQML('news', 'DataType','number', 'Symbols','BSX:HP:AAPL:GOOG')
data =
AAPL: 7
BSX: 14
GOOG: 2
HP: 0
In this example, we see that BSX has a higher news-count today than AAPL or GOOG.
Symbols having no news items will appear at the bottom of the struct with a count of 0.
You can limit the search to specific news sources, by specifying a colon-separated or
cell-array list of sources in the Sources parameter. For example:
>> data = IQML('news', 'DataType','number', 'Symbols','BSX:GOOG:AAPL',...
'Sources','DTN:CPR:BEN')
data =
AAPL: 2
BSX: 3
In this example, we see that when we limit our search to DTN (DTN News), CPR (PR
Newswire), and BEN (Benzinga Pro), AAPL and BSX have fewer news items, and
GOOG has none. The news source names are the ones reported by the Majors.Source
field, in the news configuration query (see §7.1 above).
You can also filter the search to only look at news items published at specific dates,
by specifying the BeginDate, EndDate and/or Date parameters. Dates can be specified
in several formats: as a Matlab datetime object, Matlab numeric datenum (737089),
numeric yyyymmdd (20180129), or string ('2018/01/29', '2018-01-29', '20180129'):
>> data = IQML('news', 'DataType','number', 'Symbols','BSX:GOOG:AAPL',...
'BeginDate',20180301)
data =
AAPL: 45
BSX: 19
GOOG: 15
>> data = IQML('news', 'DataType','number', 'Symbols','BSX:GOOG:AAPL',...
'BeginDate',20180301, 'EndDate',20180303)
data =
AAPL: 37
BSX: 3
GOOG: 13
>> data = IQML('news', 'DataType','number', 'Symbols','BSX:GOOG:AAPL',...
'EndDate',20180305)
data =
AAPL: 2038
BSX: 191
GOOG: 996
>> data = IQML('news', 'DataType','number', 'Symbols','BSX:GOOG:AAPL',...
'Date',20180301)
data =
AAPL: 16
BSX: 1
GOOG: 3
IQML User Guide
82
IQML returns a Matlab struct, so the reported symbols need to be valid field names,
and non-alphanumeric characters are automatically converted. For example:
>> data = IQML('news', 'DataType','number', 'Symbols','BOL.ST:BOL@SS:0QLL.L')
data =
x0QLL_L: 3
BOL_ST: 1
BOLxSS: 1
The following parameters affect (filter) news story-count queries:
Parameter Data type
Default
Description
Limits the query to the specified symbols
and meta-tags only (or to all symbols, if
colonempty). Examples:
delimited
''
Symbol or
'IBM'
string or (empty string),
Symbols 66
'IBM:AAPL:GOOG'
cell-array meaning all
{'IBM', 'AAPL', 'GOOG'}
of strings
'BZRatings:BZTradingIdeas'
Limits the query to the specified news
colonsources only (or to all sources, if empty).
delimited
''
Examples:
string or (empty string),
Sources
'DTN'
cell-array meaning all
'DTN:CPR:BEN'
of strings
{'DTN', 'CPR', 'BEN'}
Specific date at which the news items were
published. Examples:
737089 (Matlab datenum format)
integer or
20180129 (yyyymmdd format)
[]
string or
Date
'20180129'
datetime meaning today
object
'2018/01/29'
'2018-01-29'
Note: Date overrides BeginDate, EndDate
Earliest date at which the news items were
published. Examples:
integer or '1900/01/01'
737089 (Matlab datenum format)
string or (i.e., from as
BeginDate datetime
20180129 (yyyymmdd format)
early as data is
'20180129'
object
available)
'2018/01/29'
'2018-01-29'
Latest date at which the news items were
published. Examples:
integer or
737089 (Matlab datenum format)
'2099/12/31'
string
or
EndDate
20180129 (yyyymmdd format)
datetime (i.e., until now)
'20180129'
object
'2018/01/29'
'2018-01-29'
66
In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization
IQML User Guide
83
7.5 Streaming news headlines
The streaming news mechanism has two parts, just like streaming ticks (§6.1):
1. Request IQFeed to start sending a stream of news headlines. This is done by
using the 'news' action and setting a NumOfEvents parameter to a positive >1
value. You can limit the headlines to certain news source(s) using the Sources
parameter, and/or to certain symbol(s) using the Symbols parameter.
2. Later, whenever you wish to process the latest news headline(s), simply use
the 'news' 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 100 streaming headlines for Facebook and Apple:
IQML('news', 'Symbols','FB:AAPL', 'NumOfEvents',100)
This causes IQFeed to start sending news headlines to IQML in the background, up to
the specified NumOfEvents, without affecting normal Matlab processing. This
means that you can continue to work with Matlab, process and display information etc.
Headlines 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 §7.2:
IQML('news', 'NumOfEvents',100);
data = IQML('news', 'NumOfEvents',100);
% streaming, non-blocking
% blocking
NumOfEvents can be any number higher than 1 for streaming to work (a value of 1
is the standard snapshot news-headline request described in §7.2). To collect
streaming headlines 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 headlines are collected into an internal data buffer in IQML. Unlike streaming
quotes, all headlines, for all symbols, are collected in a single buffer. The buffer size
can be controlled using the MaxItems parameter, which has a default value of inf67.
This means that by default all the streaming headlines that affect the specified
symbols will be stored in the buffer and become accessible for later processing.68
If you set a higher value for MaxItems, then up to the specified number of latest
news headline items will be stored. For example, to store the latest 50 headlines:
IQML('news', 'NumOfEvents',100, 'MaxItems',50)
Note that using a large MaxItems increases memory usage, which could have an
adverse effect if you set a very large buffer size (many thousands) and/or streaming
for a large number of different securities.69
67
Note that this too is different from the streaming quotes mechanism, where the default MaxItems value is 1. Note that
MaxItems is a numeric parameter like NumOfEvents, so don’t enclose the parameter value within string quotes (‘’)
68
This might have a memory and performance implication if you leave streaming news on for a long time, for a large number of
symbols. See the discussion of memory and performance implications further below.
69
Each news headline item uses 1-2KB of Matlab memory. During trading hours, there could be 10-20 headlines per minute for
all symbols (i.e., 1K headlines, or 1-2MB per hour, unless you limit Symbols to certain symbols). Limiting Symbols to certain
symbols and/or setting MaxItems to some finite value, ensures that memory usage and performance impact remain low.
IQML User Guide
84
Subsequent requests to retrieve the latest accumulated headlines 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('news', 'NumOfEvents',-1)
data =
Command: 'S,NEWSON'
isActive: 1
EventsToProcess: 100
EventsProcessed: 13
LatestEventDatenum: 737146.726041343
LatestEventTimestamp: '20180327 17:25:29'
DataType: 'news'
ProcessType: 'stream'
Sources: {}
Symbols: {}
BufferSize: 50
Buffer: [13×1 struct]
LatestData: [1×1 struct]
In the returned data struct, we can see the following fields:
Command
EventsToProcess
EventsProcessed – number of streaming headlines received. When
EventsProcessed >= EventsToProcess, streaming headlines 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
– the command sent to IQFeed.70
isActive – a flag indicating whether headlines are currently being streamed.
When NumOfEvents ticks have been received, this flag is set to false (0).
– total number of streaming headlines requested (using the
NumOfEvents parameter).
to reach IQFeed and during this time a few additional items may have arrived.
70
LatestEventDatenum – Matlab
LatestEventTimestamp.
LatestEventTimestamp
DataType
ProcessType
Symbols
BufferSize
Buffer
numeric datenum representation of the
– local timestamp (string format) when this headline
was received by IQML.
– always equal to 'news' for streaming headlines.
– always equal to 'stream' for streaming headlines.
Sources – cell array of acceptable news sources, set by the Sources parameter.
Headline events from all other sources are ignored. When Sources is empty,
no headline is ignored based on its source.
– cell array of acceptable symbols, set by the Symbols parameter.
Headline events that affect all other symbols are ignored. When Symbols is
empty, no headline is ignored based on its related symbol(s).
– size of the data buffer (=MaxItems parameter, see below).
– buffer of size BufferSize, accumulating the latest headline updates.
LatestData – latest headline event received from IQFeed.
Note that this is not specific to symbols/sources: filtering based on symbol/source is done on the incoming headline messages.
IQML User Guide
85
To get the headline data, read the fields of the returned data struct, for example:
>> data.LatestData
ans =
Source: 'BEN'
ID: 21996096022
Symbols: {'BZRatings' 'FB'}
Timestamp: '20180326 083326'
Text: 'Baird Maintains Outperform on Facebook Lowers Price Target to $210'
Story: ''
Each headline has an associated timestamp, since different headlines are sent
separately and independently from IQFeed server.
By default, GetStory is set to false, resulting in empty data.LatestData.Story. To
automatically retrieve the full story text associated with each streamed headline, set
GetStory to true (see §7.2). In any case, it is always possible to retrieve individual
story texts using their headline ID (see §7.3).
Note: while data.LatestEventDatenum and data.LatestEventTimestamp are specified
in the local time-zone, data.LatestData.Timestamp is specified in the server’s time-zone.
Note that data.LatestData is typically the same as data.Buffer(end), regardless of
the values of MaxItems or NumOfEvents.71
To stop collecting streaming headlines for a security, simply send the request again,
this time with NumOfEvents=0.
You can specify one or more symbols for streaming, by specifying a colon-delimited
or cell-array list of symbols. If Symbols is specified, then any headline that does not
relate to one or more of the specified Symbols will be ignored (skipped). For example:
IQML('news', 'symbols',{'IBM','GOOG','AAPL'}, 'numOfEvents',6);
IQML('news', 'symbols','IBM:GOOG:AAPL', 'numOfEvents',6);
% equivalent
You can also specify meta-tags assigned by some news sources. For example, to limit
streaming headlines to “Benzinga Ratings” and anything related to Facebook or Apple:
IQML('news', 'Symbols','BZRatings:FB:AAPL', 'numOfEvents',6);
Note: if you omit the Symbols parameter in your IQML command, no filtering of
headlines based on affected symbols is performed, and all headlines will be collected.
Similarly, you can specify one or more news sources, by specifying a colon-delimited
or cell-array list of sources. If Sources is specified, then any headline that does not
originate from one of the specified Sources will be ignored and will not be recorded:
IQML('news', 'sources',{'DTN','CPR','BEN'}, 'numOfEvents',6);
IQML('news', 'sources','DTN:CPR:BEN', 'numOfEvents',6);
71
% equivalent
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.
IQML User Guide
86
As before, if you omit the Sources parameter in your IQML command, no filtering of
headlines based on their source will be performed, and all headlines will be collected.
Here is a summary of the IQML parameters that affect streaming news headlines:
Parameter
Data type Default
Symbol or
Symbols 72
colon''
delimited (empty
string or string),
cell-array meaning
of strings
all
Sources
colon''
delimited (empty
string or string),
cell-array meaning
of strings
all
NumOfEvents
integer
Inf
MaxItems
integer
Inf
DataType
string
'headline'
GetStory
logical
(true/false)
false
72
Description
Limits the query to the specified symbols and
meta-tags only (or to all symbols, if empty).
Examples:
'IBM'
'IBM:AAPL:GOOG'
{'IBM', 'AAPL', 'GOOG'}
'BZRatings:BZTradingIdeas'
Limits the query to the specified news sources
only (or to all sources, if empty). Examples:
'DTN'
'DTN:CPR:BEN'
{'DTN', 'CPR', 'BEN'}
One of:
inf – continuous endless streaming
headlines for the specified security
N>1 – stream only N headlines
1 – get only a single headline (default)
0 – stop streaming headlines
-1 – return the latest accumulated
headlines data while continuing to
stream new headlines data
Number of streaming headlines stored in a
cyclic buffer. Once this number of headlines
has been received, the oldest headline is
discarded whenever a new headline arrives.
Ignored – only headlines can be streamed
If false (default), only store the incoming
headline messages.
If true or 1, automatically fetch and store the
full story text for each incoming headline.
In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization
IQML User Guide
87
8 Lookup of symbols and codes
A list of symbols and lookup codes that match a specified set of criteria can be
retrieved using the 'lookup' and 'chain' actions. Various different lookups can be
requested, which differ by the DataType parameter.
8.1 Symbols lookup
To retrieve a list of symbols that match certain criteria, set the action to 'lookup',
DataType to 'symbols' and add one or more filtering criteria: Name, Description,
Market, SecType, SIC, and/or NAICS:
>> data = IQML('lookup', 'DataType','symbols', 'Name','IBM')
data =
1086×1 struct array with fields:
Symbol
Description
Market_ID
Market_Name
Sec_Type_ID
Sec_Type
>> data(1)
ans =
Symbol: 'IBM'
Description: 'INTERNATIONAL BUSINESS MACHINE'
Market_ID: 7
Market_Name: 'New York Stock Exchange (NYSE)'
Sec_Type_ID: 1
Sec_Type: 'Equity'
>> data(2)
ans =
Symbol: 'IBMG'
Description: 'ISHARES IBONDS SEP 2018 MUNI BOND'
Market_ID: 11
Market_Name: 'NYSE Archipelago (NYSE_ARCA)'
Sec_Type_ID: 1
Sec_Type: 'Equity'
>> data(9)
ans =
Symbol: 'IBM1804E120'
Description: 'IBM MAY 2018 C 120.00'
Market_ID: 14
Market_Name: 'OPRA System'
Sec_Type_ID: 2
Sec_Type: 'Index/Equity Option'
>> data(end)
ans =
Symbol: 'IBZ18-IBM19'
Description: '30 DAY INTERBANK CASH RATE DEC 18/JUN 19'
Market_ID: 64
Market_Name: 'ASX24 Commodities Exchange (ASXCM)'
Sec_Type_ID: 10
Sec_Type: 'Future Spread'
IQFeed returns a list of symbols whose symbol name contains (not necessarily begins
with) the term 'IBM', from different markets (exchanges) and different security types.
Note that the Name and Description filtering criteria are case-insensitive (so 'IBM',
'Ibm' and 'ibm' would all result in the same list of symbols), and also that they match
their string value anywhere within the corresponding asset field.
IQML User Guide
88
You can narrow-down the results by entering more-specific parameter values (e.g.
'IBM180' rather than 'IBM'), or by specifying additional filtering parameters. For
example, to filter the IBM list just to assets that include ‘business’ in their Description:
>> data = IQML('lookup', 'DataType','symbols', 'name','ibm', ...
'Description','business')
data =
8×1 struct array with fields:
Symbol
Description
Market_ID
Market_Name
Sec_Type_ID
Sec_Type
>> data = struct2table(data)
data =
8×6 table
Unlike the Name and Description (which match strings), the SIC and NAICS
parameters are numeric and match the beginning of the corresponding SIC/NAICS
sector/industry code. For example, the following query returns all assets that have
'inc' in their Description and belong to any sector whose SIC code begins with 83:73
>> data = IQML('lookup', 'DataType','symbols', 'Description','inc', 'SIC',83)
data =
6×1 struct array with fields:
Symbol
Description
Market_ID
Market_Name
Sec_Type_ID
Sec_Type
SIC_ID
SIC_Desc
>> data(1)
ans =
Symbol:
Description:
Market_ID:
Market_Name:
Sec_Type_ID:
Sec_Type:
SIC_ID:
SIC_Desc:
'HQGE'
'HQ GLOBAL ED INC'
3
'Nasdaq other OTC'
1
'Equity'
8331
'JOB TRAINING AND VOCATIONAL REHABILITATION SERVICES'
>> disp({data.Symbol; data.Description; data.SIC_ID; data.SIC_Desc}')
'HQGE' 'HQ GLOBAL ED INC'
[8331] 'JOB TRAINING AND ...'
'KVIL' 'KIDVILLE INC'
[8351] 'CHILD DAY CARE SERVICES'
'DRWN' 'A CLEAN SLATE INC.'
[8361] 'RESIDENTIAL CARE'
'NVOS' 'NOVO INTEGRATED SCIENCES INC...' [8361] 'RESIDENTIAL CARE'
'SPRV' 'SUPURVA HEALTHCARE GROUP INC...' [8361] 'RESIDENTIAL CARE'
'TLIF' 'TOCCA LIFE HOLDINGS INC. COMM'
[8361] 'RESIDENTIAL CARE'
73
In this example, the matching SIC codes were 8331 (for HQGE), 8351 (KVIL), and 8361 (DRWN, NVOS, SPRV and TLIF)
IQML User Guide
89
When you specify a SIC or NAICS filtering criteria, the result contains two
additional fields (either SIC_ID and SIC_Desc, or NAICS_ID and NAICS_Desc,
respectively), in addition to the standard fields (Symbol, Description, Market_ID,
Market_Name, Sec_Type_ID and Sec_Type).74
Note that it is possible that not all the requested symbols will be received before
IQML’s timeout (default value: 5 secs) returns the results:75
>> data = IQML('lookup', 'DataType','symbols', 'Name','GOOG')
Warning: IQML timeout: only partial data is returned: the Timeout parameter
should be set to a value larger than 5
data =
3848×1 struct array with fields:
Symbol
Description
Market_ID
Market_Name
Sec_Type_ID
Sec_Type
To control the maximal duration that IQML will wait for the data, set the Timeout
parameter. For example, to wait up to 30 secs to collect the complete list of symbols:
>> data = IQML('lookup', 'DataType','symbols', 'Name','GOOG', 'timeout',30)
data =
6812×1 struct array with fields:
...
Naturally, it is quite possible that no symbol is found that matches the requested
criteria. In such a case, the result will be empty (and cannot be displayed using
Matlab’s struct2table() or struct2cell() functions):
>> data = IQML('lookup', 'DataType','symbols', 'Description','inc', 'NAICS',83)
data =
[]
>> struct2cell(data)
Undefined function 'struct2cell' for input arguments of type 'double'.
An error message will result if you try to specify both SIC and NAICS filtering
criteria – only one (or none) of them is permitted in a lookup query:
>> data = IQML('lookup', 'DataType','symbols', 'NAICS',1234, 'SIC',83)
You can specify either SIC or NAICS parameter, but not both of them, in a
symbol lookup query
An error message will also result if you do not specify at least one of the filtering
criteria Name, Description, SIC, NAICS:
>> data = IQML('lookup', 'DataType','symbols')
Either Name, Description, SIC or NAICS parameters must be specified in a
symbol lookup query
74
The description of the various numeric codes for Market_ID, Sec_Type_ID, SIC and NAICS can be fetched separately – see
§8.3-§8.6 below for details
75
IQML can process ~1000 symbols per second; coupled with the network and server-processing latencies we can expect ~4000
symbols to accumulate before the default timeout of 5 seconds kicks in.
IQML User Guide
90
You can filter the results based on one or more markets, and/or security types, using
the Market and SecType parameters (see §8.3, §8.4 for valid values). For example:
>> struct2table(IQML('lookup', 'datatype','symbols', 'name','GOOG', 'SecType','Equity'))
ans =
2×6 table
Symbol
Description
Market_ID Market_Name
Sec_Type_ID Sec_Type
_______ ______________________ _________ ________________ ___________ ________
'GOOG' 'ALPHABET INC CLASS C' 21 'Nasdaq Global Select Market (NGSM)' 1 'Equity'
'GOOGL' 'ALPHABET INC CLASS A' 21 'Nasdaq Global Select Market (NGSM)' 1 'Equity'
>> data = IQML('lookup', 'datatype','symbols', 'name','GOOG', 'Market','NGSM');
Multiple Markets and/or SecTypes76 can be specified using a cell array. For
example, to get the list of all active (non-expired) GOOG equities and options:77
>> data = IQML('lookup', 'datatype','symbols', 'name','GOOG', ...
'SecTypes',{'Equity','IEOption'}, 'Timeout',20)
data =
8056×1 struct array with fields:
Symbol
Description
Market_ID
Market_Name
Sec_Type_ID
Sec_Type
You can specify both Market(s) and SecType(s) to get an even more granular
filtering. For example, to lookup only future options traded on CBOT:
>> data = IQML('lookup', 'datatype','symbols', 'name',symbol, ...
'SecTypes','FOption', ‘Markets','CBOT');
Similarly, to lookup VIX (volatility) futures and future-spreads (but not combined
future volume OI symbols such as @VX1.OI.Z) on the CBOE Futures Exchange (CFE):
>> data = IQML('lookup', 'datatype','symbols', 'name','vx', ...
'SecTypes',{'Future','Spread'}, 'Markets','CFE');
If you specify one or more invalid Market(s) or SecType(s), you will get an error.
For example, a typical error is to specify a SecType of 'Option' instead of 'IEOption':
>> d = IQML('lookup','datatype','symbols','name','GOOG','SecTypes',{'Equity','Option'})
Invalid SecType(s) "OPTION". Allowed values: ARGUS, ARGUSFC, BONDS, CALC,
COMBINED_FOPTION, COMBINED_FUTURE, COMM3, EQUITY, FAST_RACKS, FOPTION,
FOPTION_IV, FOREX, FORWARD, FUTURE, ICSPREAD, IEOPTION, INDEX, ISO, JACOBSEN,
MKTRPT, MKTSTATS, MONEY, MUTUAL, NP_CAPACITY, NP_FLOW, NP_POWER,
PETROCHEMWIRE, PRECMTL, RACKS, RFSPOT, SNL_ELEC, SNL_NG, SPOT, SPREAD,
STRATSPREAD, STRIP, SWAPS, TREASURIES
Instead of Market name(s) or SecType name(s), you can specify their corresponding
numeric codes,78 as a scalar integer value or as a numeric array of integers:
>> data = IQML('lookup','datatype','symbols','name','GOOG','SecTypes',1);
>> data = IQML('lookup','datatype','symbols','name','GOOG','SecTypes',[1,2]);
>> data = IQML('lookup','datatype','symbols','name','GOOG','Markets',21);
>> data = IQML('lookup','datatype','symbols','name','GOOG',’Markets',[21,14]);
76
Note that you can use either Market or Markets as the parameter name, and similarly, either SecType or SecTypes.
77
IQFeed only returns the symbols of active (non-expired) options/futures. See §8.2 below for details about expired contracts.
78
See §8.3 and §8.4 for the list of numeric codes that correspond to each market and security type
IQML User Guide
91
Here is a summary of the IQML parameters that affect symbols lookup:
Parameter
Data type
Name
string
Description
string
Market or
Markets 79
Default
Description
''
Limits the query to assets that contain the
(empty specified string in their symbol name (case
string) insensitive, anywhere within the symbol name)
''
Limits the query to assets that contain the
(empty specified string in their description (case
string) insensitive, anywhere within the description)
Limits the query to assets that belong to the
integer,
specified market code(s) (scalar integer or
numeric array,
[]
numeric array), or market name(s) (casestring, or cell- (empty) insensitive string or cell-array of strings).
array of strings
See §8.3 for details on valid values.
Limits the query to assets that have the
integer,
specified security type code(s) (scalar integer
SecType or numeric array,
[]
or numeric array), or security type name(s)
SecTypes 80 string, or cell- (empty) (case-insensitive string or cell-array of strings).
array of strings
See §8.4 for details on valid values.
integer
Limits the query to assets that belong to the
specified SIC sector/industry
[]
(empty) (matches the beginning of the SIC number)
See §8.5 for details on valid values.
NAICS
integer
Limits the query to assets that belong to the
specified NAICS sector/industry
[]
(empty) (matches the beginning of the NAICS number)
See §8.6 for details on valid values.
Timeout
number
SIC
5.0
Max # of seconds to wait for incoming data
(0-9000, where 0 means infinite)
79
In IQML, the Market and Markets parameters are synonymous – you can use either of them, in any capitalization
80
In IQML, the SecType and SecTypes parameters are synonymous – you can use either of them, in any capitalization
IQML User Guide
92
8.2 Options/futures chain
To retrieve a list of symbols that belong to a certain options/futures chain and match
certain criteria, set the action to 'chain'; DataType to one of 'options' (default),
'futures', 'foptions' (future options), or 'spreads'; Symbol to the underlying contract’s
symbol; and then add optional filtering criteria. For example:81
>> symbols = IQML('chain', 'Symbol','GOOG')' % options chain for GOOG
symbols =
1×1454 cell array
Columns 1 through 4
'GOOG1803H1000'
'GOOG1803H1010'
'GOOG1803H1020'
'GOOG1803H1030'
Columns 5 through 8
'GOOG1803H1040'
'GOOG1803H1050'
'GOOG1803H1055'
'GOOG1803H1060'
Columns 9 through 12
'GOOG1803H1065'
'GOOG1803H1070'
'GOOG1803H1075'
'GOOG1803H1077.5'
...
All chain queries support the Symbol, Months, Years, and NearMonths parameters
(filtering criteria – see table below). The options-related chain queries (DataType=
'options' or 'foptions') also support a Side parameter ('cp' (default), 'c' or 'p' – to limit
the reported options to calls and/or puts). In addition, the index/equity options chain
query (DataType='options') also supports IncludeBinary, MinStrike/MaxStrike
and NumInMoney/NumOutOfMoney filtering parameters. For example:
% Report GOOG options having strike price between $1000-$1010 in next 4 months
>> symbols = IQML('chain', 'symbol','goog', 'NearMonths',4, ...
'MinStrike',1000, 'MaxStrike',1010)'
symbols =
1×58 cell array
Columns 1 through 4
'GOOG1803H1000'
'GOOG1803H1010'
'GOOG1810H1000'
'GOOG1810H1005'
Columns 5 through 8
'GOOG1810H1010'
'GOOG1813G1000'
'GOOG1813G1002.5' 'GOOG1813G1005'
Columns 9 through 12
'GOOG1813G1007.5'
'GOOG1813G1010'
'GOOG1817H1000'
'GOOG1817H1005'
...
Note that if you filter by MinStrike and/or MaxStrike, you cannot also filter by
NumInMoney/ NumOutOfMoney (and vice versa):
>> IQML('chain', 'symbol','FB','NumInMoney',2,'NumOutOfMoney',2,'MinStrike',90)
You cannot specify both a strike range and number of contracts in/out of money
in 'chain' query - choose only one set
Similarly, you can only specify one of the Months, NearMonths parameters, not both:
>> IQML('chain', 'symbol','FB', 'Months',2:6, 'NearMonths',3)
Either the Months or the NearMonths parameter can be specified, but not both,
in a 'chain' query
If no symbols match the specified criteria, or if you do not have the necessary market
permissions (subscription), then the IQML query will return an empty cell array:
>> symbols = IQML('chain', 'datatype','spreads','symbol','C','years',2010:2019)
symbols =
0×0 empty cell array
81
The option contract names in IQFeed use a variant of the OPRA OSI format. See
http://www.iqfeed.net/symbolguide/index.cfm?symbolguide=guide&displayaction=support%C2%A7ion=guide&web=iqfeed
&guide=options&web=IQFeed&type=stock. Note that the name might change when corporate actions (such as splits) occur,
for example: BBD1918A15 vs. BBD11918A15.45 (http://forums.iqfeed.net/index.cfm?page=topic&topicID=5495).
IQML User Guide
93
Note: IQFeed only returns active (non-expired) contracts. IQFeed does not currently
provide similar lookup functionality for expired options/futures. However, a [huge] static
text file containing a [very long] list of expired symbols is available for download.82
If you set the optional WhatToShow parameter to 'quotes', you will receive an array
of structs that contain the corresponding latest (top-of-market) quotes data for the
corresponding symbols. For example:
>> data = IQML('chain', 'symbol','GOOG', 'NearMonths',4, ...
'MinStrike',1000, 'MaxStrike',1010, ...
'WhatToShow','quotes')
data =
58×1 struct array with fields:
Symbol
Most_Recent_Trade
Most_Recent_Trade_Size
Most_Recent_Trade_Time
Most_Recent_Trade_Market_Center
Total_Volume
Bid
Bid_Size
Ask
Ask_Size
Open
High
Low
Close
...
>> data(1)
ans =
struct with fields:
Symbol: 'GOOG1803H1000'
Most_Recent_Trade: 120
Most_Recent_Trade_Size: 1
Most_Recent_Trade_Time: '15:57:12.930497'
Most_Recent_Trade_Market_Center: 156
Total_Volume: 0
Bid: 140.5
Bid_Size: 3
Ask: 150.1
Ask_Size: 1
Open: []
High: []
Low: []
Close: 120
Message_Contents: 'Cbacv'
Message_Description: 'Last qualified trade; A bid update occurred;
An ask update occurred; A close declaration occurred; A volume update occurred'
Most_Recent_Trade_Conditions: 1
Trade_Conditions_Description: 'Normal Trade'
Most_Recent_Market_Name: 'MIAX PEARL Options exchange'
>> symbols = {data.Symbol}
symbols =
1×58 cell array
Columns 1 through 4
'GOOG1803H1000'
'GOOG1803H1010'
Columns 5 through 8
'GOOG1810H1010'
'GOOG1813G1000'
...
82
'GOOG1810H1000'
'GOOG1810H1005'
'GOOG1813G1002.5'
'GOOG1813G1005'
ftp://www.dtniq.com/beta/IEOPTION.zip. See http://forums.iqfeed.net/index.cfm?page=topic&topicID=3326 for details.
IQML User Guide
94
Note: if you request quotes for multiple chain symbols, especially if you set UseParallel
to true, you might reach your IQFeed account’s symbols-limit (MaxSymbols; see §9.3).
In such cases, IQFeed-generated error messages will be displayed on the Matlab console:
Level1 symbol limit reached - symbol 'GOOG2019R600' not serviced!
Also note that some of these structs (especially for out-of-money contracts) may contain
empty/invalid data, since their corresponding contract was never traded. For example:
>> data(7)
ans =
struct with fields:
Symbol:
Most_Recent_Trade:
Most_Recent_Trade_Size:
Most_Recent_Trade_Time:
Most_Recent_Trade_Market_Center:
Total_Volume:
Bid:
Bid_Size:
Ask:
Ask_Size:
Open:
High:
Low:
Close:
Message_Contents:
Message_Description:
occurred; A volume update occurred'
Most_Recent_Trade_Conditions:
Trade_Conditions_Description:
Most_Recent_Market_Name:
'GOOG1813G1002.5'
[]
[]
[]
[]
0
133.4
2
140.2
1
[]
[]
[]
[]
'bav'
'A bid update occurred; An ask update
1
'Normal Trade'
''
For this reason, you should be careful when concatenating the struct array’s data into
numeric arrays. In this example, only 40 of the 58 contracts had a Close price, so
concatenating into a numeric array results in an array that only has 40 data items:
>> [data.Close]
ans =
Columns 1 through 8
120
130.7
140.67
Columns 9 through 16
103.28
130.9
179.5
Columns 17 through 24
6
7.5
5.3
Columns 25 through 32
1.05
5.56
9.9
Columns 33 through 40
15.43
16.33
27.21
131.99
150.1
138.8
139.5
99.47
137.5
190.17
89.3
145
3.84
7.14
0.3
0.3
1.1
1.32
6.35
0.67
0.75
1.23
10
32.3
33.4
6.49
2.5
3.37
…instead, it is better in most cases to use cell arrays, where we can see empty cells:
>> {data.Close}
ans =
1×58 cell array
Columns 1 through 8
[120]
[]
[130.7]
[]
[]
[140.67]
[]
[]
Columns 9 through 16
[]
[]
[131.99]
[150.1]
[138.8]
[139.5]
[]
Columns 17 through 24
[]
[103.28]
[130.9]
[179.5]
[137.5]
[190.17]
Columns 25 through 33
...
[99.47]
[]
[89.3]
IQML User Guide
95
Similarly, set WhatToShow='fundamental' to get the fundamental data for all
symbols in the requested chain. For example:
>> data = IQML('chain', 'symbol','GOOG', 'NearMonths',4, ...
'MinStrike',1000, 'MaxStrike',1010, ...
'WhatToShow','fundamental')
data =
58×1 struct array with fields:
Symbol
Exchange_ID
PE
Average_Volume
x52_Week_High
x52_Week_Low
Calendar_Year_High
Calendar_Year_Low
...
>> data(1)
ans =
struct with fields:
Symbol:
Exchange_ID:
PE:
Average_Volume:
x52_Week_High:
x52_Week_Low:
Calendar_Year_High:
Calendar_Year_Low:
...
Fiscal_Year_End:
Company_Name:
...
Expiration_Date:
Strike_Price:
NAICS:
Exchange_Root:
Option_Premium_Multiplier:
Option_Multiple_Deliverable:
Price_Format_Description:
Exchange_Description:
Listed_Market_Description:
Security_Type_Description:
SIC_Description:
NAICS_Description:
>> [data.Strike_Price]
ans =
Columns 1 through 8
1000
1010
1000
Columns 9 through 16
1007.5
1010
1000
Columns 17 through 24
1007.5
1010
1000
Columns 25 through 32
1000
1005
1010
Columns 33 through 40
1005
1010
1000
Columns 41 through 48
1005
1010
1000
Columns 49 through 56
1005
1010
1000
Columns 57 through 58
1000
1010
'GOOG1803H1000'
'E'
[]
[]
120
120
[]
[]
[]
'GOOG AUG 2018 C 1000.00'
'08/03/2018'
1000
[]
[]
100
0
'Two decimal places'
'Euronext Index Derivatives (ENID)'
'OPRA System'
'Index/Equity Option'
''
''
1005
1010
1000
1002.5
1005
1005
1010
1000
1002.5
1005
1005
1010
1000
1005
1010
1000
1010
1000
1010
1000
1002.5
1005
1007.5
1010
1000
1002.5
1005
1007.5
1010
1000
1005
1010
1000
1005
1010
IQML User Guide
96
Here is a summary of the IQML parameters that affect chain symbols lookup:
Parameter Data type Default
Description
Symbol name of the underlying contract.
''
This is a mandatory parameter – it must be set.
string
Symbol
must be set! Note: Multiple symbols are NOT supported.
One of:
'options' (default) – on index/equity
'future'
string
'options'
DataType
'spread' – future calendar spreads
'foptions' – options on future
One of:
'cp'
'cp' (default) – both calls and puts
(meaning
'c' – calls only
string
Side
both calls
'p' – puts only
and puts) Only relevant if DataType='options'/'foptions'
One of:
'symbols' (default) – list of symbols in chain
'symbols'
WhatToShow string
'quotes' – return the latest quotes data
'fundamental' – return fundamental data
One of:
Numeric month value(s) between 1-12
(e.g.: 4, 2:5, [1,4,7])
English month name (e.g. 'August', 'Apr')
[] meaning
English month names in cell array (e.g.
various
Months
all
{'Apr', 'July', 'September', 'Dec'})
Financial month codes from the list
FGHJKMNQUVXZ (e.g. 'JKMN')
Cannot be specified together with NearMonths
integer
Number of nearby contract months to report.83
[]
NearMonths
Cannot be specified together with Months.
(0-99)
[]
meaning
One or more years (e.g. 2013:2019).
integer
Years
scalar/array current year Default = current year.
If true (default), then binary options are
true or 1 reported, otherwise not. This parameter is
IncludeBinary logical
only relevant when DataType='options'.
Only report options having a higher strike price;
number
[]
MinStrike
only relevant when DataType='options'.
Only report options having a lower strike price;
number
[]
MaxStrike
only relevant when DataType='options'.
Only report this number of options in the
[]
NumInMoney integer
money; only relevant if DataType='options'.
NumOutOf
Only report this number of options out of
integer
[]
money; only relevant if DataType='options'.
Money
logical
If set to true or 1, then querying chain quotes
false
UseParallel
will be done in parallel if possible (see §3.6).
(true/false)
Note: Options/futures chain lookup is only available in the Professional IQML license.
83
IQFeed officially supports only 0-4, but in practice higher values are accepted, reporting contracts that expire farther out in the
future (for example, 2.5 years for SPX). Note that this is undocumented IQFeed behavior, so specifying a value of 5 or higher
may possibly not work properly (or at all) in certain cases. See http://forums.iqfeed.net/index.cfm?page=topic&topicID=5508
IQML User Guide
97
8.3 Markets lookup
To retrieve a list of markets (exchanges), set the action to 'lookup' and DataType to
'markets':
>> data = IQML('lookup', 'DataType','markets')
data =
474×1 struct array with fields:
id
name
description
groupId
groupName
>> data(1)
ans =
id:
name:
description:
groupId:
groupName:
1
'NGM'
'Nasdaq Global Market'
5
'NASDAQ'
>> data(2)
ans =
id:
name:
description:
groupId:
groupName:
2
'NCM'
'National Capital Market'
5
'NASDAQ'
You can convert the data into a [perhaps] more readable form using Matlab’s builtin
struct2cell() and struct2table() functions:
>> struct2cell(data)'
ans =
9×5 cell array
[1] 'NGM'
[2] 'NCM'
[3] 'OTC'
[4] 'OTCBB'
[5] 'NASDAQ'
[6] 'NYSE_AMERICAN'
[7] 'NYSE'
[8] 'CHX'
[9] 'PHLX'
...
>> struct2table(data)
ans =
9×5 table
id
name
__ _______________
1 'NGM'
2 'NCM'
3 'OTC'
4 'OTCBB'
5 'NASDAQ'
6 'NYSE_AMERICAN'
7 'NYSE'
8 'CHX'
9 'PHLX'
'Nasdaq Global Market'
'National Capital Market'
'Nasdaq other OTC'
'Nasdaq OTC Bulletin Board'
'Nasdaq'
'NYSE American (Equities and Bonds)'
'New York Stock Exchange'
'Chicago Stock Exchange'
'Philadelphia Stock Exchange'
[5]
[5]
[5]
[5]
[5]
[6]
[7]
[0]
[0]
'NASDAQ'
'NASDAQ'
'NASDAQ'
'NASDAQ'
'NASDAQ'
'NYSE_AMERICAN'
'NYSE'
'NONE'
'NONE'
description
groupId
groupName
____________________________________ _______ _____________
'Nasdaq Global Market'
5
'NASDAQ'
'National Capital Market'
5
'NASDAQ'
'Nasdaq other OTC'
5
'NASDAQ'
'Nasdaq OTC Bulletin Board'
5
'NASDAQ'
'Nasdaq'
5
'NASDAQ'
'NYSE American (Equities and Bonds)'
6
'NYSE_AMERICAN'
'New York Stock Exchange'
7
'NYSE'
'Chicago Stock Exchange'
0
'NONE'
'Philadelphia Stock Exchange'
0
'NONE'
IQML User Guide
98
You can narrow-down the results by specifying the Name and/or the Description
filtering parameters. For example, let’s display only the markets that have ‘Nasdaq’ in
their Description:
>> data = IQML('lookup', 'DataType','markets', 'Description','Nasdaq')
data =
10×1 struct array with fields:
id
name
description
groupId
groupName
>> disp(struct2cell(data)')
[ 1] 'NGM'
'Nasdaq Global Market'
[ 3] 'OTC'
'Nasdaq other OTC'
[ 4] 'OTCBB'
'Nasdaq OTC Bulletin Board'
[ 5] 'NASDAQ'
'Nasdaq'
[ 15] 'NASD_ADF' 'Nasdaq Alternate Display facility'
[ 19] 'NTRF'
'Nasdaq Trade Reporting Facility'
[ 21] 'NGSM'
'Nasdaq Global Select Market'
[105] 'PK_NASDAQ' 'Pink Sheets - NASDAQ Listed'
[134] 'N2EX'
'NASDAQ OMX-Nord Pool'
[139] 'NFX'
'NASDAQ OMX Futures'
[ 5]
[ 5]
[ 5]
[ 5]
[ 5]
[ 5]
[ 5]
[ 90]
[134]
[139]
'NASDAQ'
'NASDAQ'
'NASDAQ'
'NASDAQ'
'NASDAQ'
'NASDAQ'
'NASDAQ'
'PK_SHEETS'
'N2EX'
'NFX'
Naturally, it is quite possible that no markets exist that match the requested criteria. In
such a case, the result will be empty (and cannot be displayed using Matlab’s
struct2table() or struct2cell() functions):
>> data = IQML('lookup', 'DataType','markets', 'Name','xyz')
data =
[]
>> struct2cell(data)
Undefined function 'struct2cell' for input arguments of type 'double'.
Here is a summary of the IQML parameters that affect markets lookup:
Parameter
Name
Description
Data type Default
Description
''
Limits the query to markets that contain the
string
(empty specified string in their name or groupName
string) (case insensitive, anywhere within the name)
string
''
Limits the query to markets that contain the
(empty specified string in their description (case
string) insensitive, anywhere within the description)
IQML User Guide
99
8.4 Security types lookup
To retrieve a list of security types, set action to 'lookup' and DataType to 'sectypes':
>> data = IQML('lookup', 'DataType','sectypes')
data =
38×1 struct array with fields:
id
name
>> data(1)
ans =
id: 1
name: 'EQUITY'
description: 'Equity'
>> data(2)
ans =
id: 2
name: 'IEOPTION'
description: 'Index/Equity Option'
You can convert the data into a [perhaps] more readable form using Matlab’s builtin
struct2cell() and struct2table() functions:
>> disp(struct2cell(data)')
[ 1] 'EQUITY'
[ 2] 'IEOPTION'
[ 3] 'MUTUAL'
[ 4] 'MONEY'
[ 5] 'BONDS'
[ 6] 'INDEX'
[ 7] 'MKTSTATS'
[ 8] 'FUTURE'
[ 9] 'FOPTION'
[10] 'SPREAD'
[11] 'SPOT'
[12] 'FORWARD'
[13] 'CALC'
[14] 'STRIP'
[16] 'FOREX'
[17] 'ARGUS'
[18] 'PRECMTL'
[19] 'RACKS'
[20] 'RFSPOT'
[21] 'ICSPREAD'
[22] 'STRATSPREAD'
[23] 'TREASURIES'
[24] 'SWAPS'
[25] 'MKTRPT'
[26] 'SNL_NG'
[27] 'SNL_ELEC'
[28] 'NP_CAPACITY'
[29] 'NP_FLOW'
[30] 'NP_POWER'
[31] 'COMM3'
[32] 'JACOBSEN'
[33] 'ISO'
[34] 'FAST_RACKS'
[35] 'COMBINED_FUTURE'
[36] 'COMBINED_FOPTION'
[37] 'ARGUSFC'
[38] 'PETROCHEMWIRE'
[39] 'FOPTION_IV'
'Equity'
'Index/Equity Option'
'Mutual Fund'
'Money Market Fund'
'Bond'
'Index'
'Market Statistic'
'Future'
'Future Option'
'Future Spread'
'Spot'
'Forward'
'DTN Calculated Statistic'
'Calculated Future Strip'
'Foreign Monetary Exchange'
'Argus Energy'
'Precious Metals'
'Racks Energy'
'Refined Fuel Spot'
'Inter-Commodity Future Spread'
'Strategy Spread'
'Treasuries'
'Interest Rate Swap'
'Market Reports'
'SNL Natural Gas'
'SNL Electricity'
'Nord Pool-N2EX Capacity'
'Nord Pool-N2EX Flow'
'Nord Pool-N2EX Power Prices'
'Commodity 3'
'The Jacobsen'
'Independent Systems Operator Data (Genscape)'
'Fast Racks (Racks On Wheels)'
'Combined Future Volume OI'
'Combined FOption Volume OI'
'Argus Forward Curve'
'PetroChemWire'
'FOption Implied Volatility'
IQML User Guide
>> disp(struct2table(data))
id
name
__
__________________
1
'EQUITY'
2
'IEOPTION'
3
'MUTUAL'
4
'MONEY'
5
'BONDS'
6
'INDEX'
7
'MKTSTATS'
8
'FUTURE'
9
'FOPTION'
10
'SPREAD'
11
'SPOT'
12
'FORWARD'
...
100
description
______________________________________________
'Equity'
'Index/Equity Option'
'Mutual Fund'
'Money Market Fund'
'Bond'
'Index'
'Market Statistic'
'Future'
'Future Option'
'Future Spread'
'Spot'
'Forward'
You can narrow-down the results by specifying the Name and/or the Description
filtering parameters. For example, let’s display only security types that have ‘Option’
in their Description:
>> struct2table(IQML('lookup', 'DataType','sectypes', 'Description','option'))
ans =
4×3 table
id
name
description
__
__________________
____________________________
2
'IEOPTION'
'Index/Equity Option'
9
'FOPTION'
'Future Option'
36
'COMBINED_FOPTION'
'Combined FOption Volume OI'
39
'FOPTION_IV'
'FOption Implied Volatility'
Naturally, it is quite possible that no security types exist that match the requested
criteria. In such a case, the result will be empty (and cannot be displayed using
Matlab’s struct2table() or struct2cell() functions):
>> data = IQML('lookup', 'DataType','sectypes', 'Name','xyz')
data =
[]
>> struct2cell(data)
Undefined function 'struct2cell' for input arguments of type 'double'.
Here is a summary of the IQML parameters that affect security types lookup:
Parameter
Name
Description
Data type Default
''
string
(empty
string)
''
string
(empty
string)
Description
Limits the query to secTypes that contain the
specified string in their name
(case insensitive, anywhere within the name)
Limits the query to secTypes that contain the
specified string in their description (case
insensitive, anywhere within the description)
IQML User Guide
101
8.5 SIC codes lookup
To retrieve a list of SIC sectors/industries, set action to 'lookup' and DataType to 'SIC':
>> data = IQML('lookup', 'DataType','SIC')
data =
1009×1 struct array with fields:
id
description
>> data(1)
ans =
id: 111
description: 'WHEAT'
>> data(2)
ans =
id: 112
description: 'RICE'
You can convert the data into a [perhaps] more readable form using Matlab’s builtin
struct2cell() and struct2table() functions:
>> disp(struct2cell(data)')
[111]
[112]
[115]
[116]
[119]
[131]
[132]
[133]
[134]
[139]
[161]
[171]
[172]
[173]
[174]
[175]
[179]
...
'WHEAT'
'RICE'
'CORN'
'SOYBEANS'
'CASH GRAINS, NOT ELSEWHERE CLASSIFIED'
'COTTON'
'TOBACCO'
'SUGARCANE AND SUGAR BEETS'
'IRISH POTATOES'
'FIELD CROPS, EXCEPT CASH GRAINS, NOT ELSEWHERE CLASSIFIED'
'VEGETABLES AND MELONS'
'BERRY CROPS'
'GRAPES'
'TREE NUTS'
'CITRUS FRUITS'
'DECIDUOUS TREE FRUITS'
'FRUITS AND TREE NUTS, NOT ELSEWHERE CLASSIFIED'
>> disp(struct2table(data))
id
description
___
___________________________________________________________
111
'WHEAT'
112
'RICE'
115
'CORN'
116
'SOYBEANS'
119
'CASH GRAINS, NOT ELSEWHERE CLASSIFIED'
131
'COTTON'
132
'TOBACCO'
133
'SUGARCANE AND SUGAR BEETS'
134
'IRISH POTATOES'
139
'FIELD CROPS, EXCEPT CASH GRAINS, NOT ELSEWHERE CLASSIFIED'
161
'VEGETABLES AND MELONS'
171
'BERRY CROPS'
172
'GRAPES'
173
'TREE NUTS'
174
'CITRUS FRUITS'
175
'DECIDUOUS TREE FRUITS'
179
'FRUITS AND TREE NUTS, NOT ELSEWHERE CLASSIFIED'
...
IQML User Guide
102
You can narrow-down the results by specifying the Description filtering parameter.
For example, let’s display only security types that have ‘Oil’ in their Description:
>> struct2table(IQML('lookup', 'DataType','SIC', 'Description','oil'))
ans =
22×2 table
id
description
____
___________________________________________________________________
251
'BROILER, FRYER, AND ROASTER CHICKENS'
711
'SOIL PREPARATION SERVICES'
1381
'DRILLING OIL AND GAS WELLS'
1382
'OIL AND GAS FIELD EXPLORATION SERVICES'
1389
'OIL AND GAS FIELD SERVICES, NOT ELSEWHERE CLASSIFIED'
2074
'COTTONSEED OIL MILLS'
2075
'SOYBEAN OIL MILLS'
2076
'VEGETABLE OIL MILLS, EXCEPT CORN, COTTONSEED, AND SOYBEAN'
2077
'ANIMAL AND MARINE FATS AND OILS'
2079
'SHORTENING, TABLE OILS, MARGARINE, AND OTHER EDIBLE FATS AND OILS'
2673
'PLASTICS, FOIL, AND COATED PAPER BAGS'
2843
'SURFACE ACTIVE AGENTS, FINISHING AGENTS, SULFONATED OILS, AND ASS'
2844
'PERFUMES, COSMETICS, AND OTHER TOILET PREPARATIONS'
2992
'LUBRICATING OILS AND GREASES'
3353
'ALUMINUM SHEET, PLATE, AND FOIL'
3443
'FABRICATED PLATE WORK (BOILER SHOPS)'
3497
'METAL FOIL AND LEAF'
3532
'MINING MACHINERY AND EQUIPMENT, EXCEPT OIL AND GAS FIELD MACHINER'
3533
'OIL AND GAS FIELD MACHINERY AND EQUIPMENT'
3677
'ELECTRONIC COILS, TRANSFORMERS, AND OTHER INDUCTORS'
5983
'FUEL OIL DEALERS'
6792
'OIL ROYALTY TRADERS'
Naturally, it is quite possible that no security types exist that match the requested
criteria. In such a case, the result will be empty (and cannot be displayed using
Matlab’s struct2table() or struct2cell() functions):
>> data = IQML('lookup', 'DataType','SIC', 'Description','xyz')
data =
[]
>> struct2cell(data)
Undefined function 'struct2cell' for input arguments of type 'double'.
Here is a summary of the IQML parameters that affect SIC codes lookup:
Parameter
Description
Data type Default
Description
Limits the query to SIC entries that contain the
''
string
(empty specified string in their description (case
string) insensitive, anywhere within the description)
IQML User Guide
103
8.6 NAICS codes lookup
To retrieve a list of NAICS sectors/industries, set the action to 'lookup' and DataType
to 'NAICS':
>> data = IQML('lookup', 'DataType','NAICS')
data =
1175×1 struct array with fields:
id
description
>> data(1)
ans =
id: 111110
description: 'Soybean Farming'
>> data(2)
ans =
id: 111120
description: 'Oilseed (except Soybean) Farming'
You can convert the data into a [perhaps] more readable form using Matlab’s builtin
struct2cell() and struct2table() functions:
>> disp(struct2cell(data)')
[111110]
'Soybean Farming'
[111120]
'Oilseed (except Soybean) Farming'
[111130]
'Dry Pea and Bean Farming'
[111140]
'Wheat Farming'
[111150]
'Corn Farming'
[111160]
'Rice Farming'
[111191]
'Oilseed and Grain Combination Farming'
[111199]
'All Other Grain Farming'
[111211]
'Potato Farming'
[111219]
'Other Vegetable (except Potato) and Melon Farming'
[111310]
'Orange Groves'
[111320]
'Citrus (except Orange) Groves'
[111331]
'Apple Orchards'
[111332]
'Grape Vineyards'
[111333]
'Strawberry Farming'
[111334]
'Berry (except Strawberry) Farming'
[111335]
'Tree Nut Farming'
...
>> disp(struct2table(data))
id
description
______
___________________________________________________
111110
'Soybean Farming'
111120
'Oilseed (except Soybean) Farming'
111130
'Dry Pea and Bean Farming'
111140
'Wheat Farming'
111150
'Corn Farming'
111160
'Rice Farming'
111191
'Oilseed and Grain Combination Farming'
111199
'All Other Grain Farming'
111211
'Potato Farming'
111219
'Other Vegetable (except Potato) and Melon Farming'
111310
'Orange Groves'
111320
'Citrus (except Orange) Groves'
111331
'Apple Orchards'
111332
'Grape Vineyards'
111333
'Strawberry Farming'
111334
'Berry (except Strawberry) Farming'
111335
'Tree Nut Farming'
...
IQML User Guide
104
You can narrow-down the results by specifying the Description filtering parameter.
For example, let’s display only security types that have ‘Oil’ in their Description:
>> struct2table(IQML('lookup', 'DataType','NAICS', 'Description','oil'))
ans =
20×2 table
id
description
______ ____________________________________________________________________
111120 'Oilseed (except Soybean) Farming'
111191 'Oilseed and Grain Combination Farming'
112320 'Broilers and Other Meat Type Chicken Production'
115112 'Soil Preparation, Planting, and Cultivating'
213111 'Drilling Oil and Gas Wells'
213112 'Support Activities for Oil and Gas Operations'
237120 'Oil and Gas Pipeline and Related Structures Construction'
311223 'Other Oilseed Processing'
311225 'Fats and Oils Refining and Blending'
322225 'Laminated Aluminum Foil Manufacturing for Flexible Packaging Uses'
324191 'Petroleum Lubricating Oil and Grease Manufacturing'
325620 'Toilet Preparation Manufacturing'
84
331315 ' Aluminum Sheet, Plate, and Foil Manufacturing'
332410 'Power Boiler and Heat Exchanger Manufacturing'
333132 'Oil and Gas Field Machinery and Equipment Manufacturing'
334416 'Electronic Coil, Transformer, and Other Inductor Manufacturing'
423810 'Construction and Mining (except Oil Well) Machinery and Equipment…'
454311 'Heating Oil Dealers'
486110 'Pipeline Transportation of Crude Oil'
811191 'Automotive Oil Change and Lubrication Shops'
Naturally, it is quite possible that no security types exist that match the requested
criteria. In such a case, the result will be empty (and cannot be displayed using
Matlab’s struct2table() or struct2cell() functions):
>> data = IQML('lookup', 'DataType','NAICS', 'Description','xyz')
data =
[]
>> struct2cell(data)
Undefined function 'struct2cell' for input arguments of type 'double'.
Here is a summary of the IQML parameters that affect NAICS codes lookup:
Parameter
Description
84
Data type Default
Description
Limits the query to NAICS entries that contain
''
string
(empty the specified string in their description (case
string) insensitive, anywhere within the description)
The extra space at the beginning of the description here is a typo in IQFeed’s data
IQML User Guide
105
8.7 Trade condition codes lookup
To retrieve a list of trade condition codes, set the action to 'lookup' and DataType to
'conditions':
>> data = IQML('lookup', 'DataType','conditions')
data =
155×1 struct array with fields:
id
name
description
>> data(1)
ans =
id: 1
name: 'REGULAR'
description: 'Normal Trade'
>> data(2)
ans =
id: 2
name: 'ACQ'
description: 'Acquisition'
You can convert the data into a [perhaps] more readable form using Matlab’s builtin
struct2cell() and struct2table() functions:
>> disp(struct2cell(data)')
[ 1]
'REGULAR'
'Normal Trade'
[ 2]
'ACQ'
'Acquisition'
[ 3]
'CASHM'
'Cash Only Market'
[ 4]
'BUNCHED'
'Bunched Trade'
[ 5]
'AVGPRI'
'Average Price Trade'
[ 6]
'CASH'
'Cash Trade (same day clearing)'
[ 7]
'DIST'
'Distribution'
[ 8]
'NEXTDAY'
'Next Day Market'
[ 9]
'BURSTBSKT'
'Burst Basket Execution'
[10]
'BUNCHEDSOLD'
'Bunched Sold Trade'
[11]
'ORDETAIL'
'Opening/Reopening Trade Detail'
[12]
'INTERDAY'
'Intraday Trade Detail'
[13]
'BSKTONCLOSE'
'Basket Index on Close'
[14]
'RULE127'
'Rule - 127 Trade NYSE'
[15]
'RULE155'
'Rule - 155 Trade AMEX'
[16]
'SOLDLAST'
'Sold Last (late reporting)'
...
>> disp(struct2table(data))
id
name
description
__
_____________
________________________________
1
'REGULAR'
'Normal Trade'
2
'ACQ'
'Acquisition'
3
'CASHM'
'Cash Only Market'
4
'BUNCHED'
'Bunched Trade'
5
'AVGPRI'
'Average Price Trade'
6
'CASH'
'Cash Trade (same day clearing)'
7
'DIST'
'Distribution'
8
'NEXTDAY'
'Next Day Market'
9
'BURSTBSKT'
'Burst Basket Execution'
10
'BUNCHEDSOLD'
'Bunched Sold Trade'
11
'ORDETAIL'
'Opening/Reopening Trade Detail'
12
'INTERDAY'
'Intraday Trade Detail'
13
'BSKTONCLOSE'
'Basket Index on Close'
14
'RULE127'
'Rule - 127 Trade NYSE'
15
'RULE155'
'Rule - 155 Trade AMEX'
16
'SOLDLAST'
'Sold Last (late reporting)'
...
IQML User Guide
106
You can narrow-down the results by specifying the Name and/or the Description
filtering parameters. For example, let’s display only security types that have ‘Option’
in their Description:
>> struct2table(IQML('lookup', 'DataType','conditions', 'Description','option'))
ans =
7×3 table
id
name
description
__
______________
___________________________________________________
39
'SPRD'
'Spread - Trade in Two Options in the Same Class
(a buy and a sell in the same class)'
40
'STDL'
'Straddle - Trade in Two Options in the Same Class
(a buy and a sell in a put and a call)'
43
'BWRT'
'Option Portion of a Buy/Write'
44
'CMBO'
'Combo - Trade in Two Options in the Same Options
Class (a buy and a sell in the same class)'
68
'STKOPT_TRADE'
'Stock-Option Trade'
82
'OPTION_EX'
'Option Exercise'
96
'OPT_ADDON'
'Short Option Add-On'
Naturally, it is quite possible that no security types exist that match the requested
criteria. In such a case, the result will be empty (and cannot be displayed using
Matlab’s struct2table() or struct2cell() functions):
>> data = IQML('lookup', 'DataType','conditions', 'Name','xyz')
data =
[]
>> struct2cell(data)
Undefined function 'struct2cell' for input arguments of type 'double'.
Note that the trade condition codes are typically reported by IQFeed as a string of one
or more 2-digit hexadecimal values.85 For example (see §4.1):
>> data = IQML('quotes', 'Symbol','GOOG')
data =
...
Most_Recent_Trade_Conditions: '3D87'
Trade_Conditions_Description: 'Intramaket Sweep; Odd lot trade'
In this example, the reported last trade had 2 trade conditions: hexadecimal 3D (=61,
meaning 'Intramaket Sweep')86 and hexadecimal 87 (=135, meaning 'Odd lot trade').
Here is a summary of the IQML parameters that affect trade conditions lookup:
Parameter
Name
Description
Data type Default
Description
''
Limits the query to trade conditions that
string
(empty contain the specified string in their name
string) (case insensitive, anywhere within the name)
string
''
Limits the query to trade conditions that
(empty contain the specified string in their description
string) (case insensitive, anywhere in the description)
85
Trade condition codes 15 or lower are reported with a leading 0, e.g. 05 or 0E
86
The missing “r” in “Intramarket” is a typo in IQFeed’s data
IQML User Guide
107
9 Connection, administration and other special commands
9.1 Connecting & disconnecting from IQFeed
When using IQML, there is no need to worry about connecting or disconnecting from
IQFeed – IQML handles these activities automatically, without requiring user
intervention. The user only needs to ensure that IQFeed is active and logged-in when
the IQML command is invoked in Matlab.
IQML does not require any special configuration when connecting to IQFeed. It uses
whatever setting was previously set in the DTN IQConnect client application. You
might be prompted to enter a username/password, if IQConnect was not set up to
automatically connect using saved login/password information:
In addition to entering the login credentials in the client window, you can also specify
them programmatically. This could be useful when you have several IQFeed accounts
and wish to switch between them programmatically, or if you use IQFeed’s nonWindows client installer on MacOs (which prevents user-entry in the login window):
>> IQML('time', 'Username','123456-1', 'Password','OpenSesame')
Note that the Username and Password parameters must be specified together, and
that they are only meaningful in the first IQML command that starts the connection –
they are ignored once a connection to IQFeed is already established.
If you enter an invalid set of Username/Password, an error message will be thrown.
A different error will be thrown if IQML fails to connect to IQFeed within 10 seconds.
IQML User Guide
108
IQML can connect to a running IQFeed client, that was already started by another
process on the current computer (e.g. charting app or another Matlab process that runs
IQML), even without Username and Password in the initial IQML connection. IQML
will bypass login, connecting directly to the client process.
You will be able to retrieve information in Matlab as soon as IQML connects to the
IQFeed client and [if necessary] the client finishes the login process and synchronizes
with the IQFeed servers. This process typically takes a few short seconds.
In some cases, users may wish to disrupt a live connection. You can disconnect from
IQFeed using IQML’s 'disconnect' action, which has no settable parameters:
>> IQML('disconnect')
This command disconnects IQML from the IQFeed client. If IQML was the only
application that was connected to the client, then the client will silently exit after
several seconds, if a new connection to it is not established during this time.
There is no need for a corresponding connect action, because connection is
automatically (re-)established whenever this is required by a new IQML command.
IQML and IQConnect automatically try to recover from connection losses during
normal operation. You may see in the Matlab console one or more IQConnect error
messages such as the following, which indicate such a connection loss:
20180410 20:03:06.371 Level1 server disconnected!
or:
20180410 20:03:57.934 Unable to connect to L2IP server. Error Code: 10051
Error Msg: A socket operation was attempted to an unreachable network.
or:
20180410 20:03:57.934 Unable to connect to L2IP server. Error Code: 10065
Error Msg: A socket operation was attempted to an unreachable host.
or:
20180410 20:03:57.934 Unable to connect to L2IP server. Error Code: 10053
Error Msg: An established connection was aborted by the software in your host
machine.
or:
20180410 20:03:57.934 Unable to connect to L2IP server. Error Code: 10060
Error Msg: A connection attempt failed because the connected party did not
properly respond after a period of time
You can safely ignore such messages in most cases, since IQConnect will
automatically re-establish connection with IQFeed’s servers as soon as they become
accessible again, and show an appropriate informational message in Matlab’s console:
20180410 20:04:16.497 Level1 server is connected
In some cases, users may wish to actively re-connect (disconnect and then connect) to
IQFeed. This can be done with the 'reconnect' action (no settable parameters):
>> IQML('reconnect')
Note that after reconnecting to IQFeed, you will need to request any and all streaming
data again (see §6), since IQFeed resets data streaming after a client disconnect.
IQML User Guide
109
9.2 Server time
You can request the latest IQFeed server time using the 'time' action:
>> data = IQML('time')
data =
latestEventDatenum:
latestEventTimeStamp:
latestServerDatenum:
latestServerTimestamp:
737114.660205451
'20180223 15:50:41'
737114.368518519
'20180223 08:50:40'
The returned data struct includes the following data fields:
latestEventDatenum
latestEventTimeStamp
latestServerDatenum
latestServerTimeStamp
– a Matlab numeric datenum value that corresponds to
the local time in which the very latest message has arrived from IQFeed.
– a human-readable format of latestEventDatenum
– a Matlab numeric datenum value that corresponds to
the latest server time that was received from IQFeed.
– a human-readable format of latestServerDatenum
Note that the server time may be off by up to a full second from the current time,
depending on when the last timestamp message was received from IQFeed. IQFeed
sends server time messages once every second, so latestServerDatenum lags by 0.5
secs behind the current time on average.
Similarly, latestEventDatenum reports the time at which the last message was
received from IQFeed. This message could be a timestamp message, or any other data
message. For this reason, the lag here is typically much lower than the lag of
latestServerDatenum.
The 'time' action has no settable properties.
IQML User Guide
110
9.3 Client stats
You can retrieve the updated IQFeed connection traffic stats using the 'stats' action:
>> data = IQML('stats')
data =
ServerIP:
ServerPort:
MaxSymbols:
NumOfStreamingSymbols:
NumOfClientsConnected:
SecondsSinceLastUpdate:
NumOfReconnections:
NumOfAttemptedReconnections:
StartTime:
MarketTime:
ConnectionStatus:
IQFeedVersion:
LoginID:
TotalKBsRecv:
KBsRecvLastSecond:
AvgKBsPerSecRecv:
TotalKBsSent:
KBsSentLastSecond:
AvgKBsPerSecSent:
Exchanges:
ServerVersion:
ServiceType:
'66.112.148.226'
60002
1300
0
3
1
0
0
'Mar 07 11:03AM'
'Mar 07 04:34AM'
'Connected'
'5.2.7.0'
'123456-1'
42.98
0.02
0.02
361.62
0.22
0.19
{1×16 cell}
'6.0.0.5'
'real_time'
The returned data struct includes the following data fields:87
ServerIP
MaxSymbols
NumOfClientsConnected
NumOfReconnections
NumOfAttemptedReconnections
– IP address of the least loaded IQFeed Quote Server
ServerPort – Port number for least loaded IQFeed Quote Server
– The maximum # of symbols that can be streamed simultaneously
NumOfStreamingSymbols – The # of symbols that are currently being streamed
– The # of clients that are currently connected
SecondsSinceLastUpdate – The # of seconds since the last update from the
Quote Server
– The # of times that IQFeed successfully reconnected
– The # of times that IQFeed has attempted to
reconnect, but failed
87
StartTime
MarketTime
IQFeedVersion
LoginID
TotalKBsRecv
– Time of latest connection/reconnection to IQFeed (local timezone)
– Current time of the market (market’s time-zone)
ConnectionStatus – Represents whether IQFeed is connected or not
– Represents the version of IQFeed that is running
– The Login ID that is currently logged into IQFeed
– Total # of Kilobytes received by IQFeed from IQML (i.e.,
IQML commands/requests to IQFeed). Found in the “Internet Bandwidth”
section of the IQConnection Manager. Formula: total bytes received / 1024
http://iqfeed.net/dev/api/docs/AdminSystemMessages.cfm
IQML User Guide
KBsRecvLastSecond
AvgKBsPerSecRecv
TotalKBsSent
KBsSentLastSecond
AvgKBsPerSecSent
Exchanges
ServerVersion
111
– Found in the “Internet Bandwidth” section of the
IQConnection Manager. Formula: bytes received in the past second / 1024
– Found in the “Internet Bandwidth” section of the
IQConnection Manager. Formula: total KB's received / total seconds
– Total # of Kilobytes sent from IQFeed to IQML (i.e., IQFeed
messages to IQML). Found in the “Local Bandwidth” section of the
IQConnection Manager. Formula: total bytes sent / 1024
– Found in the “Local Bandwidth” section of the
IQConnection Manager. Formula: bytes sent in the past second / 1024
– Found in the “Local Bandwidth” section of the
IQConnection Manager. Formula: total KB's sent / total seconds.
– The list of exchanges for which this IQFeed account is subscribed
– The current version of IQFeed that the server supports. This
is always the same or higher than your locally-installed IQFeedVersion.
ServiceType – Type of data provided for this account (delayed or real-time)
The 'stats' action has a single settable property: AddPortStats (default=0). If you set
this property to 1 or true, then additional stats will be returned, with extra
information on the various data ports (see the highlighted fields below):
>> data = IQML('stats', 'AddPortStats',1)
data =
ServerIP: '66.112.148.224'
ServerPort: 60005
MaxSymbols: 1300
NumOfStreamingSymbols: 0
NumOfClientsConnected: 4
SecondsSinceLastUpdate: 0
NumOfReconnections: 0
NumOfAttemptedReconnections: 0
StartTime: 'Apr 01 8:21PM'
MarketTime: 'Apr 01 02:12PM'
ConnectionStatus: 'Connected'
IQFeedVersion: '5.2.7.0'
LoginID: '464720-1'
TotalKBsRecv: 69.44
KBsRecvLastSecond: 0.04
AvgKBsPerSecRecv: 0.02
TotalKBsSent: 1470.32
KBsSentLastSecond: 0.47
AvgKBsPerSecSent: 0.48
Exchanges: {1×16 cell}
ServerVersion: '6.0.0.5'
ServiceType: 'real_time'
Level2: [1×1 struct]
Level2SymbolsWatched: 2
Lookup: [1×1 struct]
RegionalSymbolsWatched: 2
Admin: [1×1 struct]
Level1: [1×1 struct]
Level1SymbolsWatched: 0
IQML User Guide
>> data.Level1
ans =
ConnectTime:
KBsReceived:
KBsSent:
KBsQueued:
'20180401 202111'
0.74
70.58
0
>> data.Admin
ans =
ConnectTime:
KBsReceived:
KBsSent:
KBsQueued:
'20180401 202108'
0.43
1516.74
0
112
Note that it might take a few seconds for the stats to arrive after the initial command.
If you don’t see the expected results immediately simply re-query them after 1-2 secs.
IQML User Guide
113
9.4 Sending a custom command to IQFeed
You can send any custom command to IQFeed’s API, using the 'command' action.
For example, to send the 'S,TIMESTAMPSOFF' command,88 which stops IQFeed
from sending server timestamp messages every second:
>> IQML('command', 'String','S,TIMESTAMPSOFF')
IQFeed expects that users send commands to its API via specific channels (“ports”).
Each command is typically accepted only by the port for which it is defined. For
example, the 'S,TIMESTAMPSOFF' command is defined for the Level1 port,89
whereas the 'S,CLIENTSTATS OFF' command (which stops the IQFeed server from
streaming client stats messages) is defined for the Admin port.90 When you use
IQML’s standard actions you do not need to worry about which port handles which
command – this is automatically handled by IQML. But when you send a custom
command to IQFeed, you need to specify the port, if it is different from the default
('Level1'). In this specific example:
>> IQML('command', 'String','S,CLIENTSTATS OFF', 'PortName','Admin')
IQFeed is very picky about the spelling of the commands, including spaces and
casing. If the spelling is not exactly right, the command will be rejected by IQFeed,
possibly even without an error message. Unfortunately, IQFeed are not entirely
consistent in the format of the various commands. For example, the
'S,TIMESTAMPSOFF' command has no space, whereas the 'S,CLIENTSTATS OFF'
command does have a space; also, both of these commands are all-uppercase, yet the
'S,SET AUTOCONNECT,On' Admin command spells On/Off with lowercase letters
(and uses a comma instead of a second space).
In some cases, the command that is sent to IQFeed may result in data messages that
will be sent back from IQFeed, which should be received and processed. To do this,
you can set the ProcessFunc property to a custom callback function that will handle
these messages (see §10).
The following properties can be specified in IQML with the 'command' action:
Parameter
String
PortName
ProcessFunc
Data type Default
Description
string
(none) The IQFeed command string.
The IQFeed port that will process the command.
Must be one of the following:
'Level1' (default)
string 'Level1'
'Level2'
'Lookup'
'Admin'
function
Custom user callback function to process
[]
handle
incoming IQFeed data messages (see §10).
88
http://iqfeed.net/dev/api/docs/Level1viaTCPIP.cfm
89
http://iqfeed.net/dev/api/docs/Level1viaTCPIP.cfm
90
http://iqfeed.net/dev/api/docs/AdminviaTCPIP.cfm
IQML User Guide
114
10 Attaching user callbacks to IQFeed messages
10.1 Processing IQFeed messages in IQML
IQFeed uses an asynchronous event-based mechanism for sending information to
clients. This means that we do not simply send a request to IQFeed and wait for the
answer. Instead, we send a request, and when IQFeed is ready it will send us one or
more (or zero) messages in response. Each of these messages evoke an event that
carry data (the message content and the originating IQFeed channel/port-name). By
analyzing the event data we (hopefully) receive the answer that we were waiting for.
Matlab has built-in support for asynchronous events, called callbacks in Matlab
jargon.91 Whereas Matlab callbacks are normally used in conjunction with Graphical
User Interfaces (GUI), they are also used with IQML, which automatically converts
all the IQFeed events into a Matlab callback invocation.
The callback that processes incoming IQFeed messages is constantly being “fired”
(i.e., invoked) by asynchronous messages from IQFeed, ranging from client stats and
time messages (once per second, for each of IQFeed’s 3 channels/ports), to system
messages (e.g. connection losses and reconnections), to error messages and responses
to market queries. Some of the events are triggered by user actions (market or
portfolio queries, for example), while others are triggered by IQFeed (e.g., client stats
once a second).
In addition to the regular IQML callback that processes all incoming IQFeed message
events, you can assign your own custom Matlab function that will be triggered
whenever a certain IQFeed message arrives. In all cases, the parameter controlling
this callback in IQML is called ProcessFunc.
There are two types of callbacks that you can use in IQML:
Generic callback – this is a catch-all callback function that is triggered upon
any IQFeed message event. Within this callback, you would need to write
some code to distinguish between the different event types in order to process
the events’ data. A skeleton for this is given below.
Specific callback – this is a callback function that is only triggered when the
specific event type is received from IQFeed. Since the event type is known,
you can process its event data more easily than in the generic callback case.
You can specify a different specific callback for each of the event types that
you wish to process, as well as a default callback that will be used for any
other event that was not assigned a specific callback.
When you specify any callback function to IQML, the command/action does not need
to be related to the callback. For example:
data = IQML('time', 'ProcessFunc',@IQML_Callback);
where IQML_Callback() is a Matlab function created by you that accepts two input
arguments, which are automatically populated in run-time:
91
http://www.mathworks.com/help/matlab/creating_guis/writing-code-for-callbacks.html
IQML User Guide
iqObject
eventData
115
– this is currently an empty array. Future versions of IQML may
place an actual object in this argument.
– a Matlab struct that contains the event’s data in separate fields.
This struct includes the following fields:
o Timestamp – local time in Matlab numeric datenum format.
o MessagePort – the name of the IQFeed port that sent the message:
'Level1', 'Level2', 'Lookup' or 'Admin'.
o MessageType – the event type, which corresponds to the custom fields
that can be set in the ProcessFunc parameter for specific callbacks.
o MessageHeader – the first part of the message text string, that identified
the message type. This is typically used to set the MessageType field.
o MessageString – the message text string as received from IQFeed.
o MessageParts – processed parts of MessageString, as a cell-array.
An example of defining a Matlab callback function is:
function IQML_Callback(iqObject, eventData)
% do callback processing here using the info in eventData
end
You can pass external data to your callback functions using the callback cell-array
format.92 For example, to pass two extra data values:
callbackDefinition = {@IQML_Callback, 123, 'abc'};
IQML('time', 'ProcessFunc',callbackDefinition);
function IQML_Callback(iqObject,eventData,extra1,extra2)
% do callback processing here using the info in eventData, extra1, extra2
end
Here are examples of the eventData for two different IQFeed messages – a timestamp
message (sent from IQFeed once every second on the Level1 and Level2 ports), and a
connection stats message (sent from IQFeed once a second on the Admin port).
IQFeed messages always begin with a single character indicating the message type:
Timestamp:
MessagePort:
MessageType:
MessageHeader:
MessageString:
MessageParts:
737128.675475417
'Level1'
'Time'
'T'
'T,20180309 09:12:39'
{'T' '20180309 09:12:39'}
Timestamp:
MessagePort:
MessageType:
MessageHeader:
MessageString:
737128.675479248
'Admin'
'System'
'S'
'S,STATS,66.112.148.225,60002,1300,0,4,0,0,0,Mar 09
3:10PM,Mar 09 09:12AM,Connected,5.2.7.0,4647201,86.43,0.04,0.02,759.37,0.20,0.20'
MessageParts: {1×20 cell}
All IQFeed messages typically begin with a single character followed by ‘,’, which
we call the MessageHeader, and which identify the MessageType. For example,
MessageHeader of 'T' identifies a Time message, and 'S' identifies a System message. 93
92
http://www.mathworks.com/help/matlab/creating_guis/writing-code-for-callbacks.html#brqow8p
93
An exception to this rule may happen if you send custom commands to IQFeed using the mechanism in §7.4. In such case, it is
possible that MessageHeader will not be a recognized or even a single character. It will have a MessageType of 'Other'.
IQML User Guide
116
All the callbacks examples so far have set a generic callback that is used for all
incoming IQFeed messages. As noted above, you can also set specific callbacks for
specific messages. For example:
% Alternative #1: using the struct() function:
>> callbacks = struct('Time','disp TIME!', ...
'System',@(h,e)disp(e.MessageString));
% Alternative #2: using direct field assignments:
>> callbacks.Time = 'disp TIME!';
>> callbacks.System = @(h,e)disp(e.MessageString);
>> IQML('time','processFunc',callbacks);
TIME!
TIME!
S,STATS,66.112.156.228,60002,1300,0,4,0,0,1,Mar 11 12:36PM,Mar 11
07:14AM,Connected,5.2.7.0,464720-1,51.51,0.04,0.02,516.30,0.23,0.23
TIME!
TIME!
S,STATS,66.112.156.228,60002,1300,0,4,0,0,1,Mar 11 12:36PM,Mar 11
07:14AM,Connected,5.2.7.0,464720-1,51.54,0.04,0.02,516.48,0.23,0.23
TIME!
In this example, we have set two separate custom callbacks for two different IQFeed
messages: the periodic timestamp messages and the periodic system update messages.
In addition to specific callbacks for specific message types, you can also set a
“Default” callback that will be invoked for each incoming IQFeed message that does
not have a specific callback assigned to it.
The following message types can be trapped, corresponding to the eventData’s
MessageType field (e.MessageType):
MessageType
Fundamental
Quote_summary
Quote_update
Market_depth
Market_maker
History
Regional
News
End_of_data
Message
Header
Description
See
section
F
Fundamental asset data
4.2
P
Quote summary message
4.1
Q
Quote update (tick) message
6.1
Z
Level2 market-depth update message 4.4,6.4
M
Market maker information
4.4,6.4
H
Historical data (one msg per bar/tick)
5
R
Regional update message
6.2
N
News data (one message per item)
7
!ENDMSG! Indicates end of the data with multiple 5, 7
data items (e.g., history or news)
Lookup
s
Lookup information message
8.1
Chain
:
Options/Futures chain
8.2
Time
T
Timestamp message (once a second)
9.2
System
S
System message (stats, once a sec)
9.3
Symbol_not_found_error
n
Indicates a symbol-not-found error
3.4
General_error
E
All other IQFeed-generated errors
Other
All other IQFeed messages
Default
Any IQFeed message that does not
have a specific callback assigned to it
IQML User Guide
117
You can set individual callbacks to any of these MessageType values, by using the
MessageType value as a field-name in the ProcessFunc parameter. For example, to
process quote-update (tick) messages in a dedicated callback function:
>> callbacks.Quote_update = @IQML_Quote_Update_Callback;
>> IQML('time','ProcessFunc',callbacks);
Here is a more elaborate example, were we set different callbacks for different
message types, along with a default callback for all other message types:
% Alternative #1: using the struct() function:
>> callbacks = struct('Time','disp TIME!', ...
'System',[], ... % ignore System messages
'Quote_update',@IQML_Quote_Update_Callback, ...
'Default',@IQML_Default_Callback);
% Alternative #2: using direct field assignments:
>> callbacks.Time = 'disp TIME!';
>> callbacks.System = []; % ignore System messages
>> callbacks.Quote_update = @IQML_Quote_Update_Callback;
>> callbacks.Default = @IQML_Default_Callback);
>> IQML('time','processFunc',callbacks);
When you specify any callback function to IQML, you only need to set it once, in any
IQML command. Unlike most IQML parameters, which are not remembered across
IQML commands and need to be re-specified, callbacks do not need to be respecified. They are remembered from the moment they are first set, until such time as
Matlab exits or the callback parameter is changed.
Note that it is not an error to re-specify the callbacks in each IQML command, it is
simply useless and makes the code less readable.
To reset all callbacks (i.e., remove any callback invocation), simply set the
ProcessFunc parameter value to [] (empty square brackets):
IQML('time', 'ProcessFunc',[]);
You can also set individual message callbacks to an empty value, in order to ignore
just these specific messages but not the other messages:
>> callbacks.Time = 'disp TIME!';
>> callbacks.System = []; % ignore System messages
>> callbacks.Default = @IQML_Default_Callback);
>> IQML('time','ProcessFunc',callbacks);
Matlab callbacks are invoked even if you issue a custom IQFeed command (see §9.4).
This is actually very useful: you can use the command to send a request to IQFeed,
and then process the results in a Matlab callback function. However, note that in such
a case, it is possible that the returned message will contain a MessageHeader that will
not be a recognized or even a single character. Such messages will be assigned a
MessageType of 'Other'.
IQML User Guide
118
10.2 Run-time performance implications
It is very important to ensure that any callback function that you assign in IQML
completes in the fastest possible time. This is important for programming in general,
but it is especially important for IQML callbacks, which are invoked (executed) every
time that a new message arrives from IQFeed, numerous times each second.
As explained in §3.6, IQML’s standard callback processing has an overhead of 1-2
milliseconds per IQFeed message. This means that without any user-specified
callbacks, and without any other Matlab or other code running, IQML can process up
to 500-1000 IQFeed messages per second.
When you add your own user-defined callbacks, their processing time is added to
IQML’s. For example, if your callback takes an average of just 3 msecs to process
(which is quite fast), then the total average message processing time will be 4-5
msecs, lowering IQML’s effective maximal processing rate from 500-1000 to just
200-250 messages/second. The more callbacks and alerts that you define, and the
longer each of them takes to process, the lower will IQML’s message processing rate be.
The following specific tips may assist you to reduce the callback performance impact:
1. Ensure that you have enough physical memory to avoid memory swapping to
disk. This is probably the single most important tip to improve performance
2. Avoid setting user callbacks and alerts, or at least disable them when not needed.
3. Avoid setting a Default callback or a general ProcessFunc, but rather specific
callbacks only for the messages that you need (e.g. for News or Regional).
4. Limit the streaming data to just those events and symbols that are of interest to
you. For example, if you are only interested in the GOOG symbol, and set a
Quote_update callback, this callback will also be processed for streaming
quotes for other symbols, so it’s better to stop streaming those other symbols.
5. Minimize disk access: disk I/O is much slower than memory access. Save data
to memory and flush it to disk at the end of the trading day, or once in a while
(e.g. every 5 minutes), but not in each callback.
6. If you need to access a disk, use SSD (solid-state disk) rather than a spinning
hard-disk.
7. If you need to load data from disk, do it once and preserve the data in memory
using Matlab persistent or global variables, to be reused in callback calls.
8. Instead of re-computing values that are based on static data in each callback
call, compute once and cache results in Matlab persistent or global variables.
9. Use Matlab’s built-in Profiler tool94 to check your callback code for run-time
performance hotspots that can be optimized to run faster.
10. Read the textbook “Accelerating MATLAB Performance”,95 authored by
IQML’s creator (see §15.2), for numerous tips on improving Matlab run-time.
94
https://mathworks.com/help/matlab/matlab_prog/profiling-for-improving-performance.html
95
https://undocumentedmatlab.com/books/matlab-performance
IQML User Guide
119
10.3 Usage example – using callbacks to parse options/futures chains
In this example, we request IQFeed to send the list of symbols in an options/futures
chain, then parse the incoming results to retrieve the symbols in the chain (see §8.2).
We first send the relevant command to IQFeed using IQML’s custom command
functionality (§9.4), specifying a custom callback function for the 'Chain'
MessageType:96
% Equity options chain for GOOG:
processFunc.Chain = @IQML_Chain_Callback;
>> IQML('command', 'String','CEO,GOOG,p,,1', 'PortName','lookup', ...
'debug',1, 'ProcessFunc',processFunc)
=> 20180405 13:13:00.063 (lookup) CEO,GOOG,p,,1
<= 20180405 13:13:00.574 (lookup) :,GOOG1806P1000,GOOG1806P1002.5,GOOG1806P1
005,GOOG1806P1007.5,GOOG1806P1010,GOOG1806P1012.5,GOOG1806P1015,GOOG1806P1017
.5,GOOG1806P1020,GOOG1806P1022.5,GOOG1806P1025,GOOG1806P1027.5,GOOG1806P1030,
GOOG1806P1032.5,GOOG1806P1035,GOOG1806P1037.5,GOOG1806P1040,GOOG1806P1042.5,G
OOG1806P1045,GOOG1806P1047.5,GOOG1806P1050,…,
<= 20180405 13:13:00.578 (lookup) !ENDMSG!
% Future options chain for C:
>> IQML('command', 'String','CFO,C,p,,9,1', 'PortName','lookup', ...
'debug',1, 'ProcessFunc',processFunc)
=> 20180405 13:31:48.677 (lookup) CFO,C,p,,9,1
<= 20180405 13:31:49.149 (lookup) :,CH19P2000,CH19P2100,CH19P2200,CH19P2300,CH19
P2400,CH19P2500,CH19P2600,CH19P2700,CH19P2800,CH19P2900,CH19P3000,CH19P3100,CH19P
3200,CH19P3300,CH19P3400,CH19P3500,CH19P3600,CH19P3700,CH19P3800,CH19P3900,CH19P4
000,CH19P4100,CH19P4200,CH19P4300,CH19P4400,CH19P4500,CH19P4600,CH19P4700,CH19P48
00,CH19P4900,CH19P5000,CH19P5100,CH19P5200,CH19P5300,CH19P5400,CH19P5500,CH19P560
0,CH19P5700,CH19P5800,CH19P5900,CH19P6000,CH19P6100,CH19P6200,CH19P6300,CH19P6400
<= 20180405 13:31:49.158 (lookup) !ENDMSG!
The custom callback function may look something like this:
function IQML_Chain_Callback(iqObject,eventData)
symbols = eventData.MessageParts(2:end); %discard the ':' message header
% now do something useful with the reported symbols...
end
96
Note that we have set Debug=1 in this example purely to illustrate the incoming IQFeed message format; it would not be used
in a typical run-time program.
IQML User Guide
120
10.4 Usage example – using callbacks for realtime quotes GUI updates
In this example, we wish to update a real-time ticker window with the latest
streaming quotes data. The idea is to create a minimalistic window and update its title
with the symbol name and latest trade price, whenever a new tick arrives.
The code relies on the format of IQFeed’s Quote_update (Q) message, which by default
is a 16-element cell array: {Symbol, Most_Recent_Trade, Most_Recent_Trade_Size,
Most_Recent_Trade_Time, Most_Recent_Trade_Market_Center, Total_Volume, Bid, Bid_Size, Ask,
Ask_Size, Open, High, Low, Close, Message_Contents, Most_Recent_Trade_Conditions }:
>> processFunc = struct('Quote_Update', @Quote_Update_Callback);
>> IQML('quotes', 'symbol','@VX#', 'numofevents',100, ...
'ProcessFunc',processFunc, 'debug',1)
=> 20180411 12:03:40.131 (Level1) w@VX#
<= 20180411 12:03:40.391 (Level1) F,@VX#,20,,,28.05,12.85,,,,,,,,,,,,,,,,,,CBOE …
<= 20180411 12:03:40.409 (Level1) P,@VX#,20.61,,04:52:29.711000,32,5668,20.60,50,
20.65,87,20.20,20.70,20.15,20.18,Cbasohlcv,4D
<= 20180411 12:03:44.887 (Level1) Q,@VX#,20.61,,04:52:29.711000,32,5668,20.60,50,
20.65,86,20.20,20.70,20.15,20.18,a,4D
In our case, we are only interested in the 1st (Symbol) and 2nd (Most_Recent_Trade)
elements of the 'Q' update messages:
eventData =
Timestamp:
MessagePort:
MessageType:
MessageHeader:
MessageString:
737161.502602859
'Level1'
'Quote_Buffer'
'Q'
'Q,@VX#,20.61,,04:52:29.711000,32,5668,20.60,50,20.65,86,
20.20,20.70,20.15,20.18,a,4D'
MessageParts: {'@VX#' 20.61 [] '04:52:29.711000' 32 5668 20.6 50
20.65 86 20.2 20.7 20.15 20.18 'a' '4D'}
The corresponding callback function will be:
function Quote_Update_Callback(iqObject, eventData)
% Symbol is 1st data element of IQFeed 'Q' messages
symbol = eventData.MessageParts{1};
% Last trade price is 2nd data element of the IQFeed 'Q' messages
latestTrade = eventData.MessageParts{2};
% Get the handle for this symbol's ticker window
hFig = findall(0, 'Tag',symbol, '-depth',1);
if isempty(hFig)
% Ticker window not found, so create it
hFig = figure('Tag',symbol,
'Position',[300,300,250,1], ...
'Resize','off', 'NumberTitle','off', ...
'Menu','none', 'Toolbar','none',);
end
% Update the ticker window's title
hFig.Name = sprintf('%s: %.2f', symbol, latestTrade);
end
And the resulting ticker window will look like this:
As noted in §6.1 above, tick events may be sent at a very high rate from the IQFeed
server. So instead of updating the GUI with each tick, you may want to use a periodic
Matlab timer having a Period of 0.5 [secs], that will invoke a timer callback, which
will call IQML(…,'NumOfEvents',-1) to fetch the latest data and update the GUI.
IQML User Guide
121
10.5 Usage example – using callbacks for realtime order-book GUI updates
In this example, we wish to update a real-time GUI display of the order-book (at least
the top few rows of the book).
Note: Market Depth (Level 2) data is only available in the Professional IQML license.
As noted in §6.4 above, market-depth events may be sent at a very high rate from the
IQFeed server, and so it is not feasible or useful to update the Matlab GUI for each
update. Instead, we update the GUI with the latest data at a steady rate of 2 Hz (twice
a second). This can be achieved in two different ways: one alternative is to set-up a
periodic timer that will run our GUI-update callback every 0.5 secs, which will call
IQML(…,'NumOfEvents',-1) to fetch the latest data and update the GUI.
Another alternative, shown here below (also downloadable97), is to attach a user
callback function to Level 2 market-depth messages, updating an internal data struct,
but only updating the GUI if 0.5 secs or more have passed since the last GUI update:
% IQML_MktDepth - sample Market-Depth usage function
function IQML_MktDepth(symbol)
% Initialize data
numRows = 10;
depthData = cell(numRows,8);
lastUpdateTime = -1;
GUI_refresh_period = 0.5 * 1/24/60/60; % =0.5 secs
% Prepare the GUI
hFig = figure('Name','IQML market-depth example', ...
'NumberTitle','off','CloseReq',@figClosedCallback,...
'Menubar','none', 'Toolbar','none', ...
'Resize','off', 'Pos',[100,200,660,260]);
color = get(hFig,'Color');
headers = {'Ask valid','Ask time','Ask size','Ask price', ...
'Bid price','Bid size','Bid time','Bid valid'};
formats = {'logical','char','numeric','long', ...
'long','numeric','char','logical'};
hTable = uitable('Parent',hFig, 'Pos',[10,40,635,203], ...
'Data',depthData, 'ColumnName',headers, ...
'ColumnFormat',formats, ...
'ColumnWidth',{60,100,80,80,80,80,100,60});
hButton = uicontrol('Parent',hFig, 'Pos',[50,10,60,20], ...
'String','Start', 'Callback',@buttonCallback);
hLabel1 = uicontrol('Parent',hFig, 'Pos',[120,10,100,17], ...
'Style','text', 'String','Last updated:', ...
'Horizontal','right', 'Background',color);
hLabelTime = uicontrol('Parent',hFig, 'Pos',[225,10,100,17], ...
'Style','text', 'String','(not yet)', ...
'Horizontal','left', 'Background',color);
% Send the market-depth request to IQFeed using IQML
contractParams = {'symbol',symbol}; % symbol='@ES#'
callbacks = struct('Market_depth',@mktDepthCallbackFcn);
IQML('marketdepth', contractParams{:}, 'processFunc',callbacks);
97
http://IQML.net/files/IQML_MktDepth.m
IQML User Guide
% Figure close callback function - stop market-depth streaming
function figClosedCallback(hFig, ~)
% Delete figure window and stop any pending data streaming
delete(hFig);
IQML('marketdepth', contractParams{:}, 'numofevents',0);
end % figClosedCallback
% Start/stop button callback function
function buttonCallback(hButton, ~)
currentString = get(hButton,'String');
if strcmp(currentString,'Start')
set(hButton,'String','Stop');
else
set(hButton,'String','Start');
end
end % buttonCallback
% Callback functions to handle IQFeed Market Depth update events
function mktDepthCallbackFcn(~, eventData)
% Ensure that it's the correct MktDepth event
allMsgParts = strsplit(eventData.MessageString,',');
allMsgParts(strcmpi(allMsgParts,'T')) = {true};
allMsgParts(strcmpi(allMsgParts,'F')) = {false};
if strcmp(eventData.MessagePort,'Level2') && ...
strcmp(allMsgParts{2},symbol)
% These are the field names of the IQFeed messages
inputParams = {'Intro','Symbol','MMID',...
'Bid','Ask','BidSize','AskSize',...
'BidTime','Date','ConditionCode',...
'AskTime','BidInfoValid',...
'AskInfoValid','EndOfMsgGroup'};
% Get the updated data row
% Note: Java indices start at 0, Matlab starts at 1
mmid = allMsgParts{strcmpi(inputParams,'MMID')};
row = sscanf(mmid,'%*c%*c%d');
% Get the size & price data fields from the event's data
bidValid = allMsgParts{strcmpi(inputParams,'BidInfoValid')};
askValid = allMsgParts{strcmpi(inputParams,'AskInfoValid')};
bidTime = allMsgParts{strcmpi(inputParams,'BidTime')};
askTime = allMsgParts{strcmpi(inputParams,'AskTime')};
bidSize = allMsgParts{strcmpi(inputParams,'BidSize')};
askSize = allMsgParts{strcmpi(inputParams,'AskSize')};
bidPrice = allMsgParts{strcmpi(inputParams,'Bid')};
askPrice = allMsgParts{strcmpi(inputParams,'Ask')};
thisRowsData = {askValid,askTime,askSize,askPrice,...
bidPrice,bidSize,bidTime,bidValid};
depthData(row,:) = thisRowsData;
% Update the GUI if more than 0.5 secs have passed and
% the button was not pressed
if ~isvalid(hButton), return, end
isStopped = strcmp(get(hButton,'String'),'Start');
if now - lastUpdateTime > GUI_refresh_period && ~isStopped
set(hTable,'Data',depthData);
set(hLabelTime,'String',datestr(now,'HH:MM:SS'));
lastUpdateTime = now;
end
end
end % mktDepthCallbackFcn
end % IQML_MktDepth
122
IQML User Guide
123
IQML User Guide
124
11 Alerts
11.1 General Usage
In cases where certain events in steaming data are of interest to the user, IQML can
generate alerts of these events as they arrive from IQFeed. The user can define the
event data type, the trigger condition, and the type of alert to generate when the
condition is met. For example, users may configure an alert on quotes, such that when
a symbol’s bid price is higher than some threshold, an email will be sent.
Each alert contains 3 components:
Data type – quote, intervalbar, regional or news
Trigger – a condition (typically a comparison between a field and a value)
Action – what IQML should do when the trigger condition is met
Alerts are created using the 'alert' action. Each new alert is assigned a unique
numeric ID. Using this ID, users can query, delete or edit the alert after it was created.
The following parameters affect the alerts. Detailed explanations and usage examples
are listed in the following sections.
Parameter
Symbol or
Symbols 98
Trigger
Data type
Default
colondelimited
string or
cell-array
of strings
(none)
(none)
string
describing
the alert – must be
trigger defined for
new alerts!
(none)
AlertAction
string
– must be
defined for
new alerts!
Description
Limits the alert to the specified symbols
and meta-tags only. Examples:
'IBM'
'IBM:AAPL:GOOG'
{'IBM', 'AAPL', 'GOOG'}
Optional parameter for news alerts;
mandatory for quote/intervalbar alerts
A string composed of the data type,
triggering parameter, trigger operator and
triggering value, separated by spaces.
Examples:
'quote bid >= 100'
'intervalbar close < 80'
'news text contains IPO'
Type of alert to generate. Options: 99
'display'
'popup'
'email' (requires specifying the
EmailRecipients parameter)
@myCallbackFcn
{@myFcn, data1, data2, …}
98
In IQML, the Symbol and Symbols parameters are synonymous – you can use either of them, in any capitalization
99
Note the performance implications that are discussed in §3.6 and §10.2 above
IQML User Guide
Parameter
Data type
Default
125
Description
Maximal # of times to be alerted of the
defined event. NumOfEvents = -1 returns
integer
1
NumOfEvents
a list of all existing alerts.
If false (default), data streaming needs to be
started by the user in a separate command.
logical
false
If true and relevant data streaming is not
StartStream
(true/false)
currently active, IQML starts the data
streaming automatically (see §11.2).
Unique ID generated and returned by
IQML when new alert is defined.
[]
integer
(scalar or
AlertID
(empty AlertID is relevant (and mandatory) only
array)
for querying, editing or deletion of
array)
existing alerts. See §11.3, §11.4 below.
If true (default), the full story text is
fetched and reported with each news alert
via email/callback;
logical
true
GetStory
if false, only headline data will be reported.
(true/false)
GetStory is relevant only for news alerts
with AlertAction='email' or callback.
Email addresses to which email alerts will
commabe sent. This parameter is relevant (and
delimited
''
mandatory) only for email alerts. Examples:
(empty
EmailRecipients string or
'john@doe.com'
cell-array
string)
'john@doe.com, jane@doe.com'
of strings
{'john@doe.com', 'jane@doe.com'}
SMTP e-mail address from which alert
emails will be sent.
'iqml.alerts@ This parameter is relevant only for
string
SmtpEmail
gmail.com' specifying a non-default email sender.
SmtpEmail only needs to be set once,
and is used by all future IQML alert events.
SMTP server that will send alert emails.
This parameter is relevant only for
string
(none) specifying a non-default email sender.
SmtpServer
SmtpServer only needs to be set once,
and is used by all future IQML alert events.
Password of the sender’s e-mail account.
This parameter is relevant only for
specifying a non-default email sender.
(confidential)
string
SmtpPassword
SmtpPassword only needs to be set once,
and is used by all future IQML alert events.
Note: Alerts are only available in the Professional IQML license.
IQML User Guide
126
11.2 Alert Configuration
Alerts can be configured by the user using the 'alert' action, using the properties in
the table above. Users can configure the data type, event trigger, maximal number of
alert reports, and the type of alert to generate (email, pop-up message, etc.). For email
alerts, users can also specify the recipients and the sender email account.
The Trigger parameter is the most important input, and is unique to the 'alert'
action. It is a string describing the alert trigger event, so it is very important that it be
composed properly. The Trigger string has 4 elements:
1. Data type ('quote', 'intervalbar' or 'news')
2. Trigger field: case-insensitive name of a field in the latestData struct of the
source data specified by the Data type (see §6.1, §6.3). For example: 'bid',
'ask', 'total_volume', 'Most_Recent_Trade', 'intervalVolume', 'text', etc.
3. Trigger operator ('>', '<', '=', '>=', '<=', 'contains').100
'>', '<', '=', '>=', '<=' are relevant for quote/intervalbar alerts
'=' and 'contains' are relevant for news alerts
4. Trigger value: either numeric (for a >,<,=,>=,<= operator) or string (for a
=,contains operator)
For example:
alertId = IQML('alert', 'Symbol','IBM', 'Trigger','quote ask < 145', ...);
alertId = IQML('alert', 'Symbol','IBM', 'Trigger','quote Total_Volume >= 10', ...);
alertId = IQML('alert', 'Symbol','IBM', 'Trigger','news text contains IPO', ...);
By default, alerts are only triggered and reported once. This can be changed by setting
the NumOfEvents parameter to an integer value. For example, the following alert
will be reported up to 5 times, and will then be deleted from the list of alerts:
alertId = IQML('alert', 'Symbol','IBM', ..., 'NumOfEvents',5);
IQML does NOT automatically start streaming data when alerts are defined. This
enables users to start and stop streaming data at will, and the alerts will only be
evaluated when streaming data messages arrive from IQFeed.
It is sometimes convenient to start streaming immediately when the alert is created.
This can be done by setting the StartStream parameter (default: false). Setting a
value of true starts the streaming for the corresponding data type (e.g., streaming
quotes for a symbol) automatically, unless the streaming is already active.
Note that with StartStream=true, the streaming is started automatically, using the
default parameters. If you wish to control the streaming parameters (for example,
NumOfEvents or DataType), leave StartStream in its default false value, and start
the streaming in a separate IQML command.
100
Additional trigger operators are planned in future IQML releases.
IQML User Guide
127
The AlertAction defines the action to be performed when a triggering event is detected
(i.e., when the trigger condition is met). There are 4 possible AlertAction values:
'popup', 'display', 'email', and callback (note the performance discussion in §3.6, §10.2):
1. 'Popup' announces the triggered event in a pop-up a message-box:
alertId = IQML('alert', 'Symbol','@VX#', 'Trigger','quote bid > 14.75', ...
'AlertAction','popup');
2. 'Display' announces the event in Matlab’s console (Command Window):
alertId = IQML('alert', 'Symbol','@VX#', 'Trigger','quote bid > 14.75', ...
'AlertAction','display');
04:50:11.099000 IQML alert: @VX# bid (14.8) > 14.75
Or, as another example of regional update alert:
alertId = IQML('alert', 'Symbol','IBM', 'AlertAction','display', ...
'Trigger', 'regional regionalbid > 140');
20180524 16:57:13.689 IQML alert: IBM regionalbid (143.75) > 140
3. 'Email' – an email with the alert event’s details will be sent to the specified
EmailRecipients, a mandatory parameter for email alerts. EmailRecipients
must be set as a comma/semi-colon/colon delimited string, or a cell array of
email addresses; it cannot be left empty.
For example, the following alert will send an email to two email recipients:
alertId = IQML('alert', 'Symbol','@VX#', 'Trigger','quote bid > 14.75', ...
'AlertAction','email', ...
'EmailRecipients',{'john@a.com','jane@b.com'});
which results in an email similar to this:
From: iqml.alerts@gmail.com
Subject: IQML alert: @VX# bid (14.8)
Body:
Symbol:
Most_Recent_Trade:
Most_Recent_Trade_Size:
Most_Recent_Trade_Time:
Most_Recent_Trade_Market_Center:
Total_Volume:
Bid:
...
or similarly, in the case of a news alert:
> 14.75
'@VX#'
14.82
10
'08:40:02.926510'
32
6890
14.8
IQML User Guide
128
From: iqml.alerts@gmail.com
Subject: IQML alert: United Technologies Plans To Hire 35,000 People, Make
$15 B... (RTB)
Body:
ID: 22017029634
Symbols: {'UTX'}
Text: '09:31 Wednesday, May 23, 2018. (RTTNews) - United Technologies
Plans To Hire 35,000 People, Make $15 Bln Investment In U.S. Over Next 5 Years
For comments and feedback: contact editorial@rttnews.com. Copyright(c) 2018
RTTNews.com. All Rights Reserved'
For news alerts, the full story text is fetched by default. It is possible to skip
fetching the full story by setting GetStory to false. This speeds up processing
by skipping the news-fetch query, and reports only the headline information:
From: iqml.alerts@gmail.com
Subject: IQML alert: United Technologies Plans To Hire 35,000 People, Make
$15 B... (RTB)
Body:
Source: 'RTB'
ID: 22017029634
Symbols: {'UTX'}
Timestamp: '20180523 093143'
Text: 'United Technologies Plans To Hire 35,000 People, Make $15 B...'
As noted, EmailRecipients can be specified in various manners. For example,
all the following are equivalent:
'EmailRecipients','john@a.com,jane@b.com'
'EmailRecipients','john@a.com;jane@b.com'
'EmailRecipients',{'john@a.com','jane@b.com'}
Alert emails are sent from an IQML email address (iqml.alerts@gmail.com)
by default. To send the alert emails from another sender (for example, a
corporate email account), specify the SmtpEmail, SmtpServer and
SmtpPassword.101 These parameters are saved in your local machine’s
Matlab settings, and will be used by all future IQML email alerts (even after
you restart the computer), so you only need to set them once. For example:
alertId = IQML('alert', 'Symbol','GOOG', 'Trigger','quote ask < 1090', ...
'AlertAction','email', 'Recipients','JohnDoe@gmail.com', ...
'SmtpServer','smtp.gmail.com', ...
'SmtpEmail','senderEmail@gmail.com', ...
'SmtpPassword','mypassword123');
On modern smartphones, text (SMS) messages have generally been replaced
with push notifications of incoming emails. Still, for some users text alerts
may be useful. Some mobile operators enable users to receive text messages
by sending the messages to a specially-formed email address.102 For example,
to send a text message alert to T-Mobile number 123-456-7890 in the USA,
simply email the alert to 1234567890@tmomail.net. To receive alerts via such
text messages, you just need to determine your mobile carrier’s email gateway
for SMS messages, and set EmailRecipients accordingly.
101
The SMTP port is automatically assumed to be 465
102
https://en.wikipedia.org/wiki/SMS_gateway#Email_clients. Note that carrier charges for these SMS messages might apply.
IQML User Guide
129
4. Callback: a personalized callback function for an event can be specified using
a Matlab function handle. For example:
alertId = IQML('alert', 'Symbol','GOOG', 'Trigger','…', 'AlertAction',@myFunc);
The callback function (myFunc in this example) should accept two or more
inputs, as customary for Matlab callbacks:103
function myFunc(alertObject, eventData)
alertObject –
eventData
a struct with the alert’s configuration (see §11.3 below)
– a struct with the triggered event’s local time (in Matlab
datenum format) and the trigger data.
For example, for quote data alerts, eventData might look like this:
>> eventData =
triggerTime: 737202.663148947
triggerData: [1×1 struct]
>> eventData.triggerData
ans =
Symbol:
Most_Recent_Trade:
Most_Recent_Trade_Size:
Most_Recent_Trade_Time:
Most_Recent_Trade_Market_Center:
Total_Volume:
...
'GOOG'
1083
30
'08:54:53.159809'
11
1957
To specify additional input parameters to your callback function, set
AlertAction to a cell array in which the first cell is the function handle and
the rest are additional inputs. For example:
callback = {@myFunc, data1, data2};
alertId = IQML('alert', 'Symbol','GOOG', 'Trigger','…', 'AlertAction',callback);
function myFunc(alertObject, eventData, data1, data2)
... % data processing done here
end
103
https://www.mathworks.com/help/matlab/creating_plots/callback-definition.html;
https://www.mathworks.com/help/matlab/creating_guis/write-callbacks-using-the-programmatic-workflow.html#f16-1001315
IQML User Guide
130
11.3 Alerts Query
IQML can be queried for the list of all existing alerts, or just a single specific alert.
Alerts are returned in this case as Matlab structs containing the alerts’ specifications.
Specific alerts may be queried by specifying their unique AlertID (which was
returned by the command that created the alert), and setting NumOfEvents to -1:
>> alertID = IQML('alert', 'Symbol','IBM', 'Trigger','quote bid > 200',…);
>> alert = IQML('alert', 'AlertID',alertID, 'NumOfEvents',-1)
alert =
struct with fields:
AlertID: 22120136109
isActive: 1
DataType: 'quote'
Trigger: 'bid > 200'
TriggerType: 'bid'
TriggerOp: '>'
TriggerValue: '200'
Symbol: {'IBM'}
AlertAction: 'popup'
EmailRecipients: {}
EventsProcessed: 0
EventsToProcess: 1
LatestValue: []
The AlertID parameter can be an array of alert IDs, resulting in an array of structs.
To retrieve the list of all the existing alerts, simply set NumOfEvents to -1, without
specifying the AlertID parameter:
>> allAlerts = IQML('alert', 'NumOfEvents',-1)
allAlerts =
3×1 struct array with fields:
AlertID
isActive
DataType
Trigger
TriggerType
TriggerOp
TriggerValue
Symbol
AlertAction
EmailRecipients
EventsProcessed
EventsToProcess
LatestValue
11.4 Alert Editing or Deletion
An existing alert can be edited or deleted by specifying its AlertID:
To delete an alert, set NumOfEvents to 0 as follows:
IQML('alert', 'AlertID',alertID, 'NumOfEvents',0);
To update/edit an alert, specify AlertID with one or more of the alert configuration
parameters: Symbols, Trigger, AlertAction, EmailRecipients, NumOfEvents (>1).
IQML('alert','AlertID',alertID,'AlertAction','email','EmailRecipients','john@a.com');
As above, the AlertID input can be an array of IDs, affecting multiple alerts at once.
IQML User Guide
131
12 Messages and logging
To display detailed information, you can set IQML’s Debug parameter to 1 or true
(default=0). This will display in the Matlab console (Command Window) additional
information that may help diagnose problems.
For example, setting Debug to 1 (or true) displays the outgoing commands from
IQML to IQFeed (“=>”), and incoming messages from IQFeed to IQML (“<=”), along
with the message’s local timestamp and port channel:104
>> data = IQML('news' ,'DataType','headlines', 'MaxItems',4, 'debug',1)
=> 20180401 15:14:00.010 (Lookup) NHL,,:,t,5,,
<= 20180401 15:14:01.082 (Lookup) N,CPR,21998204468,,20180401080059,
Following Is a Test Release
<= 20180401 15:14:01.086 (Lookup) N,RTI,10134529069,,20180401080029,
Quarterly Corporate Earnings (04/01/18)
<= 20180401 15:14:01.092 (Lookup) N,CPR,21998201110,,20180401073059,
Following Is a Test Release
<= 20180401 15:14:01.098 (Lookup) N,CPR,21998197500,,20180401070059,
April 1 Alert: Introducing, Duty Not Free: Pay-as-you-go toilet time
<= 20180401 15:14:01.107 (Lookup) !ENDMSG!
>> data = IQML('quotes', 'symbol','FB', 'debug',1)
=> 20180401 17:20:29.189 (Level1) wFB
<= 20180401 17:20:29.450 (Level1)
F,FB,5,29.1,50158000,195.3200,138.8100,195.3200,149.0200,0.0000,,,,,,
,,,,5.49,,2.52,12,,FACEBOOK,FB,47.600,0.63,,48563.0,3760.0,12/31/2017
,,2905001,,,,,,14,4,7375,36.25,1,21,02/01/2018,04/11/2017,02/01/2018,
03/26/2018,176.4600,,,,,519190,,,
<= 20180401 17:20:29.462 (Level1)
P,FB,160.0500,50000,19:59:56.263577,11,0,160.0500,4600,160.0600,200,,
,,159.7900,Cbacv,8801
=> 20180401 17:20:29.471 (Level1) rFB
A detailed log of all outgoing and incoming IQFeed messages, as well as IQFeed
events, can be found in IQFeed’s log, which is a text file called “IQConnect.txt” in
the \DTN\IQFeed subfolder, in the “My Documents” folder. For example,
C:\Users\\Documents\DTN\IQFeed\IQConnectLog.txt (replace with the
actual user name). You can control logging in IQFeed’s Diagnostic Utility:
104
Periodic IQFeed timestamp and client-stats messages (once every second) are not displayed, even Debug is 1 or true
IQML User Guide
132
In certain cases, IQML reports messages as red error messages on the Matlab console.
Such messages can be handled by analyzing IQML’s second (optional) output
argument, which is typically an empty string, except when an error is reported:
>> [data, errorMsg] = IQML('quotes', 'Symbol','IBM', 'Timeout',0.1)
IQML timeout: either IQFeed has no data for this query, or the Timeout
parameter should be set to a value larger than 0.1
data =
[]
errorMsg =
'IQML timeout: either IQFeed has no data for this query, or the Timeout
parameter should be set to a value larger than 0.1'
Users can control whether such error messages from IQFeed should raise a Matlab
error (exception) in blocking (non-streaming) mode, using the RaiseErrorMsgs
parameter (default: true).
>> [data, errorMsg] = IQML('quotes', 'Symbol','IBM', 'RaiseErrorMsgs',false);
In addition to IQFeed messages, your program must handle cases of IQML errors. In
most cases, these are due to invalid IQML input parameters (an invalid action or
parameter name, or an invalid parameter value). Errors might also happen due to
network problems, or even an internal bug due to an unhandled edge-case situation.
To trap and handle such programmatic exceptions, wrap your calls to IQML within a
try-catch block, as follows:
try
data = IQML('action','query', ... );
catch
% process the exception here
end
Try-catch blocks have very small performance or memory overhead and are a very
effective way to handle programmatic errors. We recommend that you use them in
your program, not just to wrap IQML calls but also for other processing tasks. I/O sections
in particular (reading/writing files) are prone to errors, so they are prime candidates
for such exception handling. The same applies for code that handles user inputs (we
can never really be too sure what invalid junk a user might enter in there, can we?).
Very common causes of errors when using IQML are relying on default parameter
values, and specifying numeric parameter values within string quotes (e.g., ‘1’ rather
than 1). Users of IQML should take extra precaution in their programs to ensure that
these common mistakes do not occur. See discussion in §3.4 above.
Matlab “out of memory” errors might occur when receiving and storing a huge
amount of streaming or historic data. They can be fixed by running IQML on a
computer having more memory, or by reducing the amount of stored data.105
Java memory errors are recognized by the message “java.lang.OutOfMemoryError:
Java heap space”. They can be solved by running Matlab with more allocated Java
heap memory than the default value of 64MB or 128MB (depending on Matlab
105
Also see: http://www.mathworks.com/help/matlab/matlab_prog/resolving-out-of-memory-errors.html
IQML User Guide
133
release). This value can be increased in Matlab’s preferences, or via a java.opts
file.106
106
https://www.mathworks.com/matlabcentral/answers/92813-how-do-i-increase-the-heap-space-for-the-java-vm-in-matlab-6-0r12-and-later-versions
IQML User Guide
134
13 Frequently-asked questions (FAQ)
1. Can IQML be used with other data-feed providers?
IQML only connects to DTN IQFeed. It can be adapted for other data providers, but
some development is obviously required since other providers have different APIs.
Contact us by email to see if we can help.
2. Does IQML impose limitations on historical data or streaming quotes?
IQML does not impose any limitations, but the IQFeed server does impose limitations
on the frequency of the requests and the amount of returned data. The limitations
depend on your specific IQFeed subscription. For example, your account might be
limited to a maximum of 1000 concurrently-streaming (“watched”) symbols. These
limitations are imposed by the IQFeed server based on your account; IQML supports
whatever subscription your account has, and does not limit the information in any
manner.
3. Can I see a demo of IQML?
You are most welcome to request a fully-functional trial version of IQML, to try the
product at no risk.
4. How does IQML compare to alternative products?
We believe that of all the currently available alternatives for connecting Matlab to
IQFeed, IQML provides by far the best functionality, value and cost-effectiveness.
You are most welcome to test all this using IQML’s free trial.
5. Does IQML come with an IQFeed or market subscription?
No – IQML connects to an existing IQFeed account. You will need to purchase the
IQFeed and market subscriptions separately from DTN.
6. Does IQML send you any information?
No – IQML only communicates with IQFeed. The only communication that is done
with IQML’s server is a verification of the license activation (a single hash-code).
7. How can I be sure IQML does not contain bugs that will affect my trades?
Well, there is never a 100% guarantee. The product is rigorously tested. So far
nothing major has been reported. IQML is a very stable and robust product, despite
the fact that new functionality is being added on a constant basis.
8. Is IQML being maintained? supported?
Yes, actively. Features and improvements are added on a regular basis, and I support
the users personally. You can see the list of ongoing improvements in IQML’s
change-log, listed in Appendix B of the IQML User Guide (this document). You can
see the very latest updates in the online version of this guide.107
107
http://IQML.net/files/IQML_User_Guide.pdf
IQML User Guide
135
9. I saw a nice new feature in the online User Guide – can I get it?
Once the IQML product is installed, you will be notified in the Matlab console
(Command Window) whenever a new version is available. You can always update
your installation to the latest version, directly from the Matlab console, as follows:
>> IQML('update')
Downloading the latest IQML version from http://IQML.net/files/IQML.zip
into C:\IQML\...
Download complete - installing...
Installation of the latest IQML version is now complete.
Please restart Matlab for the new version to take effect.
In addition, you can always download the latest version of IQML at any time from
http://IQML.net/files/IQML.zip.
10. What happens when the license term is over?
A short time before your license term is over, you will start to see a notification
message in your Matlab console (Command Window) alerting you about this:
*** Your IQML license will expire in 3 days (10-Mar-2018).
*** To extend your license please email info@IQML.net
This message will only appear during the initial connection to IQFeed, so it will not
affect your regular trading session. When the license term is over, IQML will stop
working. You can always renew or extend your license using the payment links on
http://IQML.net. If you wish to be independent of such annual renewals, you can
purchase a discounted multi-year license.
11. Can I transfer my IQML license to another computer?
Yes, simply email us and we will make the activation switch for you. At any one
time, each IQML license will only be activated on a single computer (unless you
purchase a site license). You can make up to 3 license activations per year at no extra
cost; additional switches will incur a small handling fee.
12. I have a laptop and desktop – can I use IQML on both?
Yes, but you will need to purchase two separate IQML licenses. IQML’s license is
tied to a specific computer (unless you purchase a site license).
13. Can IQML be compiled and deployed?
Yes, IQML can indeed be compiled. You do not need a separate license for the
compiled application on your development computer, since this computer is already
licensed. However, any other deployed computer will require a separate IQML
license, otherwise IQML will not run. If you wish to deploy IQML on a large scale, to
multiple computers, then contact me to discuss alternatives.
14. Is IQML provided in source-code format?
IQML is provided in encrypted binary form, like any other commercial software. If
you wish to get the source-code, then this is possible, subject to signing a separate
agreement and a higher cost. The benefit is that the source-code version has no
license fees and is not tied to any specific computer – you can install it on as many
computers as you wish within your organization. Contact me for details.
IQML User Guide
136
15. Do you provide an escrow service for IQML’s source-code?
Yes. There are two alternative levels of escrow that you can select:
1. At safe-keeping with a Wall-Street lawyer
2. Using NCC Group’s108 independent escrow service
Escrow services incur a non-negligible usage fee, but you may decide that it may be
worth it for ensuring business continuity. The choice is entirely yours.
If you wish to ensure business continuity, consider purchasing multi-year renewals in
advance, for a reduced cost. This will ensure that your license will be independent of
annual renewals for as many years as you select.
16. Is feature ABC available in IQML?
IQML supports the entire IQFeed API. This means that all the functionality that
IQFeed exposes in its API, is available in IQML. In most cases, this functionality is
available using an easy-to-use Matlab wrapper function. This includes all the
important trading and query functionalities. Some additional functionalities, which
are less commonly used, are supported by sending IQFeed the corresponding custom
command (see §9.4) and then processing the incoming IQFeed data (see §10). To
check whether a specific feature is available in the IQFeed API (and by extension, in
IQML), please refer to IQML’s User Guide (this document), IQFeed’s online
reference, or contact IQFeed customer service.
17. Can you add feature ABC in IQML for me?
I will be happy to do so, for a reasonable development fee that will be agreed with
you in advance. After the development, this feature will be available to all others who
purchase (or renew) the latest version of IQML, at no extra cost. Contact me by email
if you have such a request, to get a proposed quote.
18. Can you develop a trading strategy for me?
I will be happy to do so, for a reasonable development fee that will be agreed with
you in advance. Unlike development of IQML features, strategy development will
never be disclosed to others, and will not be integrated in IQML. It will be developed
privately for you, and will be kept secret. See §15 below for additional details. If you
have such a request, contact me by email to get a proposed quote.
19. Does IQML include back-testing/charting/data analysis/algo-trading?
No. IQML is only used for communication with the IQFeed server (retrieving data
from IQFeed servers), it does not include any data analysis, charting or back-testing
functionalities. Matlab is great at data analysis and visualization, so you can easily
develop your own analysis programs in Matlab, using the data from IQML. I have
extensive experience in developing complete backtesting and real-time trading
applications - see §15 below for additional details. I will be happy to either develop a
new application based on your specifications, or to integrate IQML into your existing
application, under a consulting contract.
108
http://nccgroup.com/en/our-services/software-escrow-and-verification/software-escrow
IQML User Guide
137
14 Troubleshooting
Error
NullPointerException
com.mathworks.jmi.bean.
MatlabBeanInterface.addCallback
IQFeed is not properly
installed
IQFeed cannot be
connected or started
or:
Cannot connect to
IQFeed
Description / solution
Sections
IQML cannot work properly unless its Java file
(IQML.jar) is added to Matlab’s static Java
2.1
classpath. Contact us to solve the problem.
IQFeed is not installed properly on the local
2.1
computer so IQML cannot connect to it.
IQML cannot connect to an active (running)
IQFeed client process, nor start one. Try to start
IQFeed’s client manually and then retry.
Some component of your activated computer
fingerprint has changed. Revert this change, or
contact us to modify the activated fingerprint.
Your IQML license will This is an alert on upcoming license expiration.
expire in 4 days (1It is not an error, and does not affect IQML’s
Mar-2018)
operation. Contact us to extend your license.
IQML’s license is limited in duration. When the
Your IQML license has
expired on 1-Jun-2018
license term expires, contact us to renew it.
IQML validates its license on the IQML.net
Cannot connect to
server.
Your internet connection may be down, or
IQML.net to validate
this domain may be blocked by your firewall
your IQML license
(your IT admin can unblock it).
The specified action is not [yet] a valid IQML
Action 'xyz' is not [yet]
supported
action, although it is planned for a future version.
Unrecognized IQML action The specified action is invalid in IQML. Refer to
'xyz'
the User Guide for a list of acceptable actions.
No value was provided for the specified
Missing parameter value:
all parameters must have a parameter. IQML parameters must be specified as
value
name-value pairs that have both name and value.
Value for parameter 'abc' The specified parameter value provided in your
should be a data
IQML command has an incorrect data type. Refer
type
to the User Guide for a list of acceptable values.
The specified parameter value must be a single
Value for parameter 'abc'
scalar value, not a numeric array. Refer to the
should be a scalar number
User Guide for a list of acceptable values.
The specified parameter name is not valid for the
'abc' is not a valid
parameter for the 'xyz'
specified IQML action. Refer to the User Guide
action
for a list of acceptable parameter names.
IQML is not activated
on this computer
IQML timeout: either
IQFeed has no data for
this query, or the Timeout
parameter should be set to
a value larger than 5
The query took longer than expected to return
data from IQFeed before IQML timed-out. Try to
set the Timeout parameter to a larger value.
2.1
2.2
2.2
2.2
2.2
2.4
3.1
3.1
3.1
3.1
3.1
3.2
IQML User Guide
138
Error
Description / solution
Sections
Warning: IQML timeout:
The query took longer than expected to return
only partial data is
data, so only partial results have arrived from 4.1, 5.1,
returned: the Timeout
IQFeed
before the IQML timed-out. To get all 7.2, 8.1
parameter should be set to
a value larger than 5
results set the Timeout parameter to a larger value.
The specified action is only available in the
The 'news' action is not
available in your Standard IQML Professional license and free trial. Contact
3.4
license of IQML
us to upgrade your license to access this feature.
Either you have no permission to access this
Symbol 'XYZ' was not found
3.4
Symbol, or this symbol is unknown by IQFeed.
(Missing digits in Matlab Matlab’s display format is possibly set to “short”
3.4
Command Window)
instead of “long”.
Undefined function
'struct2cell' for input
arguments of type 'double'
An empty result was returned, and this cannot be
converted into a Matlab cell-array.
3.5
Error using struct2table
(line 26) - S must be a
scalar structure, or a
structure array ...
An empty result was returned, and this cannot be
converted into a Matlab table object.
3.5
The Symbol parameter must
be specified for an XYZ
query when NumOfEvents>0
Queries that have NumOfEvents>0 must be
specified with a non-empty Symbol/Symbols.
4, 6
The date/time format of one or more of the query
parameters is incorrect. Refer to the User Guide
for a description of the acceptable formats.
No data is available for the specified query.
IQML historic data query
error: !NO_DATA!
Try to modify the query parameters.
Start data streaming (by sending a query with
Symbol "XYZ" is not
currently streaming
NumOfEvents>0) before querying streamed data
Try to actively disconnect and reconnect to
(IQML stops receiving
IQFeed streaming data)
IQFeed, or to restart the IQConnect application.
Unable to connect to L2IP IQConnect lost the connection to IQFeed’s servers.
server. Error Code: 10065
IQConnect will automatically reconnect as soon
Error Msg: A socket
as
possible, and in most cases you can ignore this
operation was attempted to
an unreachable host.
message. You can also try to actively reconnect
(or a similar variant)
to IQFeed, or to check your internet connection.
Out of memory
This Matlab error might occur when receiving
or:
huge amounts of streaming/historic data.
Maximum variable size
allowed by the program is
Different Matlab releases display different
exceeded
messages having the same basic idea.
or:
Requested array exceeds
Run
IQML on a computer with more memory,
maximum array size
or reduce the amount of stored/processed data.
preference
Set Matlab to use a larger Java heap memory size
java.lang.OutOfMemory
Error: Java heap space than the default value. This can be set in Matlab’s
preferences, or via a java.opts file.
Date parameter value must
be either a string
(YYYYMMDD, YYYY-MM-DD or
YYYY/MM/DD) or datenum
5
5
6
9.1
9.1
12
12
IQML User Guide
139
15 Professional services
In addition to IQML being offered as an off-the-shelf software program, advanced
Matlab consulting, training, and development are being offered. With over 25 years
of professional Matlab programming experience, including extensive finance/tradingrelated development in the past decade, I offer top-of-class Matlab consulting, with a
particular emphasis on the financial sector.
In particular, I have experience integrating quality production-grade Matlab programs
with online brokers such as IB (Interactive Brokers) and CQG; data-feed providers
such as DTN IQFeed, Bloomberg and Reuters; and websites such as finviz.com and
Nasdaq.com. The programs interfaced with various databases such as SQL Server,
MySQL, SQLite and Oracle, as well as Excel and raw-format data files. Programs
were developed on multiple Matlab releases, and on all Matlab-supported platforms:
Windows, Mac and Linux.
I have completed countless life-cycles of software requirements definition, design,
development, documentation, integration, testing, deployment, handover, maintenance
and support.
Much of my work derives from the financial sector. For example, I developed custom
software for a commodities fund in a Geneva bank; a backtesting and analysis
program for a large bank in Chicago; a currencies trading program for a hedge-fund
in Malta; data-analysis products for financial services firms in New-York; a portfolio
risk/exposure analysis program for an Israeli investment advisor; a charting GUI for a
San-Francisco hedge fund; and semi- and fully-automated algo-trading programs for
multiple clients around the globe.
Most of my revenue comes from repeat clients. I will be happy to provide references
of satisfied clients in US or Europe. With such an impressive track record, you
probably know some of them.
Development is typically done remotely; onsite consulting/development is also possible
upon request.
You can see a small sample of programs that I have developed below. Additional
samples can be seen on my consulting webpage.109
Anything developed under private consulting will be kept confidential and will not be
disclosed to others.
Contact us by email (info@IQML.net) to receive a proposal.
109
http://undocumentedmatlab.com/consulting
IQML User Guide
15.1 Sample program screenshots
140
IQML User Guide
141
IQML User Guide
142
IQML User Guide
143
15.2 About the author
With 25 years of professional software programming
experience, Yair Altman offers top-notch Matlab
consulting and training services.
Yair has worked extensively with Matlab and other
programming languages (Java, C#, C, C++ and others).
He has developed many programs with SQL and a variety
of databases, operating systems and hardware platforms.
Matlab community developers, and even MathWorks themselves, consider Yair to be
a top Matlab expert, as any simple online search will show. His website
UndocumentedMatlab.com is by far the largest and most active independent Matlab
site. Yair is also well-known from numerous submissions on the Matlab forums and
File Exchange; a MathWorks study determined110 that Yair is the third most influential
submitter in the entire Matlab user community. He regularly advises MathWorks, and
is a member of their Community Advisory Board, along with a handful of other members.
Yair has a specific experience in the finance sector, developing quality professional
Matlab programs that integrate with OMSes such as IB and CQG; data-feed providers
such as DTN IQFeed, Bloomberg and Reuters; websites such as finviz.com and
Nasdaq.com; databases such as SQL Server, MySQL, SQLite and Oracle, as well as
Excel and raw-format data files. These programs were developed on multiple Matlab
releases, and on all Matlab-supported platforms: Windows, MacOS and Linux.
Yair published two extensive highly-acclaimed textbooks
on advanced Matlab: MATLAB-Java programming111 in
2011 and Accelerating MATLAB Performance112 in 2014.
Both are considered the top references in their field.
Yair provides professional, cost
effective consulting and contract
work.113 He can do stuff that few
other Matlab programmers
know
is
even
possible,
delivering great value: top
quality code at reasonable cost.
Yair offers customized Matlab
training courses,114 in a variety of topics and levels, from
introductory to highly advanced. By combining a proven
track-record of 25 years of quality professional industry
programming, Matlab knowledge that few others possess,
and hands-on workshop, Yair’s training is highly effective.
110
http://blogs.mathworks.com/community/2013/01/15/giving-by-taking-file-exchange-acknowledgment-trees
111
http://undocumentedmatlab.com/books/matlab-java
112
http://undocumentedmatlab.com/books/matlab-performance
113
http://undocumentedmatlab.com/consulting
114
http://undocumentedmatlab.com/training
IQML User Guide
144
Appendix A – online resources
A.1 Official DTN IQFeed resources
IQFeed homepage – http://iqfeed.net
IQFeed API homepage – http://www.iqfeed.net/dev/api/docs
IQFeed symbol guide –
http://iqfeed.net/symbolguide/index.cfm?symbolguide=guide&displayaction=support
§ion=guide&web=iqfeed
IQFeed symbol lookup –
http://iqfeed.net/symbolguide/index.cfm?symbolguide=lookup&displayaction=support
§ion=guide&web=iqfeed
IQFeed users forum – http://forums.iqfeed.net
IQFeed live chat –
http://iqfeed.net/Fibonacci/index.cfm?displayaction=support§ion=chat
API customer service and technical support – support@iqfeed.net or
http://iqfeed.net/Fibonacci/index.cfm?displayaction=support§ion=contact
(please let them know that you are using IQML)
A.2 MathWorks webinars/presentation
MathWorks algorithmic-trading portal –
http://mathworks.com/discovery/algorithmic-trading.html,
http://mathworks.com/financial-services/algorithmic-trading.html
(includes Yair’s webinar “Real-Time Trading System in MATLAB”)
Algorithmic Trading Strategies with MATLAB Examples –
https://mathworks.com/videos/algorithmic-trading-strategies-with-matlabexamples-92899.html
Energy Trading & Risk Management with MATLAB –
https://mathworks.com/videos/energy-trading-risk-management-with-matlab81745.html
Cointegration and Pairs Trading with the Econometrics Toolbox –
https://mathworks.com/videos/cointegration-and-pairs-trading-with-econometricstoolbox-81799.html
Commodities Trading with MATLAB –
https://mathworks.com/videos/commodities-trading-with-matlab-81986.html
Creating professional-quality applications with MATLAB –
(Yair’s keynote presentation in the 2016 Munich MATLAB Expo using IQFeed)
https://undocumentedmatlab.com/blog/upcoming-public-matlab-presentations
A.3 Additional open-source Matlab resources
Spatial Econometrics Toolbox for Matlab – http://spatial-econometrics.com
Algorithmic trading code in the Matlab File Exchange –
http://www.mathworks.com/matlabcentral/fileexchange/?term=trading
IQML User Guide
145
Appendix B – change log
Cha ngelo g
The following table lists changes done to this document and IQML. Depending on the
date that you have installed IQML, your version may be missing some features
discussed in this document. You can always update to the latest version – see §2.4.
Note: The last column indicates the change type: F=functional; D=documentation.
Version
Date
Section
Description
0.80 2017-10-17
Beta integration of IQML in a user trading program
1.00 2018-02-26
First commercial release of IQML
1.01
1.02
1.03
2018-03-11
8.1
4.3.2
2018-03-12 4.3.3
7.1, 11
3.2
4.1, 6.1
2018-03-19
6.1
1, 2.1
2.1
3.2
5
6.1
1.04
6.2
2018-04-01 4.37
7.3
7.4
7.5
8-13
8.2
10
A.2
Enabled message-specific user callbacks;
Added additional information to callback eventData
Clarified filtering meta-symbols such as 'BZRatings'
Added relevant symbols list in returned news story data
Clarified automatic connection re-establishment
Enabled Symbol and Symbols as synonymous params
Improved ticks request logic & the returned data fields
Enabled requesting streaming ticks/quotes for multiple
symbols at once, in a single IQML command
Clarified that IQFeed client can run on Linux/Mac via
Parallels/Wine, as well as natively on Windows/Mac
Added support for native Mac IQFeed client (untested)
Added new MsgParsingLevel general parameter, for
improved callback run-time performance
MaxDataItems input parameter is renamed MaxItems
Some result output fields renamed for consistency;
BufferSize input parameter is renamed MaxItems for
consistency; clarified the documentation text
Added new streaming regional updates functionality
Moved the news functionality into a new chapter (#7)
Added newline characters between separate paragraphs
in the reported news-story text, for better readability
Clarified that default Date is today; clarified that story
count also includes non-subscribed news sources
Added new streaming news functionality
Renumbered chapters 7-12 as 8-13, to make room for
the new chapter (7) on the news functionality
Added new section on callback run-time performance
Added timestamp and channel info to debug printouts
Added an online MathWorks resource
F
F
F
D
F
D
F
F
F
D
F
F
F
F
F
D
F
D
F
D
D
F
D
IQML User Guide
Version
Date
Section
146
Description
Added note that in some cases users may need/want to
D
specify the IQFeed connection Username, Password
Added new symbols and numeric market codes lookup
3.1, 8
F
functionality
2.1
3.2, 4.1
5, 7.2 Modified the default Timeout value from 3 to 5 [secs]
3.5 Added new section on handling returned data format
1.05
1.06
1.07
1.08
1.09
1.10
5.5
2018-05-16
6.3
1.12
F
Indicated that IQFeed server may possibly limit reported
interval bars depending on exchange, data subscriptions; D
Clarified that IntervalSize must be >1 for volume/ticks
3.4, 4.3,
Clarified that news, level 2 (market depth), alerts,
6.2, 6.4,
options/futures chain lookup, and regional updates are D
7, 8.2,
only available in the Professional license and free trial
2018-05-23 10.5, 12
12 Added alerts functionality
F
13-15
7.2
11-12
1.13
D
Clarified that micro-sec time resolution depends on the
D
IQFeed client version, the market, and the security type
Added basic support for options-chain and futures-chain
8.2, 10.3
F
symbol lookup (better support is planned for next version)
Renumbered chapters 8-13 as 9-14, to make room for
9-14
D
the new chapter (8) on the lookup functionality
Enabled specifying IQFeed Username and Password;
9.1
F
Added a 10-sec timeout on IQFeed connection attempts
9.3 Added extra port-specific stats when AddPortStats=1 D
2018-04-08 8.2 Added options/futures chain lookup functionality
F
2018-04-10 9.1 Added info msgs on server connections/disconnections F
4.1, 6.1 Added the Symbol field to returned quotes data struct F
2018-04-11
10.4 Added usage example of realtime quotes user callback D
2018-04-16 6.3 Added Interval Bars functionality
F
2018-05-04 2.4 Added example of update notification on a new version D
2018-04-05
4.3, 6.4,
Added Market Depth (Level 2) functionality
10.5
1.11
F
2018-05-25
11.2
11.1,
11.2
3.1
5.4
1.131 2018-05-28
6.2
7.2
Renumbered chapters 12-14 as 13-15, to make room
D
for a new chapter (12) on the alerts functionality
Enabled auto-fetch of full news story in news headlines
F
query (streaming/blocking) using GetStory parameter
D
Switched between sections 11,12 in the User Guide
Enabled reporting the full news story (in addition to
F
headline) in news alerts using GetStory parameter
Added regional updates alert functionality (in addition
F
to news/quote/intervalbar alerts)
Fixed bug in accepting struct-based input parameters F
Clarified that IntervalSize must be >1 for vol/tick bars D
Fixed typo in regional update action (should be 'regional') D
Fixed bug in the news headlines functionality
F
IQML User Guide
Version
Date
Section
1.15
1.16
1.17
1.18
1.19
1.20
Description
Enabled specifying multiple Symbols in a single
F
Fundamental-data query
Enabled specifying multiple Symbols in a single
2018-05-30 6.2
F
streaming Regional updates query
Enabled specifying multiple news headline ID values
7.3
F
in a single news story query
Updated compatibility notice for Matlab release R2018b D
4.1, 6.1, Enabled querying snapshot (top of market) & streaming
F
14 data of multiple symbols at once, in a single IQML query
Fixed: querying multi-symbol fundamental data
4.2
F
sometimes returned empty results
Fixed: debug data was displayed when streaming queries
6.1-6.3
F
2018-07-08
were requested (now only displayed if Debug=1)
Enabled querying fundamental data of all symbols in an
8.2
F
options/futures chain at once, in a single IQML query
Enabled querying snapshot (top of market) data of
8.2
F
entire options/futures chain at once, in a single query
Fixed: IQML query during IQFeed connection
9.1
F
sometimes returned empty/error results
3.6 Added new section on general run-time performance
D
2018-07-09 5.1-5.5 Improved performance (speed) of historical data queries F
10.2 Updated the section on callback-related performance
D
Clarified that IQFeed limits ticks/interval data to 8 days
5.4, 5.5
D
during US trading hours, 180 calendar days outside them
Clarified that IQFeed allows up to 500 concurrently6.1
D
streaming symbols, unless you pay DTN for more symbols
Clarified that IntervalSize must be >1 for interval bars
2018-07-30 6.3
D
that use IntervalType = 'ticks' or 'volume'
Enabled retrieval and cancellation of streaming data for
6.1-6.4
F
multiple/all streamed symbols in a single IQML command
Clarified that option/future chain name might change
8.2
D
when corporate actions (such as splits) occur
3.1, 3.5 Added optional errorMsg output for IQML commands F
9.1 Fixed problem of duplicate fields during initial connection F
2018-08-03
Improved the reliability of a programmatic IQFeed
9.1
F
disconnect/reconnect
Added the RaiseErrorMsgs parameter to control
3.2, 12
F
whether IQFeed errors should raise a Matlab error
2018-08-06
4.1, 5.1, Message about partial data received due to Timeout is
F
7.2, 8.1 now a Matlab warning message, not an error message
5.1-5.5 Enabled requesting history data for multiple symbols in
F
14 a single IQML command
2018-08-07
5.1, 5.4, Automatically convert BeginDateBeginDateTime,
F
5.5 EndDateEndDateTime (i.e. try to fix usage error)
4.2
1.14
147
IQML User Guide
Version
1.21
1.22
1.23
1.24
Date
Section
Description
8.1 Enabled looking up symbols by market(s), sec-type(s)
148
F
Clarified
that
IQFeed
only
enables
lookup
of
active
2018-08-10
8.2 (non-expired) options; a list of expired options is
D
available separately as a downloadable text file.
Enabled NearMonths values of 0-12, not just 0-4, for
8.2 options/futures chain. Note: this is based on undocumented F
2018-08-13
IQFeed functionality, so might not work in some cases.
3.2 etc. Limited the Timeout parameter values to 0-3000 [secs] F
Clarified regarding historical intervals data limitations;
5.4 Clarified that IQFeed’s interval data typically exclude D
“O” trades (see §5.5).
2018-08-14
Fixed a problem of possible bad connection to IQFeed
9.1
F
during the initial connection by IQML
Limited the Timeout parameter values to 0-9000 [secs],
3.2 etc.
F
with 0 indicating infinite (i.e. no-limit) timeout
Clarified that while IQFeed typically limits historic tick
5.5 data to 180 days (outside trading hours), extended (older) D
tick data can possibly be purchased from DTN
2018-08-31
Enabled NearMonths values of 0-99, not just 0-12, for
8.2 options/futures chain. Note: this is based on undocumented F
IQFeed functionality, so might not work in some cases.
Enabled multiple Matlab processes on the same computer
9.1
F
to run IQML concurrently (Beta)
IQML User Guide
Version
2.00
(major
update)
2.02
2.03
2.04
Date
Section
149
Description
This is a major update. Highlights: query parallelization
and multiple usability/functionality fixes/improvements
Enabled parallel processing of IQML commands within
(all) parfor/spmd blocks, and parallel internal processing via F
the UseParallel parameter (Professional license only)
2.1-2.4 Added the license type to the output of IQML('version') F
3.1 Clarified the actions available in Pro vs. non-Pro license D
3.5 All returned data arrays are now column vectors
F
Using the 2nd (optional) output of IQML (errorMsgs)
3.5
now implies a default value of false for RaiseErrorMsgs F
3.5, Fixed various typos in code snippets, that would have
D
8.2-8.7 resulted in errors or bad data if used as-is
4.1-4.4 Modified reported data format when NumOfEvents >1 F
Issued a warning when requesting more symbol quotes
F
2018-09-05 4.1, 8.2 than your IQFeed account limit
4.3 Added new section on blocking interval bars functionality F
4.3, 5.4, Clarified that IntervalSize must be ≥100 for volume
F
6.3 bars (a new limitation of IQFeed)
4.3, 5, Enabled specifying dates and date-times using Matlab
F
6.3, 7.4 datetime objects (in addition to datenums and strings)
4.34.4 Moved the blocking market-depth section to §4.4
D
5.1, 5.4, Clarified that MaxItems has precedence over BeginDate
D
5.5 /Time when more data items are available than MaxItems
5.4, 5.5 Clarified that in IQFeed and IQML, 'ticks' = 'trades'
D
6.1-6.4 Added Symbol field to returned streaming data struct
F
Story count for symbols that have no related news story
7.4
is reported as 0 (such symbols were previously skipped) F
Added Exchanges, ServerVersion, ServiceType fields to
9.3
F
the returned client stats data
11 Fixed various things with the Alerts functionality
F
11.2 Reorganized & clarified the Alerts Configuration section D
Clarified that IntervalSize must be < 86400 for secs
4.3, 5.4,
bars (a new limitation of IQFeed); added warning when F
6.3
user attempts to use an invalid IntervalSize value.
Clarified that streaming/latest interval bars are subject to
4.3, 6.3
the same limitations as those imposed on historical bars D
2018-09-13
Clarified that full-minute interval bars are excempt from
5.4
the 8/180-day limitation imposed by IQFeed’s servers D
Added detection & report for a case of a non9.1
F
communicative background IQConnect process
Fixed a problem with the license check that caused
2018-09-30 9.1
F
IQFeed disconnections
Improved download speed of historical data queries
5
F
2018-10-02 6, 7.5, LatestEventTimestamp is now reported in seconds (not
F
9.2 msecs) resolution by default, unless Debug is 1 or true
IQML User Guide
150
Version
Date
Section
Description
2.05 2018-10-13 4.1, 6.1 Added Fields parameter to enable dynamic fields-set
F
4.1 Added some clarifications on the new Fields parameter D
2.06 2018-10-15
6.1 Minor fixes, performance speedup of streaming quotes F
3.4 Minor text clarifications; added timestamp examples
D
4.3, 5.4, Clarified that IQFeed’s limitations on live 'secs' interval
D
6.3 bars are stricter than limitations on historical intervals
Enabled using MaxDays as synonym for the Days
F
parameter in historic interval queries
Fixed a problem with the license validation that
9.1
F
prevented connection in certain cases
Fixed a few small edge-cases with sending custom
9.4
F
commands to IQFeed
3.6 Added clarifications on the use of query parallelization D
5.1, 5.4, Enabled parallelized historic data queries (daily/interval/
2.08 2018-10-28
F
5.5 ticks) that have date/time range (Professional license only)
A.1 Added IQFeed’s users forum to list of online resources D
3.1 Fixed a bug in parsing input parameters in struct format F
2.09 2018-11-07
Added explanation on how to use a customized Fields
3.6
D
parameter to improve the query speed of market quotes
Added ability to revert back to the previous IQML
2.4
F
version at any time.
Added a table listing all the available quote data fields
4.1
D
(customizable via the Fields parameter)
Added description fields for the Bid_Market_Center,
4.1 Ask_Market_Center and Last_Market_Center fields,
F
when reported in a quotes message from IQFeed.
2.10 2018-11-14
Added a new Greeks action, to calculate Greeks, fair
4.5 value price and implied volatility for options
F
(Professional license only)
Clarified that DTN limits historical data retrieval in
5.1 IQFeed’s trial account. Historical data queries in such D
accounts may yield fewer data points than requested.
Clarified that tick (update/quote) messages are streamed
6.1
D
whenever any of the requested Fields gets updated.
DaysPerYear parameter was renamed AnnualFactor;
Duration parameter was renamed DaysToExpiration;
Vega, Rho, Veta, Ultima are no longer divided by 100 by
default (compatibility with Matlab Financial Toolbox,
Maple & NAG); minor fix for Veta (negative value);
2.11 2018-11-22 4.5
F
added new fields in the reported data struct: Omega +
Lambda (synonyms), CRho, Color, Annual_Factor_Used.
Clarified differences of IQML’s Greek values vs.
Matlab’s Trading Toolbox, NAG, and Maple.
Added a table explaining all the reported Greek values.
2.07
2018-10-21
5.4
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.5 Linearized : No Page Count : 150 Language : en-US Producer : Microsoft® Word 2016 Creator : Microsoft® Word 2016 Create Date : 2018:11:28 19:46:19+02:00 Modify Date : 2018:11:28 19:46:19+02:00EXIF Metadata provided by EXIF.tools