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'

>> data.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: 'CPR'
Description: 'PR Newswire'
AuthenticationCode: '1X'
IconID: 5
Minors: [1×0 struct]

>> data.Majors(7)
ans =
Source: 'BEN'
Description: 'Benzinga Pro'
AuthenticationCode: '1a'
IconID: 10
Minors: [1×0 struct]

News configuration queries do not have any user-settable parameters.

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
Datenum
Text
Story
URL

>> data(1)
ans =
Source: 'CPR'
ID: 21988707473
Symbols: {}
Timestamp: '2018-03-05 06:45:53'
Datenum: 737124.281863426
Text: 'The Surface Disinfectants Market is Expected to Grow at a CAGR
of 8.3% to a USD '
Story: ''
URL: ''

>> data(2)
ans =
Source: 'BEN'
ID: 21988707468
Symbols: {'BZFDA' 'CVRS'}
Timestamp: '2018-03-05 06:45:53'
Datenum: 737124.281863426
Text: 'Corindus Receives FDA Clearance for First Automated Robotic
Movemen...'
Story: ''
URL: ''

>> data(3)
ans =
Source: 'RTB'
ID: 21988701358
Symbols: {'BSX'}
Timestamp: '2018-03-05 06:42:33'
Datenum: 737124.279548611
Text: 'Boston Scientific Corp Q4 adjusted earnings Miss Estimates'
Story: ''
URL: ''

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 specified in US Eastern time-zone.123

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. Perhaps the Timeout parameter should be set to a value larger than 5 or the NumOfEvents parameter to a value smaller than Inf

data =
738×1 struct array with fields:
Source
ID
Symbols
Timestamp
Datenum
Text
Story
URL

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:124

>> 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.125 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:
...

>> data = IQML('news', 'DataType','headlines', 'Symbols',{'BSX','AAPL'})
data =
677×1 struct array with fields:
...

>> data = IQML('news', 'DataType','headlines', 'Symbols','BSX:AAPL:GOOG')
data =
841×1 struct array with fields:
...

Note: Queries with a non-empty Symbols filter are much faster than symbol-less queries (IQFeed takes an extra 1-3 secs to process symbol-less queries).

You can also 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','headlines', 'Symbols','BSX:GOOG:AAPL', ...
'Sources','DTN:CPR:BEN')
data =
745×1 struct array with fields:
...

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).

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');

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:
ID
...

Date can be specified in various 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'). Note: IQFeed only stores headlines of the past 180 days.126

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):127

>> data = IQML('news', 'DataType','headlines', 'MaxItems',50)
data =
50×1 struct array with fields:
Source
ID
...

For performance reasons, it is always better to limit the query at the source (using the various filter parameters Symbols, Sources, Date and MaxItems), rather than filtering the messages after they are received. Using filter parameters reduces the IQFeed server response time,128 network download time, and IQML processing time.

By default, only the headline text is returned. To also fetch the full news-story text that is associated with each headline, set GetStory to true:129

>> 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 Environment-Friendly 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...
For comments and feedback: contact editorial@rttnews.com ↵Copyright(c) 2018 RTTNews.com All Rights Reserved'
URL: 'editorial@rttnews.com'

Each news story takes 0.3-0.5 secs to download, so querying the story text for multiple headlines can take a long time. For example, such a query might take a full minute for 100 headlines. If you have Matlab’s Parallel Computing Toolbox and the Professional IQML license, you can parallelize this 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.

News headlines queries with GetStory are composed of an initial headlines query, followed by multiple news-story queries (§7.3) for each of the reported headline IDs. Such queries with GetStory have an automatic minimal Timeout value of 60 [secs]. The Timeout parameter has a practical effect only on the initial headlines query, as well as the subsequent story text queries (individually). The total query time does not have a time-out and can take much longer than the specified Timeout. A Timeout of 60 (the default/min value for such queries) allows fetching up to ~10-20k headlines in theory (depending on network/computer speed and MaxItems/Date parameter values), but only up to 4k headlines are returned in practice (IQFeed’s undocumented limit). The news-story queries for these 4k headlines could take an extra 20-40 minutes (depending on network/computer speed), unless you parallelize the query. This would not be cut short by Timeout, since Timeout affects each news-story query seperately. You can only stop the query by typing Ctrl-C in Matlab’s console (Command Window).

The following parameters affect (filter) news headlines queries:

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, see §7.2). 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.'
URL: ''

>> 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-q4-
adjusted-earnings-miss-estimates.aspx) For comments and
feedback: contact editorial@rttnews.com. Copyright(c) 2018
RTTNews.com All Rights Reserved.'
URL: 'http://alpha.rttnews.com/9583/boston-scientific-corp-q4-
adjusted-earnings-miss-estimates.aspx'

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'
URL: 'http://www.businesswire.com/news/home/20180312005490/en/'

As can be seen in the examples here, the URL field is automatically extracted from the story Text, when such a URL is reported (many stories do not report a URL). When a webpage URL is not detected but an email address is, the URL field will report it:

>> data = IQML('news', 'DataType','story', 'ID',22386314395)
data =
ID: 22386314395
Symbols: {'CMRE-PB' 'CMRE-PC' 'CMRE-PD' 'CMRE-PE' 'CMRE'}
Text: 'March 01, 2021↵ MONACO, March 01, 2021 (GLOBE NEWSWIRE) -- Costamare Inc. (the Company or our) (NYSE: CMRE) announced today that its Annual Report on Form 20-F for the fiscal year ended December 31, 2020 (the Annual Report) has been filed with the U.S. Securities and Exchange Commission and can be accessed on the Companys website, www.costamare.com, in the Investors section under Annual Reports... % full text redacted here
Company Contacts:↵ Gregory Zikos - Chief Financial Officer Konstantinos Tsakalidis - Business Development↵ Costamare Inc., Monaco Tel: (+377) 93 25 09 40 Email: ir@costamare.com'
URL: 'ir@costamare.com'

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.'
URL: ''

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.

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) % non-existing headline ID
ans =
[]

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
URL

>> data(1)
ans =
ID: 22018991229
Symbols: {}
Text: 'May 29, 2018 ↵Dublin, May 29, 2018 (GLOBE NEWSWIRE) -- The European Financing in Cleantech Innovation report...
URL: ''

>> 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. ...
URL: ''

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).

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 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:

7.5 Streaming news headlines

The streaming news mechanism has two parts, just like streaming ticks (§6.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.

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); % streaming, non-blocking

data = IQML('news', 'NumOfEvents',100); % 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 inf133. 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.134

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.135

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]
GetStory: 0

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

Command – the command sent to IQFeed.136

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

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

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 to reach IQFeed and during this time a few additional items may have arrived.

LatestEventDatenum – Matlab numeric datenum representation of the LatestEventTimestamp.

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

DataType – always equal to 'news' for streaming headlines.

ProcessType – 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.

Symbols – 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).

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

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

LatestData – latest headline event received from IQFeed.

GetStory – a flag indicating if story text was requested (GetStory parameter)

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'
Datenum: 737145.356550926
Text: 'Baird Maintains Outperform on Facebook Lowers Price Target to $210'
Story: ''
URL: ''

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.137

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); % equivalent

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: