Home

Event Registry is a Python package that can be used to easily access the news data available in Event Registry through the API. The package can be used to query for articles, events or mentions by filtering using a large set of filters, like keywords, concepts, categories, sources, sentiment, date, etc. Details about the News API are available on the landing page of the product.

Installation

The package requires Python 3.9 or newer. It can be installed using Python's pip installer. In the command line, simply type:

pip install eventregistry

and the package should be installed. Alternatively, you can also clone the package from the GitHub repository. After cloning it, open the command line and run:

pip install .

Validating installation

To ensure the package has been properly installed run python and type:

import eventregistry

If you don't get any error messages, then your installation has been successful. eventregistry.__version__ contains the installed version.

Updating the package

As features are added to the package you will need at some point to update it. In case you have downloaded the package from GitHub simply do a git pull. If you have installed it using the pip command, then simply run

pip install eventregistry --upgrade

When updating to a new major version (10.0, 11.0), check the migration guide - it lists the changes that can require an update of your code, with before/after examples.

Authentication and API key

When making queries to Event Registry you will have to use an API key that you can obtain for free. The key can be passed as the apiKey argument, set in the EVENTREGISTRY_API_KEY environment variable or stored in a settings.json file. The details on how to obtain and use the key are described in the Authorization section.

Quick start

If you want to get something working quickly, go to the Quickstart recipes - copy-paste-ready scripts for the most common tasks (articles about a company in the last week, paging and token usage, restricting sources and languages, events and their articles, polling for new articles, aggregates, error handling).

A few simple examples to get you interested

Print a list of recent articles or blog posts from US based sources with positive sentiment mentioning phrases "George Clooney" or "Sandra Bullock"

from eventregistry import *
er = EventRegistry(apiKey = YOUR_API_KEY)

# get the USA URI
usUri = er.getLocationUri("USA")    # = http://en.wikipedia.org/wiki/United_States

q = QueryArticlesIter(
    keywords = QueryItems.OR(["George Clooney", "Sandra Bullock"]),
    minSentiment = 0.4,
    sourceLocationUri = usUri,
    dataType = ["news", "blog"])

# obtain at most 500 newest articles or blog posts, remove maxItems to get all
for art in q.execQuery(er, sortBy = "date", maxItems = 500):
    print(art)

Print a list of most relevant business articles from the last month related to Microsoft or Google. The articles should be in any language (including Chinese, Arabic, ...)

from eventregistry import *
# allowUseOfArchive=False will allow us to search only over the last month of data
er = EventRegistry(apiKey = YOUR_API_KEY, allowUseOfArchive=False)

# get the URIs for the companies and the category
microsoftUri = er.getConceptUri("Microsoft")    # = http://en.wikipedia.org/wiki/Microsoft
googleUri = er.getConceptUri("Google")          # = http://en.wikipedia.org/wiki/Google
businessUri = er.getCategoryUri("news business")    # = news/Business

q = QueryArticlesIter(
    conceptUri = QueryItems.OR([microsoftUri, googleUri]),
    categoryUri = businessUri)

# obtain at most 500 newest articles, remove maxItems to get all
for art in q.execQuery(er, sortBy = "date", maxItems = 500):
    print(art)

Search for latest events related to Star Wars

from eventregistry import *
er = EventRegistry(apiKey = YOUR_API_KEY)

q = QueryEvents(keywords = "Star Wars")
q.setRequestedResult(RequestEventsInfo(sortBy = "date", count = 50))   # request event details for latest 50 events

# get the full list of 50 events at once
print(er.execQuery(q))

Search for articles that (a) mention immigration, (b) are related to business, and (c) were published by news sources located in New York City

from eventregistry import *
er = EventRegistry(apiKey = YOUR_API_KEY)

q = QueryArticlesIter(
    # here we don't use keywords so we will also get articles that mention immigration using various synonyms
    conceptUri = er.getConceptUri("immigration"),
    categoryUri = er.getCategoryUri("business"),
    sourceLocationUri = er.getLocationUri("New York City"))

# obtain the 500 articles from the most important news sources
for art in q.execQuery(er, sortBy = "sourceImportance", maxItems = 500):
    print(art)

Use a complex query to combine multiple conditions: find articles that are (a) about electric vehicles or batteries, (b) published in January 2024 by German or French sources, and (c) don't mention Tesla

from eventregistry import *
er = EventRegistry(apiKey = YOUR_API_KEY)

