Technische Informationen

Stand der Dokumentation: 05.02.2025

Technische Dokumentation des Standard-Importers

Über unsere standardisierte Schnittstelle können wir einfach und zuverlässig täglich aktuelle Veranstaltungsinformationen importieren.

1. Basisinformationen

1.1 Daten bereitstellen

Es gibt zwei Möglichkeiten, die Daten zu übertragen:

  • Stellen Sie uns eine URL, ggfs. mit Authentifizierung (Benutzername, Passwort) zur Verfügung, über die wir die Daten abrufen können.
  • Legen Sie die Daten per FTP-PUSH auf dem VADB-Server ab

1.2 Daten ändern, löschen, neu anlegen

Damit die Informationen über alle Änderungen korrekt und performant in der VADB ankommen, gibt es folgende Importstrategie:

  • Liefern Sie immer alle aktuell gültigen Datensätze aus Ihrem System, versehen mit dem Zeitpunkt der letzten Änderung.
  • Der Importer überträgt nur die Daten, die sich seit dem letzten erfolgreichen Import geändert haben, in die VADB.
  • Außerdem vergleicht der Importer alle Datensätze in der VADB mit den gelieferten Datensätzen und deaktiviert in der VADB diejenigen Datensätze, die in der Lieferung nicht mehr dabei sind. Damit ist sichergestellt, dass Daten, die aus dem Quellsystem entfernt wurden, auch in der VADB deaktiviert werden.

Fällt es Ihnen schwer, diese Importstrategie zu unterstützen, so wenden Sie sich an Ihre Ansprechpartner bei der Hamburg Tourismus GmbH, um Alternativen zu vereinbaren.

1.3 Formate

Die Daten können in standardisiertem XML in die VADB importiert werden. Bei Downloads befindet sich ein Beispiel.

1.4 Kodierung

Die Dateien müssen im UTF-8-Format geliefert werden.

1.5 Datentypen

In der VADB wird im Wesentlichen mit zwei Objekttypen gearbeitet: Veranstaltungen und Spielstätten

Jede Veranstaltung muss grundsätzlich eine Spielstätte haben. Kann ein Datenlieferant für eine Veranstaltung keine Spielstätten-Informationen bereitstellen, wird beim Import automatisch eine Standard-Spielstätte zugewiesen.

Jeder Datensatz ohne Spielstätte wird von Seiten Hamburg Tourismus vor einer möglichen Freigabe redaktionell geprüft. Die Chancen für eine Veröffentlichung sind gering.

zurück zur Inhaltsübersicht

2. Anforderungen

2.1 Datenmodell

Das Datenmodell in der imx.Platform enthält die Objekttypen:

  • Veranstaltung (Event)
  • Spielstätte (AddressPoi)

2.1.1 Rahmenbedingungen

  • Jedes importierte Objekt muss eine systemweit eindeutige Fremd-ID besitzen.
  • Jede Veranstaltung muss genau eine Spielstätte haben.
  • Jede Veranstaltung muss mindestens einen Termin haben.
  • Die Daten können einsprachig (deutsch) oder zweisprachig (deutsch, englisch) übergeben werden.

zurück zur Inhaltsübersicht

2.2 Datenstruktur
2.2.1 Veranstaltung (Tabelle nach rechts scrollbar!)
Attribut Name im xml Pflicht Beschreibung / Hinweis
FremdID id Ja ID des zu importierenden Datensatzes im
Quell-System.

