Details about OLE

Open Linked Event Data Interface

The core function of Hinto is that the information about events is newly spread dynamically, across the boundaries of individual websites and platforms, automatically. Thanks to the automatic exchange of data with other websites & platforms, the visibility for cultural professionals is increased with little effort. Knowledge about our rich cultural landscape thus spreads more easily and becomes more tangible.

Without OLE interface (Previously)

Events must be published manually

The organizer has to enter his event manually on different platforms.

This means: The organizer has to invest a lot of time to publish his events. In case of changes, the information has to be adjusted by hand everywhere.

If a interface is offered by the platform, it has to be implemented for each individual platform.

This means: Dependence on the platform and costs for implementation and maintenance.

With OLE interface (New)

Events spread automatically

The standardized OLE interface is provided by you . The platforms come to you for the data pick up.

This means: No effort in publishing events. One time Cost of implementing the OLE interface to provide any number of platforms with data.

For Wordpress (version 5.2-5.7) there is a free OLE plugin which allows event data to be injected into the OLE network with just a few clicks. The plugin supports various event manager plugins (e.g. Event Organiser, WP Event Manager, Event Calendar), but can also be extended by a custom driver.

A small PHP library we have on bitbucket.org (GIT, MIT license) so that plugins for Typo3, Drupal, Joomla! and other solutions can emerge more easily.
We've also prepared this library as a composer package so you can integrate even faster (composer require fugugmbh/oledata dev-master).

Contact us to integrate the interface into your website or if you have any other questions.

If you have developed an OLE plugin, we will be happy to communicate it here on hinto.ch.

License

OLE was developed by fugu GmbH and is licensed under the Creative Commons Attribution-Share Alike 4.0 International License.

Platforms/aggregators that use the OLE interface for aggregating data are required to communicate the OLE interfaces (URLs) used publicly and in a machine-readable form in order to ensure the redistribution of the event data.

The use of the OLE interface should be communicated in an appropriate way to ensure the dissemination of the OLE concept. For this purpose, we have created an example text in the next section.

Thus, the OLE concept can be freely used for commercial and non-commercial applications in compliance with the license.

Licensor

fugu GmbH
Schwarztorstrasse 9
CH-3007 Bern

www.fugu.ch

Example for a mention in the imprint or footer

The following text can be used directly in the masthead of your website:

This website is part of the Open Linked Event Data network (OLE), an initiative of the Hinto.ch association. All events are also automatically published on www.hinto.ch.

Already equipped with OLE

Hinto sources

How it works

After the XML based interface has been implemented into your website by a programmer, the data can be automatically and very efficiently read in by remote systems with the corresponding URL.

The remote systems call the URL several times a day and can thus read in the current event data.

Since the XML based document is well-structured and documented, there are no incorrect interpretations of your event data. The OLE interface is also much more efficient than harvesting on the website, thus your website/hosting will be less busy and the experience for all other website visitors will be maintained.

By implementing the OLE interface, you explicitly consent to your event data being read by third-party systems and consequently used in remote/foreign systems.

Minimal implementation of the interface

The following is an example of the structure the XML must have.

We recommend publishing a maximum of 20 events per request. This recommendation protects the infrastructure of you and the recipient. If you want to publish more than 20 events, you can implement a paging using <next_url>.

All data must be encoded as UTF-8.

Sample XML

<!--
We recommend to wrap all values by CDATA <![CDATA[...]]>

lang attribute ist optional (ISO-639-1)

source_id on event,show element must be unique and required for update purpose

