Get Event Information

When you want to find detailed information about a specific event you can use the QueryEvent class. The class 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/<event-id>).

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

Example

from eventregistry import *
er = EventRegistry()
# we are interested in event with URI 2338129
q = QueryEvent("2338129")
# get core event information (location, date, top concepts, ...)
q.addRequestedResult()
# 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:

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

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