cq = ComplexArticleQuery(
    query = CombinedQuery.AND([
        # articles should mention EVs or batteries (as concepts, so in any language)
        CombinedQuery.OR([
            BaseQuery(conceptUri = er.getConceptUri("electric vehicle")),
            BaseQuery(conceptUri = er.getConceptUri("electric battery"))
        ]),
        # published in January 2024 by sources in Germany or France
        BaseQuery(
            dateStart = "2024-01-01", dateEnd = "2024-01-31",
            sourceLocationUri = QueryItems.OR([
                er.getLocationUri("Germany"),
                er.getLocationUri("France")
            ]))
        ],
        # exclude articles that mention Tesla
        exclude = BaseQuery(conceptUri = er.getConceptUri("Tesla"))
    ))

q = QueryArticlesIter.initWithComplexQuery(cq)
for art in q.execQuery(er, sortBy = "date", maxItems = 100):
    print(art)

Handle the errors: an invalid API key or used up tokens, a failed query

from eventregistry import *
er = EventRegistry(apiKey = YOUR_API_KEY)

q = QueryArticlesIter(keywords = "Tesla", lang = "eng")
try:
    for art in q.execQuery(er, sortBy = "date", maxItems = 100):
        print(art["title"])
except AccessError as ex:
    print("Check your API key and tokens:", ex.responseText)
except QueryError as ex:
    print("The server could not execute the query:", ex)
except EventRegistryError as ex:
    print("The request failed with status %s: %s" % (ex.statusCode, ex))

What are the currently trending topics

from eventregistry import *
er = EventRegistry(apiKey = YOUR_API_KEY)

# top 10 trending concepts in the news
q = GetTrendingConcepts(source = "news", count = 10)
print(er.execQuery(q))

Learning from examples

We believe that it's easiest to learn how to use our service by looking at examples. For this reason, we have prepared examples of various most used features. View the examples grouped by main search actions:

View examples of searching for articles

View examples of searching for events

View examples of obtaining information about an individual event

Examples of how to obtain the full feed of articles

Examples of how to obtain the full feed of events

All the example files are in the examples folder. Each file contains several examples as functions: running a file without arguments lists them and makes no requests, and python QueryArticlesExamples.py <name> runs one of them.

Play with interactive Jupyter notebook

To interactively learn about how to use the SDK, see examples of use, see how to get extra meta-data properties, and more, please open this Binder. You'll be able to view and modify the examples.

Where to next?

Depending on your interest and existing knowledge of the eventregistry package you can check different things:

Quickstart recipes. Task-oriented, copy-paste-ready examples: the fastest way to a working script.

Terminology. There are numerous terms in the Event Registry that you will constantly see. If you don't know what we mean by an event, story, concept or category, you should definitely check this page first.

Learn about EventRegistry class. You will need to use the EventRegistry class whenever you will want to interact with Event Registry so you should learn about it.

Details about articles/events/concepts/categories/... that we can provide. When you will be requesting information about events, articles, concepts, and other things, what details can you ask for each of these?

Querying events. Check this page if you are interested in searching for events that match various search criteria, such as relevant concepts, keywords, date, location or others.

Querying articles. Read if you want to search for articles based on the publisher's URL, article date, mentioned concepts or others.

Querying mentions. Are you interested in individual sentences that express a particular type of a relation, such as an acquisition, a product launch or a data breach? This page describes how to search for such mentions and filter them by event type, industry, ESG category and more.

Topic pages and feed of new articles/events. Do you want to monitor a topic and regularly get the new content about it?

Trends. Are you interested in finding which concepts are currently trending the most in the news? Maybe which movie actor is most popular in social media? How about the trending of various news categories?

Errors and troubleshooting. Which exceptions can be raised and what they mean (401, 403, 429), how failed requests are repeated, the limit of 5 simultaneous requests, how to check your token usage, how to turn on logging, and the common mistakes.

Migration guide. What to change in your code when updating from version 9 to 10 and from version 10 to 11.

API reference. The reference of all the classes and methods, generated from the docstrings in the code. The list of changes in each version is in the change log.

Data access and usage restrictions

Event Registry is a commercial service but it allows also unsubscribed users to perform a certain number of operations. Non-paying users are not allowed to use the obtained data for any commercial purposes (see the details on our Terms of Service page) and have access to only last 30 days of content. In order to avoid these restrictions please contact us about the available plans.