Event Registry Python Client

9.1 · active · verified Fri Apr 17

The `eventregistry` library is a Python client for interacting with the Event Registry API (eventregistry.org). It allows users to query for news articles, events, mentions, and perform text analytics. The current version is 9.1, and releases are made periodically to add new features and improve existing functionality.

Common errors

```
eventregistry.EventRegistryException: The API key 'YOUR_API_KEY' is not valid or has expired.
```
cause The provided API key is either incorrect, expired, or has exceeded its usage limits.

fix Double-check your API key on eventregistry.org. Generate a new key if necessary, and ensure it's correctly passed to the `EventRegistry` constructor.
```
TypeError: QueryArticles.__init__() missing 1 required positional argument: 'keywords'
```
cause A required parameter for a query object (e.g., `keywords` for `QueryArticles` or `eventUri` for `QueryEvent`) was not provided.

fix Consult the documentation or examples for the specific query class you are using and ensure all mandatory parameters are supplied during initialization. For `QueryArticles`, at least `keywords`, `conceptUri`, or `sourceUri` is usually needed.
```
ImportError: cannot import name 'EventRegistry' from 'eventregistry'
```
cause Typo in the import statement or an issue with the package installation.

fix Verify the import statement is exactly `from eventregistry import EventRegistry`. If the error persists, try reinstalling the library: `pip install --upgrade eventregistry`.
```
No module named 'eventregistry'
```
cause The `eventregistry` library is not installed in the current Python environment.

fix Install the library using pip: `pip install eventregistry`. Ensure you are running this command in the same environment where your Python script will execute.

Warnings

breaking Version 9.0 and newer of the library dropped support for Python 2.x and Python <3.5. These versions now require Python 3.5+ due to the introduction of type hints.
Fix: Upgrade your Python environment to version 3.5 or higher. If you need Python 2.x or older 3.x compatibility, pin `eventregistry` to a version less than 9.0 (e.g., `eventregistry==8.10`).
gotcha All queries to the Event Registry API require a valid API key. Failing to provide one will result in `EventRegistryException` or similar authentication errors.
Fix: Obtain an API key from eventregistry.org and pass it to the `EventRegistry` constructor, e.g., `EventRegistry(apiKey='YOUR_API_KEY')`. It's recommended to use environment variables for keys.
breaking Starting from version 8.9, the library will raise exceptions (e.g., `EventRegistryException`) for specific non-200 HTTP status codes (204, 400, 401, 403). Previously, the library would repeatedly retry these requests, which could lead to indefinite loops or slow execution for invalid queries.
Fix: Implement explicit error handling for `eventregistry.EventRegistryException` or other `requests.exceptions.RequestException` in your code to gracefully manage API errors and invalid requests.
gotcha For advanced keyword search modes (e.g., logical 'OR' or 'AND' between keywords), the `keywordSearchMode` parameter was introduced in v9.1 for `QueryArticles`, `QueryEvents`, etc.
Fix: When constructing queries, use `keywordSearchMode='OR'` or `keywordSearchMode='AND'` along with your keywords. Refer to the documentation for advanced usage examples.

Install

pip install eventregistry Install stable version

Imports

EventRegistry
```
from eventregistry import EventRegistry
```
QueryArticles
```
from eventregistry import QueryArticles
```
QueryEvents
```
from eventregistry import QueryEvents
```
QueryMentions
```
from eventregistry import QueryMentions
```
Introduced in v8.10. May require specific permissions to use.
EventRegistryException
```
from eventregistry import EventRegistryException
```
Commonly used for API error handling.

Quickstart

This quickstart demonstrates how to initialize the `EventRegistry` client with an API key, construct a `QueryArticles` object to search for articles, execute the query, and print the titles of the retrieved articles. Ensure your API key is correctly set.

import os
from eventregistry import EventRegistry, QueryArticles

# Get API key from environment variable or replace with your key
ER_API_KEY = os.environ.get('EVENT_REGISTRY_API_KEY', 'YOUR_API_KEY')

if ER_API_KEY == 'YOUR_API_KEY':
    print("Warning: Please replace 'YOUR_API_KEY' with your actual Event Registry API key or set the EVENT_REGISTRY_API_KEY environment variable.")
    exit()

# Initialize EventRegistry
er = EventRegistry(apiKey=ER_API_KEY)

# Create a query for articles about 'Python programming' in English
q = QueryArticles(keywords = 'Python programming', lang = 'eng')

# Execute the query and get up to 10 articles
q.setRequestedResults(10)
res = er.execQuery(q)

# Print article titles
if res and 'articles' in res and 'results' in res['articles']:
    print(f"Found {len(res['articles']['results'])} articles:")
    for article in res['articles']['results']:
        print(f"- {article['title']}")
else:
    print("No articles found or an error occurred.")

view raw JSON →