EventRegistry class

EventRegistry is the main class that you are going to need in order to send any kind of request to the Event Registry. You can create an instance of this class as follows:

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

The constructor accepts several relevant parameters, that you can modify:

• apiKey [default: None]. The API key for your account that should be used when making the requests. If the API key is not provided, we will try to load the key from the settings.json file. See the Authorization section to see how to obtain the API key and how to use the settings.json file.
• host [default: "https://eventregistry.org"]. The URL where the Event Registry service is available. You normally don't need to change this.
• hostAnalytics [default: "https://analytics.eventregistry.org"]. The URL of the text analytics service, used by the Analytics class.
• minDelayBetweenRequests [default: 0.5]. What should be the minimum delay in seconds between two requests sent to Event Registry. If a user will be sending requests too often, his/her account might get temporarily disabled.
• repeatFailedRequestCount [default: -1]. In case a request fails (for example, timeout), how many times should it be repeated before giving up. Use -1 to repeat indefinitely. Note: requests that fail with status codes indicating an invalid request or an exceeded quota (400, 401, 403, ...) are never repeated.
• allowUseOfArchive [default: True]. Are the queries allowed to access the news archive (content older than 31 days). Queries that use the archive consume more tokens. If you are only interested in recent content, set this to False - all queries will then be executed only on the recent data, regardless of the date conditions set in the queries. The setting can also be overridden for an individual request by passing the allowUseOfArchive argument to execQuery().
• verboseOutput [default: False]. If True, additional information about failed requests will be logged.
• settingsFName [default: None]. If provided it should be a full path to a 'settings.json' file from which the apiKey and/or host can be loaded. If None, we first look for the settings file in the .eventregistry folder of your home directory (~/.eventregistry/settings.json) and, if it is not there, in the eventregistry module folder.

Authorization

When accessing data in Event Registry you have to specify an API key so that we know how many requests you have made. To obtain the API key, you have to first register for an account (registration is free). Once you activate your account, visit your dashboard page where you can find your API key.

Since you will likely create multiple instances of the EventRegistry class in your various scripts, it makes sense that you don't specify the apiKey parameter explicitly each time in case you decide to generate a new key. To avoid having to specify the apiKey in your scripts you can also create a settings.json file in the .eventregistry folder of your home directory (~/.eventregistry/settings.json, on Windows typically C:\Users\<user>\.eventregistry\settings.json). Alternatively, the file can be placed in the eventregistry package directory or in any other location, in which case pass its full path via the settingsFName constructor parameter. The content of the file should be a simple JSON object:

{
    "apiKey": "YOUR_API_KEY"
}

YOUR_API_KEY should be a string containing the value provided on your dashboard page. When creating the EventRegistry instance without specifying the apiKey parameter, we will try to locate this file (first in ~/.eventregistry/, then in the package directory) and read the apiKey from it.

Execute query method

EventRegistry.execQuery(query, allowUseOfArchive = None)

This is the method that you will use frequently since it is used for executing all types of queries (e.g QueryArticles, QueryEvents, GetCounts, ...). The method returns the data as a Python object (dict or list). The optional allowUseOfArchive argument can be used to override, for this request only, the archive setting specified in the constructor.

Autosuggestion methods

As mentioned in the terminology page, Event Registry operates with concepts, categories and news sources which all have their unique identifiers (URIs). When using the concepts/categories/news sources in search you will refer to them by their URI. As a user, you will likely not know these URIs but will instead know the label or part of the label by which it is known. In order to find the URI that you need, Event Registry provides various autosuggest methods. The group of methods suggest*() provides a list of items that best match the input text, while the group of methods get*Uri() returns only the URI of the best candidate based on the input text.

Suggest a list of items

Methods below provide a list of suggestions for a given input text. If you have a short label, such as "Lond", use these methods to obtain suggestions which concepts/categories/news sources contain this label in their name.

Suggest concepts

EventRegistry.suggestConcepts provides a list of concepts that best match the input text prefix. The method expects a prefix parameter that contains the label of a concept, for which you would like to identify the best candidate concepts. The prefix can be a complete or a partial label. Using the parameter lang, the user can specify in which language the provided prefix is. The value should use an ISO 639-3 language code. The conceptLang parameter determines which language labels should be included in the returned concepts. The sources parameter determines what type of concepts can be returned as candidates (valid values: person, loc, org, wiki, entities (= person + loc + org), concepts (= entities + wiki)). page and count parameters can be used to determine the number of returned suggestions and the page of the suggestions (like in search results).

EventRegistry.suggestConcepts(prefix,
    sources = None,          # None is interpreted as ["concepts"]
    lang = "eng", conceptLang = "eng",
    page = 1, count = 20)

Example:

>>>er.suggestConcepts("obama", lang = "eng", conceptLang = ["deu", "eng"], sources = "person")

