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()

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

• 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.
• logging [default: False]. Should the executed web requests be logged in the requests_log.txt file in the package directory?
• minDelayBetweenRequests [default: 0.5]. What should be the minimum delay in seconds between two requests sent to Event Registry. Remember that each user has a daily request limit so don't spend the requests too fast.
• 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.

Logging in

In case you are a registered user you might wish to log into Event Registry in order to be able to make more requests per day (see Daily restrictions). You can achieve this by calling the EventRegistry.login() method and passing in your email and password that you used for registration. Alternatively, you can also create a settings.json file in the eventregistry package directory. The content of the file should be a simple JSON object:

{
	"username": "YOUR_EMAIL_ADDRESS",
	"password": "YOUR_PASSWORD"
}

If this file will be found when creating the EventRegistry instance it will be used to automatically log you in. In case you have not registered yet, you can use the registration page.

Execute query method

EventRegistry.execQuery(query)

This is the method that you will use the most since it is used for executing all types of queries (e.g QueryEvents, QueryArticles, GetCounts, ...). The returned JSON object will be parsed into 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's 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 autosuggest 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 category 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 formating 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.