Linked Events event database and API
Clone or download

Linked events

Build status codecov Requirements Stories in Ready Gitter

Linked Events provides categorized data on events and places. The project was originally developed for the City of Helsinki.

The Linked Events API for the Helsinki capital region contains data from the Helsinki City Tourist & Convention Bureau, the City of Helsinki Cultural Office and the Helmet metropolitan area public libraries.

Linked Events has been updated to Django 1.11. To upgrade to Linked Events release v2.0, please upgrade to release v1.3 first.

Set up project with Docker

  1. Create from the template:

    • cp
  2. Run docker-compose up

  3. Run migrations:

    • docker exec linkedevents-backend python migrate
  4. Syncronize languages for translations in DB:

    • docker exec -it linkedevents-backend python sync_translation_fields
    • Answer y (for 'yes') to all prompt questions
  5. Import some data for testing:

    # Import general Finnish ontology (used by events from following sources)
    docker exec -it linkedevents-backend python event_import yso --all
    # Import places from Helsinki metropolitan region service registry (used by events from following sources)
    docker exec -it linkedevents-backend python event_import tprek --places
    # Import events from Visit Helsinki
    docker exec -it linkedevents-backend python event_import matko --events
    # Import events from Helsinki metropolitan region libraries
    docker exec -it linkedevents-backend python event_import helmet --events
    # Import events from Espoo
    docker exec -it linkedevents-backend python event_import espoo --events
  6. Update search indexes:

    • docker exec -it linkedevents-backend python rebuild_index
  7. (Optionally) install API frontend templates:

    • docker exec -it linkedevents-backend python install_templates helevents
  8. Start your Django server:

    • docker exec -it linkedevents-backend python runserver 0:8000

Now your project is live at localhost:8000

Installation for development

These instructions assume an $INSTALL_BASE, like so:


If you've already cloned this repository, just move repository root into $INSTALL_BASE/linkedevents. Otherwise just clone the repository, like so:

git clone $INSTALL_BASE/linkedevents

Prepare Python 3.x virtualenv using your favorite tools and activate it. Plain virtualenv is like so:

virtualenv -p python3 $INSTALL_BASE/venv
source $INSTALL_BASE/venv/bin/activate

Install required Python packages into the virtualenv

cd $INSTALL_BASE/linkedevents
pip install -r requirements.txt

Create the database, like so: (we have only tested on PostgreSQL)

cd $INSTALL_BASE/linkedevents
sudo -u postgres createuser -R -S linkedevents
# Following is for US locale, we are not certain whether Linkedevents
# behaves differently depending on DB collation & ctype
#sudo -u postgres createdb -Olinkedevents linkedevents
# This is is for Finnish locale
sudo -u postgres createdb -Olinkedevents -Ttemplate0 -lfi_FI.UTF-8 linkedevents
# Create extensions in the database
sudo -u postgres psql linkedevents -c "CREATE EXTENSION postgis;"
sudo -u postgres psql linkedevents -c "CREATE EXTENSION hstore;"
# This fills the database with a basic skeleton
python migrate
# This adds language fields based on settings.LANGUAGES (which may be missing in external dependencies)
python sync_translation_fields

You probably want to import some data for testing (these are events around Helsinki), like so:

cd $INSTALL_BASE/linkedevents
# Import general Finnish ontology (used by events from following sources)
python event_import yso --all
# Import places from Helsinki metropolitan region service registry (used by events from following sources)
python event_import tprek --places
# Import events from Visit Helsinki
python event_import matko --events
# Import events from Helsinki metropolitan region libraries
python event_import helmet --events
# Import events from Espoo
python event_import espoo --events

Furthermore, you may install city-specific HTML page templates for the browsable API by

cd $INSTALL_BASE/linkedevents
python install_templates helevents

This will install the helevents/templates/rest_framework/api.html template, which contains Helsinki event data summary and license. Customize the template for your favorite city by creating your_favorite_city/templates/rest_framework/api.html. For further erudition, take a look at the DRF documentation on customizing the browsable API

After this, everything but search endpoint (/search) is working. See search

Production notes

Development installation above will give you quite a serviceable production installation for lightish usage. You can serve out the application using your favorite WSGI-capable application server. The WSGI-entrypoint for Linked Events is linkedevents.wsgi or in file linkedevents/ Former is used by gunicorn, latter by uwsgi. The callable is application.

You will also need to serve out static and media folders at /static and /media in your URL space.

Running tests

Tests must be run using an user who can create (and drop) databases and write the directories your linkedevents installation resides in. Also the template database must include Postgis and HSTORE-extensions. If you are developing, you probably want to give those permissions to the database user configured in your development instance. Like so:

