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: "http://eventregistry.org"]. The URL where the Event Registry is available. When testing some new features, you might need to specify a different URL.
• 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.
• allowUseOfArchive [default: True]. Are the queries allowed to access the news archive (content older than 30 days). If False, then the token usage for requests will be lower.
• settingsFName [default: None]. If provided it should be a full path to 'settings.json' file where apiKey an/or host can be loaded from. If None, we will look for the settings file 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 Event Registry 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 package directory. 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 to you on your profile page. When creating the EventRegistry instance without specifying the apiKey parameter, we will try to locate this file and read the apiKey from it.

Execute query method

EventRegistry.execQuery(query)

This is the method that you will use frequently since it is used for executing all types of queries (e.g QueryEvents, QueryArticles, GetCounts, ...). The method returns data as a Python object.

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() return 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 is the provided prefix. 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. 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,
    lang = "eng", conceptLang= "eng",
    sources = ["concepts"],
    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.

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

Suggest the single best item URI

Methods below provide the single best item's URI that matches the given input text. You will use this method if you will be sure that the auto suggest will return as the first item the one that you want to use in your 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 = ["concepts"])

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.getNewsSourceUri(sourceName)

Utility methods

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

EventRegistry.getRecentStats() will return statistics about the data imported in the Event Registry.

EventRegistry.getRemainingAvailableRequests() will return the number of requests that the user with current credentials can still make today.

EventRegistry.getDailyAvailableRequests() will return the total number of requests that the user with current credentials can make per today.