Get event information

When you want to find detailed information about a specific event you can use the QueryEventArticlesIter and QueryEvent classes. The classes can be used to obtain all the information that is in the Event Registry shown on the event page (i.e. http://eventregistry.org/event/eng-2940883).

QueryEventArticlesIter

The QueryEventArticlesIter class is a helper class that allows one to quickly obtain the list of articles that are associated with a particular event.

Example of usage

A simple example that will list all English articles about event eng-2940883 is as follows:

import { EventRegistry } from "eventregistry";
const er = new EventRegistry({apiKey: "YOUR_API_KEY"});
const iter = new QueryEventArticlesIter(er, "eng-2940883", {lang: "eng"});
iter.execQuery((item) => {
   console.info(item);
});

The QueryEventArticlesIter accepts the following arguments:

• er: an instance of EventRegistry class that should be used to obtain the necessary data.
• eventUri: an URI of a single event.
• Additional optional arguments that are passed as the third in line go as follows:
  • lang: array or a single language in which to return the list of matching articles. By default, the list of 5 languages is used (["eng", "deu", "zho", "slv", "spa"]).
  • sortBy: the order in which event articles are sorted. Options: id (internal id), date (published date), cosSim (closeness to event centroid), sourceImportance (importance of the news source), socialScore (total shares in social media).
  • sortByAsc: should the results be sorted in ascending order (True) or descending (False).
  • returnInfo: what details should be included in the returned information. See details.
  • articleBatchSize: number of articles to download at once (we are not downloading article by article) (at most 200).

Methods

execQuery(callback, doneCallback)

The execQuery accepts 2 arguments:

• callback: Anonymous function that is called with a single argument, which is the current item in the iteration.
• doneCallback: an anonymous function that is called when the iteration is complete.

QueryEvent

The QueryEvent class provides a more extended set of functionalities for a given event. The class can be used to obtain not only the list of associated articles but also core event information, a timeline of reporting about the event, list of top news sources reporting about the event, related events, etc.

Example of usage

To start, let us look at a simple example of usage of the QueryEvent() class to obtain information about event with URI eng-2940883:

import { EventRegistry, QueryEvent, RequestEventInfo, RequestEventArticles, RequestEventKeywordAggr} from "eventregistry";
const er = new EventRegistry({apiKey: "YOUR_API_KEY"});
// we are interested in event with URI eng-2940883
const q = new QueryEvent("eng-2940883");
// get core event information (location, date, top concepts, ...)
q.addRequestedResult(new RequestEventInfo());
// get top 10 articles in English - not that multiple addRequestedResult() calls in a query are
// allowed only for subscribed customers - free users should use setRequestedResult to set a single return type
q.addRequestedResult(new RequestEventArticles({count: 10, lang: ["eng"]}));
// get top keywords for the event
q.addRequestedResult(new RequestEventKeywordAggr({lang: "eng"}));
er.execQuery(q);

The resulting JSON object returned by the promise will contain the following:

{
    "eng-2940883": {
        "info": { ... },    // details about the event
        "articles": { },    // requested articles
        "keywordAggr": {}   // top keywords
    }
}

The returned information about articles in the event follows the Article data model.

QueryEvent constructor accepts a single argument eventUriOrList:

new QueryEvent(eventUriOrList);

The eventUriOrList can be a string representing a single event URI or it can be a list of event URIs (at most 200).

Returned information

QueryEvent class provides a method addRequestedResult() that can be used to specify which details about the event you wish to obtain. The argument in the method call has to be an instance that has a base class RequestEvent. Free users are only allowed one requested result per call and should instead use the setRequestedResult() method. Below are the classes that can be specified in the addRequestedResult or setRequestedResult() calls:

RequestEventInfo

new RequestEventInfo({returnInfo = new ReturnInfo()} = {});

RequestEventInfo class can provide the core information about the event - the title, summary, location, date, concepts, categories and the number of articles reporting about the event.

• returnInfo: sets the properties of various types of data that is returned (event details, concepts, categories, news sources, ...)

RequestEventArticles

new RequestEventArticles({
    page = 1,
    count = 20,
    lang = mainLangs,
    sortBy = "cosSim", 
    sortByAsc = false,
    returnInfo = new ReturnInfo(),
} = {});

RequestEventArticles returns details about the articles assigned to the event.

• page: which page of the articles to return (starting from 1).
• count: number of articles to return (max 200).
• lang: languages in which should be the returned articles. By default 5 languages are used (eng, deu, spa, chi, slo).
• sortBy: how should the articles be sorted before we decide which ones to return. Options: id (internal id), date (published date), cosSim (closeness to event centroid), socialScore (total shares in social media).
• returnInfo: sets the properties of various types of data that is returned (articles, concepts, categories, news sources, ...)

RequestEventArticleUrisnew

new RequestEventArticleUris({lang = mainLangs, sortBy = "cosSim", sortByAsc = False} = {});

RequestEventArticleUris returns a simple list of article URIs (which are newsfeed IDs) for articles that are assigned to the event. The sortBy and sortByAsc parameters determine in which order should the URIs be returned.

RequestEventKeywordAggr

new RequestEventKeywordAggr({lang = "eng"});

RequestEventKeywordAggr returns top keywords extracted from articles in the specified language. The event has to be reported in the given language, otherwise no keywords can be returned.

RequestEventSourceAggr

RequestEventSourceAggr returns the information about the news sources that reported about the event.

RequestEventDateMentionAggr

RequestEventDateMentionAggr returns information about the dates that were mentioned in the articles about the event.

RequestEventArticleTrend

RequestEventArticleTrend provides a list of core article information that can be used to display how the intensity of reporting about the event has been changing over time.

RequestEventSimilarEvents

new RequestEventSimilarEvents({
    count = 20,
    source = "concept",            // how to compute similarity. Options: concept cca
    maxDayDiff = Number.MAX_SAFE_INTEGER, // what is the maximum time difference between the similar events and this one
    addArticleTrendInfo = false,   // add info how the articles in the similar events are distributed over time
    aggrHours = 6,                 // if similarEventsAddArticleTrendInfo == True then this is the aggregating window
    includeSelf = false,           // should the info about the event itself be included among the results
    returnInfo = new ReturnInfo(),
} = {})

RequestEventSimilarEvents returns a list of events related to the given event.

• count determines the number of similar events to return (max 200)
• source criteria that is used to compute similar events. Options include: concept (similarity is computed using the most relevant concepts in the event) or cca (similarity is computed based on how similar are the articles in event with articles from another event in the language independent space).