Skip to content

Feed of new articles events

Gregor Leban edited this page Oct 14, 2026 · 10 revisions

It is very easy in Event Registry to subscribe to a feed of new articles or events.

Feed of new articles

The class GetRecentArticles is able to provide you with new articles as they are imported into Event Registry. A simple example of use would be:

from eventregistry import *
import time

er = EventRegistry(apiKey = YOUR_API_KEY)
recentQ = GetRecentArticles(er, maxArticleCount = 200)
starttime = time.time()
while True:
    articleList = recentQ.getUpdates()
    print("%d articles were added since the last call" % len(articleList))

    # do whatever you need to with the articles in articleList

    # wait exactly a minute until next batch of new content is ready
    time.sleep(60.0 - ((time.time() - starttime) % 60.0))

Each call to recentQ.getUpdates() will provide you with a list of articles that were added since the last call to the method. Provided information about the articles matches the Article data model.

The GetRecentArticles constructor accepts the following parameters:

  • eventRegistry: an instance of the EventRegistry class
  • mandatorySourceLocation [default: False]: if True, return only articles from sources for which we know the geographic location
  • articleLang [default: None]: None, a string or a list of strings - return all articles or only articles in the specified language(s)
  • returnInfo: what details should be included in the returned articles. See details.
  • maxArticleCount [default: None]: the maximum number of articles to return in a call
  • updatesAfterMinsAgo [default: None]: return the articles added in the last specified number of minutes (instead of since the previous call)
  • updatesAfterTm [default: None]: return the articles added after the given time (a datetime or a string in the 'YYYY-MM-DDTHH:MM:SS' format, in UTC)
  • keywords, conceptUri, categoryUri, sourceUri, sourceLocationUri, sourceGroupUri, authorUri, locationUri, lang, keywordsLoc: return only the articles that match these conditions. They have the same meaning as in QueryArticles: a single value is given as a string and several values with QueryItems.OR() or QueryItems.AND().
  • dataType [default: "news"]: what data types should be returned - "news", "pr", "blog" or a list of them
  • isDuplicateFilter [default: "keepAll"], eventFilter [default: "keepAll"]: what to do with the duplicated articles and the articles without an event (same values as in QueryArticles)
  • startSourceRankPercentile [default: 0], endSourceRankPercentile [default: 100]: return only the articles from the sources with the given ranking
  • minSentiment [default: -1], maxSentiment [default: 1]: return only the articles with the sentiment in the given range
  • any additional keyword arguments are sent along with the request as they are

The conditions and the maxArticleCount, updatesAfterMinsAgo and updatesAfterTm parameters are named parameters since version 11.0. Before, they could only be passed as raw API parameters (e.g. recentActivityArticlesMaxArticleCount = 200), which still works.

An example that returns only the new English articles about Tesla from the top-ranked sources, without the duplicates:

from eventregistry import *
import time

er = EventRegistry(apiKey = YOUR_API_KEY)
recentQ = GetRecentArticles(er,
    conceptUri = er.getConceptUri("Tesla"),
    lang = "eng",
    isDuplicateFilter = "skipDuplicates",
    endSourceRankPercentile = 30,
    maxArticleCount = 200)
starttime = time.time()
while True:
    for art in recentQ.getUpdates():
        print(art["title"])
    time.sleep(60.0 - ((time.time() - starttime) % 60.0))

NOTE: the results are computed once a minute, so call the getUpdates() method exactly once per minute. Calling it more frequently will return the same results multiple times, calling it less frequently will miss some results.

Feed of new/updated events

As for the articles, we can also ask Event Registry for a feed of new events. In this case, the list will also include the events that were just updated (for example with a new article about this event). An example code to get the list of new or updated events would be:

from eventregistry import *
import time

er = EventRegistry(apiKey = YOUR_API_KEY)
recentQ = GetRecentEvents(er)
starttime = time.time()
while True:
    ret = recentQ.getUpdates()
    if "eventInfo" in ret and isinstance(ret["eventInfo"], dict):
        # how many events updated since last call (each event can be updated multiple times)
        print("%d events updated since last call" % len(ret["activity"]))

        # get URIs of the events that are new/updated
        uris = list(ret["eventInfo"].keys())

        # use the details about events in ret["eventInfo"]

    # wait exactly a minute until next batch of new content is ready
    time.sleep(60.0 - ((time.time() - starttime) % 60.0))

Provided information about the events in ret["eventInfo"] matches the Event data model.

The GetRecentEvents constructor accepts the following parameters:

  • eventRegistry: an instance of the EventRegistry class
  • mandatoryLang [default: None]: if set (a string or a list of strings), return only events that are covered at least by the specified language(s)
  • mandatoryLocation [default: True]: if True, return only events that have a known geographic location
  • returnInfo: what details should be included in the returned events. See details.
  • maxEventCount [default: None]: the maximum number of events to return in a call
  • updatesAfterMinsAgo [default: None]: return the events added or updated in the last specified number of minutes
  • updatesAfterTm [default: None]: return the events added or updated after the given time (a datetime or a string in the 'YYYY-MM-DDTHH:MM:SS' format, in UTC)
  • keywords, conceptUri, categoryUri, sourceUri, sourceLocationUri, sourceGroupUri, authorUri, locationUri, lang, keywordsLoc: return only the events that match these conditions. They have the same meaning as in QueryEvents.
  • minArticlesInEvent [default: None], maxArticlesInEvent [default: None]: return only the events with at least / at most this many articles
  • any additional keyword arguments are sent along with the request as they are

As for the articles, the conditions and the maxEventCount, updatesAfterMinsAgo and updatesAfterTm parameters are named parameters since version 11.0. An example that follows only the events about natural disasters that are covered by at least 10 articles:

recentQ = GetRecentEvents(er,
    conceptUri = er.getConceptUri("natural disaster"),
    minArticlesInEvent = 10,
    maxEventCount = 100)
ret = recentQ.getUpdates()

Other ways of getting new content

  • To get the new articles that match a query at your own pace (not exactly once per minute), use QueryArticles with the RequestArticlesRecentActivity result type.
  • To get the new articles or events that match a topic page, use TopicPage.getArticles() / getEvents() with the onlyAfterTm parameter.

If the request fails, getUpdates() raises an exception (see Errors and troubleshooting) - catch it in a long-running loop if the loop should continue.

Clone this wiki locally