eventregistry is a Python package for accessing the news API provided by NewsAPI.ai. The package is named after Event Registry, the company that develops NewsAPI.ai. It can be used to search for articles or events using a large set of filters, like keywords, concepts, categories, sources, sentiment, date, etc., to follow the feed of new content and to compute summaries (top sources, concepts, sentiment, ...) of the matching content. Details about the News API are available on the landing page of the product.
The package requires Python 3.9 or newer. Install it with pip:
pip install eventregistry
To update an existing installation to the latest version:
pip install eventregistry --upgrade
To check the installation, run python and type:
import eventregistry
print(eventregistry.__version__)When updating to a new major version, see the migration guide for the changes that can require an update of your code.
To make requests you need an API key, which you get for free by registering - it is shown on your dashboard. The key can be provided in one of these ways (the first one found is used):
- as the
apiKeyargument:EventRegistry(apiKey = "YOUR_API_KEY") - in the
EVENTREGISTRY_API_KEYenvironment variable - in a
settings.jsonfile with the content{ "apiKey": "YOUR_API_KEY" }, stored in the.eventregistryfolder of your home directory (~/.eventregistry/settings.json)
With the environment variable or the settings file the key stays out of your code and you can simply create the instance with EventRegistry(). See Authorization for details.
Iterate over the articles: the newest articles from US based sources, with positive sentiment, that mention "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["dateTime"], art["title"])Search by concepts instead of keywords: business articles from the last month related to Microsoft or Google, in any language
from eventregistry import *
# allowUseOfArchive = False limits the search to the last month of data (and uses fewer tokens)
er = EventRegistry(apiKey = YOUR_API_KEY, allowUseOfArchive = False)
q = QueryArticlesIter(
conceptUri = QueryItems.OR([er.getConceptUri("Microsoft"), er.getConceptUri("Google")]),
categoryUri = er.getCategoryUri("news business"))
for art in q.execQuery(er, sortBy = "date", maxItems = 500):
print(art["title"])Search for the 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))Combine conditions with a complex query: articles about electric vehicles or batteries, published in January 2024 by German or French sources, that don't mention Tesla
from eventregistry import *
er = EventRegistry(apiKey = YOUR_API_KEY)
electricVehicleUri = er.getConceptUri("electric vehicle") # = "http://en.wikipedia.org/wiki/Electric_vehicle"
batteryUri = er.getConceptUri("electric battery") # = "http://en.wikipedia.org/wiki/Electric_battery"
teslaUri = er.getConceptUri("Tesla") # = "http://en.wikipedia.org/wiki/Tesla,_Inc."
germanyUri = er.getLocationUri("Germany") # = "http://en.wikipedia.org/wiki/Germany"
franceUri = er.getLocationUri("France") # = "http://en.wikipedia.org/wiki/France"
# the query in the JSON format of the complex query language (a python dict or a string with the JSON object)
query = {
"$query": {
"conceptUri": {
"$or": [electricVehicleUri, batteryUri]
},
"sourceLocationUri": {
"$or": [germanyUri, franceUri]
},
"dateStart": "2024-01-01",
"dateEnd": "2024-01-31",
"$not": {
"conceptUri": teslaUri
}
}
}
q = QueryArticlesIter.initWithComplexQuery(query)
for art in q.execQuery(er, sortBy = "date", maxItems = 100):
print(art["title"])Handle the errors
Failed requests raise exceptions derived from EventRegistryError. Requests that fail with a temporary error (connection problem, timeout, server error) are first repeated automatically (3 times by default, see the repeatFailedRequestCount parameter). Requests rejected because too many requests are made at the same time (status 429) are repeated until they succeed, so an iteration over the results is not interrupted.
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:
# status 401 or 403: invalid API key, no more tokens or a disabled account
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))The documentation is on the wiki pages:
- Quickstart recipes - copy-paste-ready scripts for the most common tasks, including paging, limits and token usage
- Terminology - what we mean by an event, story, concept or category
EventRegistryclass - the main class, API key, autosuggest methods- Searching for articles, events and mentions (requires special access)
ReturnInfoclass and the data models - what details can be returned about articles, events, concepts, sources, ...- Topic pages and the feed of new articles/events - monitoring of new content
- Trends and text analytics
- Usage tracking - tokens and how to check their use
- Errors and troubleshooting - the exceptions, retries, the limit of 5 simultaneous requests, logging, common mistakes
- Migration guide - updating from version 9 to 10 and from 10 to 11
Other resources:
- Examples folder - runnable examples of the most used features. Each file contains several examples as functions;
python QueryArticlesExamples.pylists them andpython QueryArticlesExamples.py <name>runs one. - API reference - all the classes and methods, generated from the docstrings
- Change log - the changes in each version
- Interactive Jupyter notebook - examples that you can view and modify in the browser
The package contains type hints (py.typed), so editors and type checkers know the arguments of the classes and methods.
Clone the repository and install the package with the test dependencies:
pip install -e ".[test]"
The tests need no API key and no network access:
python -m unittest eventregistry.tests.TestOfflineUnit eventregistry.tests.TestRequestPayloads eventregistry.tests.TestQueryParamsBase
Please report bugs and suggestions on the GitHub issues page. Include the version of the package (eventregistry.__version__), a short piece of code that reproduces the problem (without your API key) and the full error message. For questions about your account, tokens or the data, use the contact options on newsapi.ai.
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.