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:

from eventregistry import *
er = EventRegistry(apiKey = YOUR_API_KEY)
iter = QueryEventArticlesIter("eng-2940883")
for art in iter.execQuery(er, lang = "eng"):
    print art

QueryEventArticlesIter constructor accepts a single argument eventUri which represents the URI of a single event.

Methods

The class has two main methods: count() and execQuery().

count(er,
    lang = mainLangs)

count(er) method simply returns the number of articles assigned to the event that are in the specified language(s). Expected arguments are:

• er is the instance of the EventRegistry class.
• lang is a string or a list of strings representing the languages in which we wish to count the articles. By default, the list of 5 languages is used (["eng", "deu", "zho", "slv", "spa"]).

execQuery(er,
    lang = mainLangs,
    sortBy = "cosSim", sortByAsc = False,
    returnInfo = ReturnInfo(articleInfo = ArticleInfoFlags(bodyLen = 200)),
    articleBatchSize = 200)

The execQuery returns an iterator over the articles in the event. The meaning of the parameters the execQuery method accepts is as follows:

• er: instance of EventRegistry class that should be used to obtain the necessary data.
• 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: 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).

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

from eventregistry import *
er = EventRegistry(apiKey = YOUR_API_KEY)
# we are interested in event with URI eng-2940883
q = QueryEvent("eng-2940883")
# get core event information (location, date, top concepts, ...)
q.addRequestedResult(RequestEventInfo())
# get top 10 articles in English
q.addRequestedResult(RequestEventArticles(count = 10, lang = ["eng"]))
# get top keywords for the event
q.addRequestedResult(RequestEventKeywordAggr(lang = "eng"))
res = er.execQuery(q)

The resulting JSON object contained in res will contain:

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

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 single 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. Below are the classes that can be specified in the addRequestedResult calls:

RequestEventInfo

RequestEventInfo(returnInfo = 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

RequestEventArticles(page = 1,
    count = 20,
    lang = mainLangs,
    sortBy = "cosSim", sortByAsc = False,
    returnInfo = 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, ...)

RequestEventArticleUris

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

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

RequestEventSimilarEvents(count = 20,
    source = "concept",            # how to compute similarity. Options: concept cca
    maxDayDiff = sys.maxint,       # 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 = 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).