-->
<!--
This XML interface is licensed under a Creative Commons 4.0 BY-SA license, https://www.hinto.ch/olelicense.html
-->
<ole>
    <meta>
        <max_pages>8</max_pages><!-- Used to generate a progress info on client side -->
        <next_url><![CDATA[https://www.mydomain.ch/myolepath/for/next/page]]></next_url>

        <!-- extended functions, optional -->
        <changedsince_supported>true</changedsince_supported><!-- boolean -->
        <source_version><![CDATA[my version value]]></source_version>
    </meta>
    <events>
        <event source_id="event-XXX">

            <name lang="de"><![CDATA[My event name]]></name>
            <name lang="fr"><![CDATA[]]></name>
            <name lang="en"><![CDATA[]]></name>
            <name lang="xx"><![CDATA[]]></name>

            <!-- optional -->
            <lead lang="de"><![CDATA[My lead]]></lead>
            <lead lang="fr"><![CDATA[]]></lead>
            <lead lang="en"><![CDATA[]]></lead>

            <!-- optional -->
            <description lang="fr"><![CDATA[My description]]></description>
            <description lang="fr"><![CDATA[]]></description>
            <description lang="en"><![CDATA[]]></description>

            <costs></costs><!-- 0|1 : Int value for no or yes (optional) -->

            <location>
                <name><![CDATA[My name]]></name>
                <street><![CDATA[My street]]></street>
                <code><![CDATA[My postal code]]></code>
                <locality><![CDATA[My city/locality]]></locality>
            </location>

            <!-- optional -->
            <categories>
                <category><![CDATA[My category A (Jazz)]]></category>
                <category><![CDATA[My category B (Fest)]]></category>
                <category><![CDATA[...]]></category>
            </categories>

            <!-- optional -->
            <targetgroups>
                <targetgroup><![CDATA[My target group A (Kinder)]]></targetgroup>
                <targetgroup><![CDATA[My group B (Senioren)]]></targetgroup>
                <targetgroup><![CDATA[...]]></targetgroup>
            </targetgroups>

            <shows>

                <show source_id="show-YYY">
                    <!-- ISO-8601 -->
                    <date_start>2019-09-30T18:00:00+02:00</date_start>
                    <!-- ISO-8601 (optional) -->
                    <date_end>2019-09-30T20:00:00+02:00</date_end>
                    <!-- Additional info (e.g. door opening) -->
                    <info lang="xx"><![CDATA[...]]></info>
                    <!-- Overwrites event.url (optional) -->
                    <url><![CDATA[...]]></url>
                    <!-- Overwrites event.ticket_url (optional) -->
                    <ticket_url><![CDATA[...]]></ticket_url>
                </show>

                <show source_id="...">
                    ...
                </show>

            </shows>

            <!-- optional -->
            <files>
                <image>
                    <!-- Absolute url to the file -->
                    <src><![CDATA[...]]></src>
                    <!-- Copyright of the source (optional) -->
                    <copyright><![CDATA[...]]></copyright>
                </image>
               ...
            </files>

            <!-- Absolute url to the original event page -->
            <url><![CDATA[...]]></url>
            <!-- Absolute url to the event ticket/reservation/booking url (optional)-->
            <ticket_url><![CDATA[...]]></ticket_url>

            <links>
               <url><![CDATA[...]]></url>
               ...
            </links>
        </event>
        <event>
            ...
        </event>
    </events>
</ole>

Optimizations of the interface

To make the data exchange even more efficient, we have implemented various options.

URL parameter "changedsince" (ISO-8601): This parameter can be supplied so that only data since the specified date is sent. The interface must respond with <changedsince_supported>true</changedsince_supported> for the differential import to work.
If "changedsince" is supported, the URL parameter "checksourceids" (comma separated list of "source_id "s) is called at the end of the import to find out about possible deletions.
The interface must respond to the request "?checksourceids=show-YYY,a,b,c" as follows:

<ole>
    <checksourceids>
        <delete>a,b,c</delete>
    </checksourceids>
</ole>

Optionally, the interface can send a <source_version> this is then sent by the client with every request. If the version is different, the interface should not react to a "changed_since" and thus provide all data again.

Platforms/Aggregators

Platforms/aggregators should not pass on the imported OLE data as their own data, but always refer to the origin of the data (URL). For this purpose, the OLE interface provides the following XML format.

Also, platforms with their own input masks should pass on/publish the event data using the OLE interface.

Hinto publishes its sources and event data at https://www.hinto.ch/oleexport.

OLE Sources

<!--
This XML interface is licensed under a Creative Commons 4.0 BY-SA license, https://www.hinto.ch/olelicense.html
-->
<ole>
    <sources>
        <source><![CDATA[my source URL]]></source>
        <source><![CDATA[...]]></source>
    </sources>
</ole>

Topnavigation

Main navigation