[
    {
        "id": "18952",
        "label": {
            "deu": "Barack Obama",
            "eng": "Barack Obama"
        },
        "score": 1076421,
        "type": "person",
        "uri": "http://en.wikipedia.org/wiki/Barack_Obama"
    },
    ...
]

Suggest categories

EventRegistry.suggestCategories method computes the list of categories that match the input prefix. The prefix parameter should specify the complete or partial label of the category. All category labels are in English so there is no need to specify the language.

EventRegistry.suggestCategories(prefix, page = 1, count = 20)

Suggest news sources

EventRegistry.suggestNewsSources method provides the list of news sources that match the prefix in the sources' title or host URL. Use the dataType parameter to only return sources of a particular type (news, pr, blog or a list of these).

EventRegistry.suggestNewsSources(prefix, dataType = None, page = 1, count = 20)

Suggest source groups

EventRegistry.suggestSourceGroups returns a list of news source groups that match the prefix. Source groups are predefined groups of news sources - see source filtering for details.

EventRegistry.suggestSourceGroups(prefix, page = 1, count = 20)

Suggest locations

EventRegistry.suggestLocations returns a list of geographic locations (cities or countries) that contain the prefix. If countryUri is provided, only locations from that country are returned. If sortByDistanceTo is provided as a (latitude, longitude) pair, the candidates are sorted by the distance to that point.

EventRegistry.suggestLocations(prefix,
    sources = None,          # None is interpreted as ["place", "country"]
    lang = "eng", count = 20,
    countryUri = None,
    sortByDistanceTo = None)

There are also two related methods: EventRegistry.suggestLocationsAtCoordinate(latitude, longitude, radiusKm, ...) which returns locations close to the given coordinate, and EventRegistry.suggestSourcesAtCoordinate(latitude, longitude, radiusKm, ...) which returns news sources located close to the given coordinate.

Suggest authors

EventRegistry.suggestAuthors returns a list of authors that match the prefix. The prefix can also contain the source url to disambiguate authors with the same name (e.g. "george brown nytimes").

EventRegistry.suggestAuthors(prefix, page = 1, count = 20)

Suggest event types and industries

When searching for mentions, you can filter by event types and industries. Use EventRegistry.suggestEventTypes(prefix) and EventRegistry.suggestIndustries(prefix) to find the corresponding URIs. The lists of SDG and SASB URIs can be obtained by calling EventRegistry.getSdgUris() and EventRegistry.getSasbUris().

Suggest the single best item URI

Methods below provide the single best item's URI that matches the given input text. You will use these methods when you are confident that the first returned suggestion is the one that you want to use in your query. All of them return None when there is no match, so make sure to check the returned value before using it in a query.

Get concept URI

EventRegistry.getConceptUri provides the concept URI that best matches the conceptLabel - the text can either be a full or partial concept label. lang specifies in which language the provided conceptLabel is. The sources again determines what types of concepts are valid candidates.

EventRegistry.getConceptUri(conceptLabel, lang = "eng", sources = None)

Example:

>>>er.getConceptUri("obama", lang = "eng", sources = "person")
"http://en.wikipedia.org/wiki/Barack_Obama"

Get category URI

EventRegistry.getCategoryUri returns the URI of the category that matches the categoryLabel.

EventRegistry.getCategoryUri(categoryLabel)

Get news source URI

EventRegistry.getNewsSourceUri returns the URI of the news source that matches the sourceName. EventRegistry.getSourceUri is a shorter alias of the same method.

EventRegistry.getNewsSourceUri(sourceName, dataType = None)

Other get*Uri methods

The same pattern is available for the other data types:

EventRegistry.getLocationUri(locationLabel, lang = "eng", sources = None, countryUri = None, sortByDistanceTo = None)
EventRegistry.getSourceGroupUri(sourceGroupName)
EventRegistry.getAuthorUri(authorName)
EventRegistry.getEventTypeUri(eventTypeLabel)

Usage information

EventRegistry.getUsageInfo() returns the number of used and total available tokens for your account. It can be called at any time, also before making any queries.

EventRegistry.getRemainingAvailableRequests() returns the number of requests that can still be made today. The information is only available after at least one request has been made.

EventRegistry.getDailyAvailableRequests() returns the total number of requests that can be made per day. The information is only available after at least one request has been made.

Utility methods

EventRegistry.format(obj) will generate a string with pretty formatting of the Python object (dict or list). Useful for printing.

EventRegistry.getUrl(query) returns the full URL (including the query parameters) that corresponds to the given query object. Useful for debugging or for sharing the request with others.

EventRegistry.printLastReqStats() prints the number of tokens used by the last request, the performed action and whether the archive was used.

EventRegistry.getLastHeaders() and EventRegistry.getLastHeader(headerName) return the HTTP headers of the last response - useful for inspecting rate-limit information.

EventRegistry.getLastException() returns the last exception that occurred while executing a request (or None).