News Requests

In this tutorial we'll cover news requests and subscriptions.

This section assumes a connection has been established; see the getting started tutorial as necessary.

Make a news request

Here's a very simple news request that will get the most recent news story's headline and publish time:

// Initiate a getStories request to the ContentGateway.
const requestHandle = client.news.getStories({
    query: "*",
    fieldIds: [activCgApi.FieldId.FID_HEADLINE, activCgApi.FieldId.FID_STORY_DATE_TIME]
});

// Asynchronously iterate records.
for await (const record of requestHandle) {
    console.log(`${record.newsSymbol} fields:`);

    // Synchronously iterate fields in the record.
    for (const field of record.fieldData) {
        console.log(`${activCgApi.FieldId[field.id]} = ${field.value}`);
    }

    console.log();
}

The complete set of available parameters for a getStories request are described here. Some more detailed discussion of the most interesting properties follows.

query

This is used to specify what stories you wish to be returned. It can contain tags and operators for those tags.

Operators

The operators are AND OR NOT (), e.g. body=((microsoft OR apple) AND NOT ibm. Note that the NOT operators can only be ANDed.

To retrieve every story, use * (an asterisk).

Tags

Tags are specified as: tag=value. Valid tags are:

Tag Description
body Query a news story body.
cat Query the category code.
head Query the headline.
magazine The magazine to search on.
newssymbol The actual symbol of a story.
supplier The supplier of news stories to search on.
symbol A stock symbol referenced in a story.

Here are some example queries:

  • cat=industrial AND symbol=IBM.
  • magazine=(DJDN OR BIZ) AND symbol=MSFT. AND body=report
  • body=(apple AND intel)
  • head=yahoo
  • newssymbol=241b3044%BIZ
  • supplier=comtex

fieldIds

A list of fields to request. Fields of interest for news stories are:

  • FID_HEADLINE: the story's headline.
  • FID_MAGAZINE: the story's source as a mnemonic, e.g. DJDN.
  • FID_SUPPLIER: the story's source as plain text, e.g. Dow Jones.
  • FID_STORY_BODY: the story's body.
  • FID_STORY_DATE_TIME: the publication time of the story.
  • FID_LANGUAGE: the language of the news story, e.g. en, fr, en-us.
  • FID_CHARACTER_SET: the character set of the story that should be used for display, e.g. ISO-8859-1.
  • FID_PREVIOUS_NEWS_SYMBOL, FID_NEXT_NEWS_SYMBOL: for those sources that allow stories to be linked together, these two fields refer to the previous and next symbol, respectively. This is usually to provide further updates to a breaking story or to shorten larger stories. (Presently only supported by Dow Jones.)
  • FID_EXPIRATION_DATE: is the date the story should be removed and only applies to temporary stories.
  • FID_SYMBOL_LIST: a space delimited list of market data symbols for entities related to this story.
  • FID_CATEGORY_CODE_LIST: a space delimited list of category codes.
  • FID_NEWS_STATE: contains state information about the news story. See NewsState for possible values.

Subscription

In order to receive new stories matching your query, or updates to stories, simply provide an updateHandler property in the request's parameters:

function displayFields(record) {
    console.log(`${record.newsSymbol} fields:`);

    // Synchronously iterate fields in the record.
    for (const field of record.fieldData) {
        console.log(`${activCgApi.FieldId[field.id]} = ${field.value}`);
    }

    console.log();
}

// Initiate a getStories request to the ContentGateway.
const requestHandle = client.news.getStories({
    query: "*",
    fieldIds: [activCgApi.FieldId.FID_HEADLINE, activCgApi.FieldId.FID_STORY_DATE_TIME],
    updateHandler: (update) => displayFields(update)
});

// Asynchronously iterate records.
for await (const record of requestHandle) {
    displayFields(record);
}

Unsubscribing

The delete method, provided by the IRequestHandle object returned by the getStories request, will cancel subscriptions resulting from the request.

Example

Here is a full example of the points covered in this tutorial:

// You may have to update the userId and password fields below.
const userId = "__ACTIV_FEED_USERNAME__";
const password = "__ACTIV_FEED_PASSWORD__";
const url = "ams://cg-ny4-replay.activfinancial.com/ContentGateway:Service";

function displayFields(record) {
    console.log(`${record.newsSymbol} fields:`);

    // Synchronously iterate fields in the record.
    for (const field of record.fieldData) {
        console.log(`${activCgApi.FieldId[field.id]} = ${field.value}`);
    }

    console.log();
}

(async function() {
    try {
        console.log("Connecting...");

        const client = await activCgApi.connect({
            url,
            userId,
            password
        });

        console.log("Connected. Initiating data request...");

        // Initiate a getStories request to the ContentGateway.
        const requestHandle = client.news.getStories({
            query: "*",
            fieldIds: [activCgApi.FieldId.FID_HEADLINE, activCgApi.FieldId.FID_STORY_DATE_TIME],
            updateHandler: (update) => displayFields(update)
        });

        // Asynchronously iterate records.
        for await (const record of requestHandle) {
            displayFields(record);
        }

        // Let's get two seconds of updates then unsubscribe.
        await activCgApi.asyncSleep(2000);

        console.log("Unsubscribing...");
        requestHandle.delete();
    } catch (e) {
        console.error(`Error: ${e}`);
    }
})();
Try it out in the playground

Also in this Section