# Change this if you have different DB user
# Most likely you have a postgres system user that can log into postgres as DB postgres user
sudo -u postgres psql << EOF
\c template1

Afterwards you can run the tests:

cd $INSTALL_BASE/linkedevents
py.test events

Note that search tests will fail unless you configure search


Linked Events uses two files for requirements. The workflow is as follows.

requirements.txt is not edited manually, but is generated with pip-compile.

requirements.txt always contains fully tested, pinned versions of the requirements. contains the primary, unpinned requirements of the project without their dependencies.

In production, deployments should always use requirements.txt and the versions pinned therein. In development, new virtualenvs and development environments should also be initialised using requirements.txt. pip-sync will synchronize the active virtualenv to match exactly the packages in requirements.txt.

In development and testing, to update to the latest versions of requirements, use the command pip-compile. You can use to monitor the pinned versions for updates.

To remove a dependency, remove it from, run pip-compile and then pip-sync. If everything works as expected, commit the changes.


Linkedevents uses Elasticsearch for generating results on the /search-endpoint. If you wish to use that functionality, proceed like so:

  1. Install elasticsearch

    We've only tested using the rather ancient 1.7 version. Version 5.x will certainly not work as the django-haystack-library does not support it. If you are using Ubuntu 16.04, 1.7 will be available in the official repository.

  2. (For finnish support) Install elasticsearch-analyzer-voikko, libvoikko and needed dictionaries

    /usr/share/elasticsearch/bin/plugin -i fi.evident.elasticsearch/elasticsearch-analysis-voikko/0.4.0 This specific command is for Debian derivatives. The path to plugin command might be different on yours. Note that version 0.4.0 is the one compatible with Elasticsearch 1.7

    Installing libvoikko: apt-get install libvoikko1

    Installing the dictionaries (v5 dictionaries are needed for libvoikko version included in Ubuntu 16.04):

   wget -P $INSTALL_BASE    unzip $INSTALL_BASE/ -d /etc/voikko ```

  1. Configure the thing

    Add the long block below these instructions to $INSTALL_BASE/linkedevents/ If you are familiar with Django haystack, feel free to customize it.

  2. Rebuild the search indexes

  python rebuild_index

  You should now have a working /search endpoint, give or take a few.

    'autosuggest': {
        'search_analyzer': 'standard',
        'index_analyzer': 'edgengram_analyzer',
        'analyzer': None
    'text': {
        'analyzer': 'default'

    'default': {
        'ENGINE': 'multilingual_haystack.backends.MultilingualSearchEngine',
    'default-fi': {
        'ENGINE': 'multilingual_haystack.backends.LanguageSearchEngine',
        'BASE_ENGINE': 'events.custom_elasticsearch_search_backend.CustomEsSearchEngine',
        'URL': 'http://localhost:9200/',
        'INDEX_NAME': 'linkedevents-fi',
        'SETTINGS': {
            "analysis": {
                "analyzer": {
                    "default": {
                        "tokenizer": "finnish",
                        "filter": ["lowercase", "voikko_filter"]
                "filter": {
                    "voikko_filter": {
                        "type": "voikko",
    'default-sv': {
        'ENGINE': 'multilingual_haystack.backends.LanguageSearchEngine',
        'BASE_ENGINE': 'events.custom_elasticsearch_search_backend.CustomEsSearchEngine',
        'URL': 'http://localhost:9200/',
        'INDEX_NAME': 'linkedevents-sv',
    'default-en': {
        'ENGINE': 'multilingual_haystack.backends.LanguageSearchEngine',
        'BASE_ENGINE': 'events.custom_elasticsearch_search_backend.CustomEsSearchEngine',
        'URL': 'http://localhost:9200/',
        'INDEX_NAME': 'linkedevents-en',

Event extensions

It is possible to extend event data and API without touching events application by implementing separate extension applications. These extensions will be wired under field extension_<extension idenfier> in event API. If not auto enabled (see 6. below), extensions can be enabled per request using query param extensions with comma separated identifiers as values, or all for enabling all the extensions.

To implement an extension:

  1. Create a new Django application, preferably named extension_<unique identifier for the extension>.

  2. If you need to add new data for events, implement that using model(s) in the extension application.

  3. Inherit events.extensions.EventExtension and implement needed attributes and methods. See for details.

  4. Add event_extension: <your EventExtension subclass> attribute to the extension applications's AppConfig.

  5. Make the extension available by adding the extension application to INSTALLED_APPS.

  6. If you want to force the extension to be enabled on every request, add the extension's identifier to AUTO_ENABLED_EXTENSIONS in Django settings.

For an example extension implementation, see course extension.