Please keep this file up to date and document the new importers or update current ones if necessary.
- YSO - General Finnish ontology (Required)
- tprek - Location registry (Required)
- osoite - Address registry
- helmet - Helsinki Metropolitan Area Libraries
- espoo - Espoo city
- add_helsinki_audience
- add_helsinki_topics
- import_organizations
- install_templates
- geo_import
- kulke
- lippupiste
First, some terminology is in order. Starting with ontology:
In computer science and information science, an ontology encompasses a representation, formal naming and definition of the categories, properties and relations between the concepts, data and entities that substantiate one, many or all domains of discourse.
YSO, short for Yleinen suomalainen ontologia, is basically a +30,000 collection of concepts in Finnish culture, translated in 3 languages.
General Finnish Ontology YSO is a trilingual ontology consisting mainly of general concepts. YSO has been founded on the basis of concepts in Finnish cultural sphere.
From https://finto.fi/yso/en/. You can browse the concepts there if you wish
Basic example would be, let's say a guitar player coming to Helsinki to perform in a concert and use sauna afterwards.
We might categorize it with "concert", "popular music", and "sauna" concepts.
These concepts come from YSO.
Linked Events application has events. Events must be described by concepts. Therefore, all events depend on YSO.
add_helsinki_audience also depends on this importer.
python manage.py event_import yso --keywords --allImports all keywords in YSO into the database, without maintaining the existing hierarchy between the concepts.
This is scheduled to run daily on the instance as data doesn't change that often.
tprek, short for Toimipisterekisteri, is a location registry service giving access to locations in Helsinki through a REST API.
Basic example would be the location of a concert in a certain theater hall.
Linked Events application has events. Events must have locations.
By default, all event locations are from tprek location registry.
Therefore, all events depend on tprek locations to be present.
python manage.py event_import tprek --placesImports all locations, which usually have addresses, coordinates and other metadata, from tprek location registry into the database.
This is scheduled to run hourly on the instance as data changes often.
Let's get terminology in order.
address is a field in a location object. location can have other metadata.
Pääkaupunkiseudun osoiteluettelo is an address registry which only contains addresses. osoite is a Metropolitan location list importer, which creates a location object with only one field of address from the addresses imported from Pääkaupunkiseudun osoiteluettelo.
Basic example would be the location of a one-off random event in a private location. Locations not meant to be used regularly are not usually added to tprek.
If you want to give the users of your application the ability to add events with locations which are not present in tprek, you need osoite.
In other words, osoite is fall-back for tprek.
python manage.py event_import osoite --placesCreates locations from osoite address registry into the database.
This is scheduled to run daily on the instance as origin database updates daily too.
helmet is an importer for Helsinki Metropolitan Area Libraries Events from https://helmet.fi.
Basic example would be an event organized by Helsinki city center library for children, which you can import with this importer.
If you want to populate the database with events organized by Helmet, you need helmet importer.
python manage.py event_import helmet --eventsImports all events organized by Helmet into the database.
This is scheduled to run hourly on the instance as data changes often.
espoo is an importer for Espoo city Events from https://espoo.fi.
Basic example would be an event organized by Espoo city for its residents, which you can import with this importer.
If you want to populate the database with events organized by Espoo city, you need espoo importer.
python manage.py event_import espoo --eventsImports all events organized by Espoo city into the database.
This is scheduled to run hourly on the instance as data changes often.
add_helsinki_audience is a django management command for creating a set of audience keywords in the database which is then exposed through /keyword_set endpoint.
Basic example would be an event whose target audience are elderly immigrants.
"Elderly" and "Immigrant" are keywords that the event creator would pick from the choices in the audience keywords set created by this command.
Any YSO keyword can be used as audience in the backend. However, if you're running the Linked Events UI, you need this command as the UI only allows the keywords set with this command to be used.
You are free to make your own UI that uses any YSO concept for the target audience and you can skip this command.
Keywords in this set are all from YSO except the ones defined in NEW_SOTE_KEYWORDS_DATA in add_helsinki_audience.py.
Concepts defined in NEW_SOTE_KEYWORDS_DATA were not found in YSO, and therefore were hard-coded manually.
python manage.py add_helsinki_audienceCreates a Helsinki audience keywords set into the database.
add_helsinki_topics is a django management command for creating a set of topics keywords in the database which is then exposed through /keyword_set endpoint.
Basic example would be an event in which they would talk about welfare.
"Discussion" and "Welfare" are keywords that the event creator would pick from the choices in the topics keywords set created by this command.
All the topics used by this command are existing YSO concepts, hand-picked in add_helsinki_topics.py.
If you're running the Linked Events UI, you need this command as the UI needs to show a list of event topics keywords for the event creator to choose for the event they would like to create.
python manage.py add_helsinki_topicsCreates a Helsinki topic keywords set into the database.
import_organizations is an importer for importing all City of Helsinki organization divisions while maintaining their hierarchy into the database.
Basic example would be, say City of Helsinki has A, B, and C divisions, and A and B have two sub-divisions themselves.
This importer would import all 5 divisions while maintaining the hierarchy within the divisions.
If you're having an application whose target users are City of Helsinki organization employees, you need this importer.
Then, you can assign required permissions to users in django-admin based on which division they belong to.
python manage.py import_organizations https://api.hel.fi/paatos/v1/organization/ -s helsinki:ahjoImports all City of Helsinki organization divisions into the database while maintaining their hierarchy.
install_templates is a django management command for giving the browsable API which comes from django-rest-framework a Helsinki brand look and feel and also instructions for the API user.
Basic example would be the live version of Linked Events API for Helsinki city
which is blue and also includes instructions on how to query the API when you'd like to apply certain filters to the /event endpoint.
If you're having an application for Helsinki city and you'd like the browsable API to have Helsinki brand look and feel and also instructions for API user, you need this django management command.
python manage.py install_templates heleventsInstalls Helsinki city templates for the browsable API.
geo_import is an importer which creates divisions data structure for each place object in database.
For example, a simplified place object from Sello library can be like so:
{
...
"id": "tprek:15417",
"position": {
"type": "Point",
"coordinates": [
24.80992,
60.21748
]
},
"name": {
"fi": "Sellon kirjasto",
"sv": "Sellobiblioteket",
"en": "Sellon kirjasto"
},
...
},And by running this importer, you'd add divisions to the object above:
{
...
"id": "tprek:15417",
"divisions": [
{
"type": "muni",
"ocd_id": "ocd-division/country:fi/kunta:espoo",
"municipality": null,
"name": {
"fi": "Espoo",
"sv": "Esbo"
}
}
],
"position": {
"type": "Point",
"coordinates": [
24.80992,
60.21748
]
},
"name": {
"fi": "Sellon kirjasto",
"sv": "Sellobiblioteket",
"en": "Sellon kirjasto"
},
...
},This allows the API user to query the /place endpoint by adding division of Espoo as an example:
/place/?division=Espoo
Or directly querying the /event endpoint by filtering division of Espoo as an example:
/event/?division=Espoo
If you'd like to add support for division based filtering of events or places in your application, then you need this importer.
python manage.py geo_import finland --municipalitiesImports all municipalities in Finland from https://kartat.kapsi.fi/.
python manage.py geo_import helsinki --divisionsImports all divisions in Helsinki from the Helsinki district division datasets. This allows more specific filtering for Helsinki city based on
district names, sub_district names, and neighborhood names.
kulke, short for Kulttuurikeskukset, is an importer which imports events from City of Helsinki cultural centers (http://annantalo.fi, http://vuotalo.fi, http://malmitalo.fi etc.).
NOTE: To get access to data from City of Helsinki cultural centers, you need to have access to City of Helsinki internal network. Specifics of how to get this access for City of Helsinki developers will be documented here later.
If you'd like to have events organized by City of Helsinki cultural centers in your Linked Events application instance, you need this importer.
python manage.py event_import kulke --eventsImports all events organized by City of Helsinki cultural centers into the database.
This is scheduled to run hourly on the instance as data changes often.
lippupiste is an importer which imports events from Lippupiste Oy (https://lippu.fi); currently used only for importing Helsinki City Theater events.
NOTE: To get access to data from Lippupiste, you need to have an agreement with Lippupiste Oy. The data is not publicly available at the moment.
If you'd like to have events marketed by Lippupiste anywhere in Finland in your Linked Events application instance, you need this importer.
python manage.py event_import lippupiste --eventsImports events marketed by Lippupiste Oy into the database. Currently, the importer only imports plays by the Helsinki City Theater; the imported locations and events can be filtered in the importer code.
This is scheduled to run hourly on the instance as data changes often.