Die FremdID muss eindeutig im gesamten
Datenbestand im Quell-System sein.
Spielstätte location.AddressPoi.id Ja  
PLZ
der
Spielstätte
location.AddressPoi.contact1.address.zipcode Ja Die PLZ muß innerhalb der Metropolregion
Hamburg liegen. Alle anderen PLZs werden ignoriert.
Veranstalter contibutor.AddressPoi.id Nein Wird automatisch mit Standard-ID3972 befüllt,
da es keine VADB-Veranstalterinfos gibt.
Titel title Ja  
Beschreibung shortDescription Ja HTML-Formatierung möglich
Autor author Nein Autor des Beschreibungstextes
Lizenz mediaLicense.MediaLicense Nein Lizenz-Typ des Beschreibungstextes
Siehe Erläuterungen zu den Lizenzen.
Link
zum
Event
link Nein Weiterführender Link, der zur Eventbeschreibungsseite
des Veranstalters oder Ticketshops führen kann.
Es sind nur gültige URLs zugelassen.
Buchungslink bookingLink Nein Es sind nur gültige URLs zugelassen.
Kategorie categories.Category Ja Siehe Erläuterungen zu den Kategorien.
Merkmale criteria.Criterion Nein Siehe Erläuterungen zu den Merkmalen.
Veranstaltungs-
reihe
series.EventSeries.id Nein Bitte erfragen Sie die für Sie relevanten IDs
bei der Redaktion.
Preise pricing.fromPrice
pricing.toPrice
pricing.freeOfCharge
pricing.priceDescription
Nein Siehe Erläuterungen zu Preisen.
Veranstaltungs-
termine
eventDates.SpecificEventDate.date
eventDates.SpecificEventDate.startTime
eventDates.SpecificEventDate.duration
eventDates.SpecificEventDate.bookingLink
eventDates.SpecificEventDate.cancelled
eventDates.SpecificEventDate.soldout
Ja Es muss mindestens einen Termin geben.
Siehe Erläuterungen zu Veranstaltungsterminen.
Termin-Meta-Tags Event.eventDates.EventDate.tags.EventDateTag Nein Siehe Erläuterungen zu den Termin-Meta-Tags.
Bilder media.EventImage
media.EventImage.imageType
media.EventImage.sortingValue
media.EventImage.pooledMedium.PooledEventMedium
Nein Siehe Erläuterungen zu Bildern.
Metadaten
zu
Bildern
media.EventImage.pooledMedium.PooledEventMedium.title
media.EventImage.pooledMedium.PooledEventMedium.description
media.EventImage.pooledMedium.PooledEventMedium.copyright
media.EventImage.pooledMedium.PooledEventMedium.altText
media.EventImage.pooledMedium.PooledEventMedium.mediaLicense
copyright
ist
Pflichtfeld
Siehe Erläuterungen zu Bildern.
Abgesagt cancelled Nein true/false
Erstell-Datum creationTime Ja Voraussetzung für unsere Import-Strategie.
Änderungs-
Zeitstempel
lastChangeTime Ja Voraussetzung für unsere Import-Strategie.
2.2.2 Spielstätte
Attribut Name im xml Pflicht Beschreibung / Hinweis
FremdID* id Ja ID des zu importierenden Datensatzes
im Quell-System.

Die FremdID muss eindeutig im gesamten
Datenbestand im Quell-System sein.
Titel title Ja  
Postleitzahl contact1.address.zipcode Ja Die PLZ muß
innerhalb der
Metropolregion
Hamburg liegen.
Ort contact1.address.city Nein  
Straße contact1.address.street Ja  
Hausnummer contact1.address.streetNo Nein  
Geo-Koordinaten geoInfo.GeoInfo.coordinates.latitude
geoInfo.GeoInfo.coordinates.longitude
Nein  

*FremdID Spielstätte

  • Achtung, die FremdID darf nur dann aus Ziffern bestehen, wenn eine konkret bekannte bzw. passende ID des Zielsystems verwendet wird. Diese ID erhalten Sie von der Redaktion der VADB.
  • Andernfalls muss bei der Verwendung von Ziffern ein Präfix als ID-Zusatz eingesetzt werden, damit nicht fälschlicherweise eine falsche Spielstätte zur Veranstaltung zugeordnet wird. Beispiel: SHMH385

2.3 Erläuterungen

2.3.1 Lizenzen

Bei der Veranstaltung und bei jedem Bild kann ein Lizenztyp wie CC0, CC-BY usw. angegeben werden.

Im Zielsystem gibt es einen vorgegebenen Satz an Lizenztypen:

MediaLicense.id name
1 CC0
2 CC-BY
3 CC-BY-SA

2.3.2 Veranstaltungstermine

Jede Veranstaltung muss mindestens einen und kann beliebig viele Termine haben.

Attribut Name im xml Pflichtfeld Format/Einheit
Datum date Ja 00:00:00
Uhrzeit start Time Ja 00:00:00
Dauer duration Nein Minuten
Ausverkauft soldout Nein true/false
Abgesagt cancelled Nein true/false

