Stand: 20.01.2026
Technische Dokumentation des Standard-Importers
Über unsere standardisierte Schnittstelle können wir einfach und zuverlässig täglich aktuelle Veranstaltungsinformationen importieren.
Wichtig: Bitte validiere deine XML-Datei nach Erstellung mit der zugehörigen XSD-Datei – das spart dir und uns Zeit und vermeidet unnötigen Abstimmungsaufwand.
Inhalt
-
- 2.1 Datenmodell
- 2.1.1 Rahmenbedingungen
- 2.2 Datenstruktur
- 2.2.1 Veranstaltung
- 2.2.2 Spielstätte
- 2.3 Erläuterungen
- 2.3.1 Lizenzen
- 2.3.2 Veranstaltungstermine
- 2.3.3 Kategorien
- 2.3.4 Merkmale
- 2.3.5 Termin-Meta-Tags
- 2.3.6 Veranstaltungsreihen
- 2.3.7 Preise
- 2.3.8 Bilder
- 2.4 Datenformat XML
- 2.1 Datenmodell
Schnittstellen, die keine Veranstaltungen aus Hamburg enthalten, können nicht an unser System angebunden werden. Bitte wende dich in diesem Fall direkt an die zuständige Landesdatenbank von Niedersachsen, Schleswig-Holstein oder Mecklenburg-Vorpommern. Mehr Infos hier.
1. Basisinformationen
1.1 Daten bereitstellen
Es gibt zwei Möglichkeiten, die Daten zu übertragen:
- Stell uns eine URL, ggfs. mit Authentifizierung (Benutzername, Passwort) zur Verfügung, über die wir die Daten abrufen können.
- Lege 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:
- Liefere immer alle aktuell gültigen Datensätze aus deinem 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 dir schwer, diese Importstrategie zu unterstützen, so wende dich an deinen Ansprechpartner der VADB, um Alternativen zu vereinbaren.
1.3 Formate
Die Daten können in standardisiertem XML in die VADB importiert werden. Beim Punkt XSD Datei befindet sich ein Beispiel.
1.4 Kodierung
Die Dateien müssen im UTF-8-Format geliefert werden.
1.5 Objekttypen und fachliche Abhängigkeiten
- In der Veranstaltungsdatenbank (VADB) werden im Wesentlichen zwei zentrale Objekttypen verwendet: Veranstaltungen und Spielstätten.
- Der Objekttyp Veranstaltung dient der strukturierten Abbildung von Events einschließlich ihrer Terminlogik. Der Objekttyp Spielstätte beschreibt den physischen Veranstaltungsort und stellt eine zwingende Voraussetzung für die Veröffentlichung einer Veranstaltung dar.
- Jede Veranstaltung muss genau einer Spielstätte zugeordnet sein. Veranstaltungen ohne Spielstättenbezug sind nicht veröffentlichungsfähig.
- Finden an einer Spielstätte mehrere Termine derselben Veranstaltung statt, sind sämtliche Termine innerhalb eines gemeinsamen Veranstaltungsdatensatzes zu pflegen.
1.6. Basisentitäten
Bei der Befüllung der Event-Basisentitäten ist sicherzustellen, dass ausschließlich die fachlich korrekten IDs übermittelt werden. Die jeweils gültigen IDs sind entweder innerhalb dieses Dokuments verlinkt oder beim Team der Veranstaltungsdatenbank zu erfragen.
| Lizenztyp Datensatz | mediaLicense.MediaLicense |
| Kategorie | categories.Category |
| Merkmal | criteria.Criterion |
| Veranstaltungsreihe | series.EventSeries.id |
| Termin-Meta-Tags | eventDates.SpecificEventDate.tags.EventDateTag |
| Bild-Typ | media.EventImage.imageType |
| Bild-Sortierung | media.EventImage.sortingValue |
| Lizenztyp Bild | media.EventImage.pooledMedium.PooledEventMedium.mediaLicense |
2. Anforderungen
2.1 Datenmodell
Das Datenmodell in der imx.Platform enthält die Objekttypen:
- Veranstaltung (Event)
- Spielstätte (AddressPoi)
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 und alle Termine einer Veranstaltung müssen in einem Event-Datensatz abgebildet werden.
- Die Daten können einsprachig (deutsch) oder zweisprachig (deutsch, englisch) übergeben werden.
2.2 Datenstruktur
2.2.1 Veranstaltung (die Tabelle ist ggfls. nach rechts scrollbar!)
| Attribut | Name im xml | Pflicht | Beschreibung / Hinweis |
|---|---|---|---|
| FremdID | id | Ja | ID des zu importierenden Datensatzes im Quell-System. Die Fremd-ID muss im Quellsystem über den gesamten Datenbestand hinweg eindeutig sein. |
| Spielstätte | location.AddressPoi.id | Ja | Siehe auch 2.2.2 Spielstätte |
| PLZ der Spielstätte |
location.AddressPoi.contact1.address.zipcode | Ja | Zulässig sind ausschließlich Postleitzahlen aus Hamburg. Abweichungen sind vorab mit dem VADB-Team abzustimmen. |
| 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 | Zu befüllen mit dem Autor des Beschreibungstextes. |
| Lizenz | mediaLicense.MediaLicense | Nein | Lizenz-Typ des Beschreibungstextes Siehe Erläuterungen zu den Lizenzen 2.3.1. |
| Link zum Event |
link | Nein, aber wichtig |
Link, der zur Eventbeschreibungsseite des Veranstalters führt. Es sind nur URLs beginnend mit https:// oder http:// zugelassen. |
| Buchungslink | bookingLink | Nein | Es sind nur URLs beginnend mit https:// oder http:// zugelassen. |
| Kategorie | categories.Category | Ja | Sie Erläuterungen zu den Kategorien 2.3.3. |
| Merkmale | criteria.Criterion | Nein | Siehe Erläuterungen zu den Merkmalen 2.3.4. |
| Veranstaltungs- reihe |
series.EventSeries.id | Nein | Siehe Erläuterungen zu den Reihen 2.3.6. |
| Preise | pricing.fromPrice pricing.toPrice pricing.freeOfCharge pricing.priceDescription |
Nein | Siehe Erläuterungen zu Preisen 2.3.7. |
| 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 2.3.2. |
| Termin-Meta-Tags | eventDates.SpecificEventDate.tags.EventDateTag | Nein | Siehe Erläuterungen zu den Termin-Meta-Tags 2.3.5. |
| Bilder | media.EventImage media.EventImage.imageType media.EventImage.sortingValue media.EventImage.pooledMedium.PooledEventMedium |
Nein | Siehe Erläuterungen zu Bildern 2.3.8.. |
| 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 & AltText sind Pflichtfelder |
Siehe Erläuterungen zu Bildern 2.3.8. |
| Abgesagt | cancelled | Nein | Für die gesamte Veranstaltung mit allen Terminen. Inhalte: 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 Fremd-ID muss im gesamten Datenbestand des Quellsystems eindeutig sein. |
| Titel | title | Ja | |
| Postleitzahl | contact1.address.zipcode | Ja | Zulässig sind ausschließlich Postleitzahlen aus Hamburg. Abweichungen sind vorab mit dem VADB-Team abzustimmen. |
| 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 |
2.3 Erläuterungen
2.3.1 Lizenzen
| Attribut | Name im xml | Pflicht |
|---|---|---|
| Lizenz | mediaLicense.MediaLicense | Nein |
Sowohl der vollständige Veranstaltungsdatensatz als auch die jeweils zugeordneten Bilder können mit einem Lizenztyp versehen werden. Der Lizenztyp definiert den zulässigen Nutzungsumfang des Veranstaltungsdatensatzes sowie – sofern angegeben – der zugehörigen Bilder und kann über die in der Nutzungsvereinbarung der Veranstaltungsdatenbank festgelegten Rechte hinausgehen. Deshalb können auch nur diese drei offenen Lizenztypen gewählt werden:
| MediaLicense.id | name |
|---|---|
| 1 | CC0 |
| 2 | CC-BY |
| 3 | CC-BY-SA |
2.3.2 Veranstaltungstermine
| Attribut | Name im xml | Pflicht |
|---|---|---|
| Veranstaltungs- termine |
eventDates.SpecificEventDate.date eventDates.SpecificEventDate.startTime eventDates.SpecificEventDate.duration eventDates.SpecificEventDate.bookingLink eventDates.SpecificEventDate.cancelled eventDates.SpecificEventDate.soldout |
Ja |
Jede Veranstaltung muss mindestens einen und kann beliebig viele Termine haben. Dabei müssen sämtliche Termine einer Veranstaltung in einem Datensatz abgebildet werden.
| 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
| Attribut | Name im xml | Pflicht |
|---|---|---|
| Kategorie | categories.Category | Ja |
Kategorien dienen der Einteilung von Veranstaltungen. Jedem Datensatz kann immer genau nur EINE Kategorie zugeordnet werden. 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 stelle 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
| Attribut | Name im xml | Pflicht |
|---|---|---|
| Merkmale | criteria.Criterion | Nein |
Merkmale dienen der Klassifizierung von Veranstaltungen zusätzlich zu den Kategorien. Einem Datensatz können mehrere Merkmale zugeordnet werden. 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 stelle 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
| Attribut | Name im xml | Pflicht |
|---|---|---|
| Termin-Meta-Tags | eventDates.SpecificEventDate.tags.EventDateTag | Nein |
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.
2.3.6 Veranstaltungsreihen
| Attribut | Name im xml | Pflicht |
|---|---|---|
| Veranstaltungs- reihe |
series.EventSeries.id | Nein |
Veranstaltungsreihen dienen dazu, die Zusammengehörigkeit von einzelnen Veranstaltungen zu einem großen Programm bzw. einer Aktion zu kennzeichnen.
Bitte erfrage die für dich relevanten IDs bei der VADB Redaktion.
2.3.7 Preise
| Attribut | Name im xml | Pflichtfeld |
|---|---|---|
| Preise | pricing.fromPrice pricing.toPrice pricing.absolutePrice pricing.freeOfCharge pricing.priceDescription |
Nein |
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
| Attribut | Name im xml | Pflicht |
|---|---|---|
| 2.3.8 Bilder | media.EventImage media.EventImage.imageType media.EventImage.sortingValue media.EventImage.pooledMedium.PooledEventMedium |
Nein |
| 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 & AltText sind Pflichtfelder |
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. Seit der Einführung des Barrierefreiheitstärkungs-Gesetz (BFSG) ist auch der AltText verpflichtend!
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.
4. XSD Datei
- XML-Beispieldatei
- xsd-Datei zum Validieren des XML (aktualisierte Datei vom 09.12.2025)