2.3.3 Kategorien

Kategorien dienen der Einteilung von Veranstaltungen. Typische Kategorien sind z.B.:

  • Theater
  • Festivals
  • Klassik

Im Zielsystem gibt es einen vorgegebenen Satz an Veranstaltungskategorien, siehe Liste Veranstaltungskategorien.

Es gibt zwei Varianten für die Übertragung der Kategorien aus dem Quell-System:

  • 1) Das Quell-System liefert genau die passenden IDs der VADB (siehe VADB-Kategorienbaum)
  • 2) Die Redaktion der VADB erzeugt ein Mapping der Kategorien des Quell-Systems.
  • Bitte stellen Sie uns hierfür eine Liste Ihrer Kategorien samt IDs zur Verfügung. Dabei ist es unerheblich, ob die IDs des Quellsystems aus Ziffern bestehen oder nicht.

2.3.4 Merkmale

Merkmale dienen der Klassifizierung von Veranstaltungen zusätzlich zu den Kategorien. Typische Merkmale sind z.B.:

  • Kulinarisch
  • Speziell für Kinder oder Familien
  • Sprache: Englisch

Im Zielsystem gibt es einen vorgegebenen Satz an Veranstaltungsmerkmalen, siehe Liste Veranstaltungsmerkmale.

Es gibt zwei Varianten für die Übertragung der Merkmale aus dem Quell-System:

  • 1) Das Quell-System liefert genau die passenden IDs der VADB (siehe VADB-Merkmale)
  • 2) Die Redaktion der VADB erzeugt ein Mapping der Merkmale des Quell-Systems.
  • Bitte stellen Sie uns hierfür eine Liste Ihrer Merkmale samt IDs zur Verfügung. Dabei ist es unerheblich, ob die IDs des Quellsystems aus Ziffern bestehen oder nicht.

2.3.5 Termin-Meta-Tags

Termin-Meta-Tags dienen der Kennzeichnung von einzelnen Veranstaltungsterminen innerhalb eines Datensatzes. Typische Tags sind z.B.:

  • Premiere
  • Vernissage

Im Zielsystem gibt es einen vorgegebenen Satz an Termin-Meta-Tags, siehe hier.

05.02.: Das Zielsystem verfügt bereits über diese Tags. Der Event-Import muß für diese Daten noch erweitert werden.

2.3.6 Veranstaltungsreihen

Event-Reihen dienen dazu, die Zusammengehörigkeit von einzelnen Veranstaltungen zu einem großen Programm bzw. einer Aktion zu kennzeichnen.

Bitte erfragen Sie die für Sie relevanten IDs bei der Redaktion.

2.3.7 Preise

In der xml-Schnittstellendatei können folgende Preis-Elemente übergeben werden:

Attribut Format/Einheit
fromPrice Zahl
toPrice Zahl
absolutePrice Zahl
freeOfCharge Boolean (true/false)
priceDescription Text

2.3.8 Bilder

Aus der xml-Beispieldatei ergibt sich, wie die Bild-Informationen zu übergeben sind.

  • Das Feld imageType.ImageType.id soll immer mit dem Wert 1 (= Standard-Bild) gefüllt werden.
  • Das Feld sortingValue kann Werte von 0 bis 10 enthalten und steuert die Reihenfolge der Bilder (0 = Bild an erster Position, usw.)
  • Das Feld mediaLicense muss mit der korrekten Lizenz-ID gefüllt werden, siehe Tabelle Lizenzen.

Bilder ohne Copyright werden nicht übernommen.

2.4 Datenformat XML

Grundsätzlich dienen die bereitgestellten Beispiel-Dateien als Referenz und Arbeitsgrundlage.

Die Import-Dateien müssen exakt dieselbe Struktur haben wie die Beispiele.

Enthält eine Import-Datei zusätzliche Strukturelemente, die über die Elemente der Beispiele hinausgehen, so stört das den Import nicht. Diese zusätzlichen Daten werden aber auch nicht importiert.

Die Datenübernahme im XML-Format muss eine zentrale Datei liefern, welche sämtliche relevante Informationen zu den Spielstätten und Veranstaltungen liefert.